,[****移动**对接方案]
,接口设计说明书
,版本:**.*
目录
概述
**业务场景汇总
需要**方提供的支持汇总:
*、***端业务场景
*.*登录
*.*数字签名
*.****端签章
*.*信封解密和文件对称解密
*、客户端接口说明
*.*登录
*.*标书加密
*.*客户端签章
概述
本文档用于移动(云)**在“****”平台上线的对接约定,根据我司的业务流程及
现有逻辑,制定的适合快速接入的标准,适用对象有:**方的产品、驱动开发、前端开
发、服务端开发等开发人员。
**业务场景汇总
业务场景 |
所属 |
登录 |
***端 |
绑定 |
***端 |
数字签名(需支持批量签名) |
***端 |
签章 |
***端 |
解密 |
***端 |
登录 |
客户端 |
标书加密 |
客户端 |
标书预解密 |
客户端 |
客户端签章 |
客户端 |
需要**方提供的支持汇总:
每个接口的具体细节将在后续场景中描述,这里仅做汇总
序号 |
功能 |
备注 |
是否满足 |
* |
(网络接口)创建登录*维码 |
登录、绑定场景共用 |
|
* |
(网络接口)查询登录*维码结果 |
用于获取证书和扫码人信息 |
|
* |
(网络接口)创建批量签名*维码的接口 |
|
|
* |
(网络接口)查询签名*维码结果 |
用于获取签名结果 |
|
* |
(驱动)获取驱动版本号 |
检查驱动是否已安装 |
|
* |
(驱动)签章控件(支持***和客户端签章、打开签章界面、支持用户拖拽、保存签章后的文件) |
***签章需要根据********地址上传签章后的文件到****平台 |
|
* |
(驱动)校验文件是否已盖章 |
|
|
* |
(驱动)文件加密 |
文件对称加密和信封非对称加密的组合接口,并在该驱动中集成加密*维码授权 |
|
* |
(驱动)加密文件预解密 |
确认加密文件可以被正确解密 |
|
** |
(网络接口)创建信封解密*维码 |
|
|
** |
(网络接口)查询解密*维码结果 |
对信封解密,得到对称密钥对文件进行解密 |
|
** |
(服务端***)文件解密 |
|
|
提示:*、*、**创建*维码可以合并成*个接口,传参“*******”区分,同
理*、*、**也可以合并,返回参数中增加“*******”区分,后文中不再提。
*、***端业务场景
*.*登录
在本场景中,合作**方需要提供*维码接口,和查询该*维码的扫码结果的
接口。**方提供*维码***,****弹窗展示*维码。
*.*.*登录*维码接口
输入参数:无
输出参数:
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
*** |
状态码****,非*为发生错误 |
|
|
******* |
****** |
错误信息 |
|
|
**** |
****** |
返回的数据,详细说明参考下面说明 |
|
|
****数据结构
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
****** |
*维码**** |
|
唯***,用于查询扫码结果 |
*** |
****** |
*维码的内容 |
|
****根据***画*维码 |
*.*.*获取扫码结果:
输入参数:
名称 |
类型 |
说明 |
**** |
****** |
*维码**** |
输出参数:
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
*** |
状态码****,非*为发生错误 |
|
|
******* |
****** |
错误信息 |
|
|
**** |
****** |
返回的数据,详细说明参考下面说明 |
|
|
****数据结构
名称 |
类型 |
说明 |
必填 |
备注 |
******** |
枚举 |
*维码状态 |
是 |
未扫码、待授权、已授权、已失效 |
****** |
****** |
证书序列号 |
否 |
|
****** |
****** |
唯*确认“机构证书+扫码人”唯*标识 |
是 |
*、标识是唯*到人,后续我们根据这个作为账号登录绑定的标记*、用户切换设备、更换证书等情况都不能有变化 |
名称 |
类型 |
说明 |
必填 |
备注 |
|
|
|
|
|
*************** |
****** |
机构名称 |
否 |
|
*********************** |
****** |
统*信用代码 |
是 |
|
************ |
****** |
扫码人姓名 |
是 |
|
********** |
**** |
扫码人在**方系统中的** |
否 |
|
*.*数字签名
*.*.*(批量)签名*维码接口
输入参数:
参数名 |
类型 |
说明 |
示例 |
备注 |
***** |
****
|
签名原文集合 |
{“***”,“***”} |
|
输出参数:
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
*** |
状态码****,非*为发生错误 |
|
|
******* |
****** |
错误信息 |
|
|
**** |
****** |
返回的数据,详细说明参考下面说明 |
|
|
****数据结构
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
****** |
*维码**** |
|
唯***,用于查询扫码结果 |
*** |
****** |
*维码内容 |
|
****根据***画*维码 |
*.*.*获取扫码结果:
输入参数:
名称 |
类型 |
说明 |
**** |
****** |
*维码** |
输出参数:
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
*** |
状态码****,非*为发生错误 |
|
|
******* |
****** |
错误信息 |
|
|
**** |
****** |
返回的数据,详细说明参考下面说明 |
|
|
名称 |
类型 |
说明 |
必填 |
备注 |
******** |
枚举 |
*维码状态 |
是 |
未扫码、待授权、已授权、已失效 |
****** |
****** |
唯*确认“机构证书+扫码人”唯*标识 |
是 |
*、标识是唯*到人,后续我们根据这个作为账号登录绑定的标记*、用户切换设备、更换证书等情况都不能有变化 |
********** |
****
|
签名结果 |
是 |
|
************ |
****** |
扫码人姓名 |
否 |
|
********** |
****** |
扫码人在**方系统中的** |
否 |
|
********:
名称 |
类型 |
说明 |
必填 |
备注 |
********** |
****** |
签名值 |
是 |
|
******** |
****** |
签名原文 |
是 |
|
*.****端签章
*.*.*需求
签章控件-基于*********(驱动)的*个页面,*******应用会以******方式打开签
章控件,**签章控件中需要内置弹窗*维码功能,当调用签章功能时,签章控件自动弹
窗授权*维码,经扫码授权后完成签章功能
*.*.*兼容性要求
支持******、****及以上、***、*******等主流浏览器。⚠注意:*********需要支持
*****;
*.*.*支持内置的功能
功能 |
描述 |
单页签 |
对***文件进行单页签章 |
多页签 |
用于***端对***文件进行多页签章、签章的页数范围可选 |
骑缝签 |
用于***端对***文件进行单页签章、签章的页数范围可选 |
暗章 |
交互同单页签,但章为固定章,章上固定文案暗标已盖章(@****提供暗章的图片) |
确认签章 |
***端签章,将签章文件上传到********。客户端签章,文件保存到指定的目录 |
****** |
是否暗章, |
否 |
**** |
默认非暗章模式;暗章模式:只支持暗章非暗章模式:支持除暗章外的其他盖章模式(单页、多页、骑缝) |
********的接口
请求:/***/**/****/*/********/****,
********的回调接口,我们会拼接在签章链接上,对接方需要自己获取
********表单提交
参数名称 |
类型 |
示列 |
说明 |
**** |
************* |
|
****:需要上传签章后的文件 |
********** |
**** |
{\"*****\":\"********************\"} |
*****:是我们业务上的唯*标书 |
返回参数
参数 |
类型 |
说明 |
******* |
******* |
请求是否成功,****为请求成功,*****为请求失败 |
****** |
******* |
返回结果,****为签章成功,*****为签章失败 |
******* |
错误的信息 |
异常的******* |
效果图:
下图展示所有可见的内容都为签章控件提供。
*.*信封解密和文件对称解密
**方提供*维码***,****弹窗展示*维码。
*.*.*信封解密*维码
描述:投标客户端对投标文件进行加密后得到信封,对该信封扫码解密获取加密时的对称
密钥,用对称密钥对文件进行解密;
输入参数:
名称 |
类型 |
示例 |
说明 |
备注 |
******** |
****** |
|
信封 |
|
输出参数:
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
*** |
状态码****,非*为发生错误 |
|
|
******* |
****** |
错误信息 |
|
|
**** |
****** |
返回的数据,详细说明参考下面说明 |
|
|
****数据结构
名称 |
类型 |
备注 |
**** |
****** |
*维码**** |
*** |
****** |
****根据***画*维码 |
*.*.*扫码结果
输入参数:
名称 |
类型 |
说明 |
备注 |
**** |
****** |
*维码**** |
|
输出参数:
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
*** |
状态码****,非*为发生错误 |
|
|
******* |
****** |
错误信息 |
|
|
**** |
****** |
返回的数据,详细说明参考下面说明 |
|
|
名称 |
类型 |
说明 |
必传 |
备注 |
******** |
枚举 |
*维码状态 |
是 |
未扫码、待授权、已授权、已失效 |
****** |
****** |
证书唯*标识 |
是 |
|
*********** |
****** |
解密结果(对称密钥) |
是 |
|
*.*.*文件解密
****调用**方***包实现解密,环境要求:
*****
解密依赖版本*******。
***.************
*.**
*、客户端接口说明
*.*登录
同***端登录
*.*.*获取驱动版本号接口
接口说明:获取驱动版本号,该接口由驱动提供,检测确认**驱动已安装
输入参数:无
输出参数:
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
*** |
状态码****,非*为发生错误 |
|
|
******* |
****** |
错误信息 |
|
|
**** |
****** |
驱动版本号 |
*.**.* |
|
*.*标书加密
标书加密分为*步:
(*)对文件进行加密,返回信封
(*)对加密文件进行预解密,保证加密后的文件能正常解密(信封解密、文件对称解
密)
*.*.*文件加密
调用驱动接口对文件进行加密,返回加密后的信封,操作人信息,加密使用的证书等信息
驱动接口说明:**驱动中需要内置弹窗*维码功能,当调用加密接口时,**驱动自动
弹窗授权*维码,经扫码授权后生成加密标书,返回信封和及其他信息;同时需要保证加
密后的文件能正常解密(建议在加密接口中内含对加密文件的预解密步骤以保证加密的文
件能正常解密)
输入参数
参数名 |
类型 |
说明 |
示例 |
备注 |
****** |
****** |
被加密文件地址 |
*:\****\*.*** |
|
******* |
****** |
加密完成后文件输出地址 |
*:\****\*-**.**** |
|
输出参数
参数名 |
类型 |
说明 |
示例 |
备注 |
**** |
*** |
状态码****,非*为发生错误 |
|
|
******* |
****** |
错误信息 |
|
|
**** |
****** |
返回的数据,详细说明参考下面说明 |
|
|
****数据结构
参数名 |
类型 |
说明 |
示例 |
备注 |
******** |
****** |
文件加密得到的信封 |
|
|
************ |
****** |
操作人姓名 |
|
该信息用于记录在标书里留档 |
************** |
****** |
操作人手机号 |
|
该信息用于记录在标书里留档 |
******** |
****** |
加密使用的证书名称 |
|
该信息用于记录在标书里留档 |
******** |
****** |
加密证书单位名称 |
|
该信息用于记录在标书里留档 |
参数名 |
类型 |
说明 |
示例 |
备注 |
****** |
****** |
加密使用的证书序列号(当解密遇到问题可以说明文件是使用说明是用该证书加密的) |
|
该信息用于记录在标书里留档 |
*********************** |
****** |
统*社会信用代码 |
|
该信息用于记录在标书里留档 |
*.*客户端签章
*.*.*需求
提供基于*********(驱动)签章控件
提供基于*********(驱动)验签接口
****投标客户端这边会以*******的形式展示签章控件。
**签章控件中需要内置弹窗*维码功能,当调用签章功能时,签章控件自动弹窗授权*
维码,经扫码授权后完成签章功能
*.*.*兼容性要求
支持********浏览器(****投标客户端的技术栈为********,*******基于
********)
*.*.*签章控件内置功能
功能 |
描述 |
单页签 |
对***文件进行单页签章 |
多页签 |
用于客户端对***文件进行多页签章、签章的页数范围可选 |
骑缝签 |
用于客户端对***文件进行单页签章、签章的页数范围可选 |
暗章 |
交互同单页签,但章为固定章,章上固定文案暗标已盖章(@****提供暗章的图片) |
确认签章 |
***端签章,将签章文件上传到********。客户端签章,文件保存到指定的目录 |
通信:**方需提供本地签章服务地址,****将通过访问如下格式***调用签章服务:
{本地签章服务地址}?*******={本地待签章文件地址}&***;********={签章完成后文件保存地
址}&***;********={签章类型,客户端签章类型为'*****'}
具体参数说明如下:
参数 |
说明 |
必填 |
参数示例 |
备注 |
******** |
保存类型是 |
|
***** |
***:保存到****;*****:保存到本地地址;当是***端签章值为***,客户端签章值为*****如果*********:****服务是只针对***端签章,可忽略 |
******* |
签章文件的地址 |
是 |
*****://*******.******.***/***-******/********-****-****-****-************.*** |
如果是********是*****,该参数为本地文件地址,例如:*:\****.***;*******会使用******************进行编码,此处示例未编码。 |
***** |
本次签章的*****,保存回传到********对应的上传签章接口 |
否 |
******************* |
如果是********是*****,该参数可不传 |
******** |
用户点击签章完成,签章文件上传到此接口 |
是 |
*****://******.******.**/***/**/****/*/********/**** |
如果是********是*****,********为本地地址,例:*:\*****.*** |
****** |
是否暗章, |
否 |
**** |
默认非暗章模式;暗章模式:只支持暗章非暗章模式:支持除暗章外的其他盖章模式(单页、多页、骑缝) |
⚠注意:客户端保存成功后触发******事件,投标客户端会监听*******的******
事件,然后投标客户端会调用验签接口,对文件进行验证是否签章成功
验签接口说明:基于*********(驱动)的****请求
请求类型:****
输入参数
参数 |
参数说明 |
是否必传 |
参数示例 |
******** |
需要验签的文件的本地路径 |
是 |
*:\****\*****.*** |
返回参数
参数 |
类型 |
说明 |
**** |
*** |
状态码****,非*为发生错误 |
******* |
****** |
错误信息 |
**** |
******* |
正确为****,错误为***** |
客户端签章效果图:
*.*.*签章对接其他要求
(*)交互友好、体验流畅
(*)异常处理:对于签章异常能给出友好明确的提示
(*)签章文件大小的支持,客户端支持****的***签章,***端:***的***文件
签章
(*)签章操作不能每*次都要求用户扫*维码授权,原因:签章为某*时间段内某个用
户的的高频操作,需要有【记住密码】的功能或者【*定时间段内默认记住密码】,不需
要用户重复进行扫码授权