1. 简介
微签SaaS Web API互签接口通过调用微签SaaS云端接口实现。
此接口适用于企业方与个人的线上签署场景，如人事合同、确认单、旅游/教培/法律服务行业的合同协议等。
互签接口可以与Web、APP、小程序等业务系统或平台对接。业务系统平台准备好签署的文件后，只需调用互签接口，甲方双方即可在线签署同一份合同。
2. 开发前准备
2.1. 接口请求说明
(1) 字符编码
均使用UTF-8编码
(2) 时间戳说明
所有参数中使用的时间戳签都使用“Unix标准时间戳”。
“Unix标准时间戳”是指从1970年1月1日(UTC/GMT的午夜)开始所经过的毫秒数。
(3) 请求方法
如果无特殊说明，总是使用POST方法。
POST 请求支持的 Content-Type 类型：
l application/x-www-form-urlencoded
l multipart/form-data (仅涉及文件流操作接口支持)
(4) 公共请求参数
(5) 公共响应参数
2.2. 请求签名Sign生成方法
为保证API调用过程的安全可靠，微签平台webapi接口在调用前首先进行鉴权，采用对请求数据进行签名的方式实现安全接入，防止请求过程数据被篡改或盗用。
(1) 请求签名鉴权前准备
第三方请先向复园商务人员获取APP ID和APP SECRET。
(2) 参数筛选并排序
对公共请求参数（不包括Sign字段），不包括字节流型参数(如文件流、字节流)，并按照参数键值ASCII码递增排序(字母升序排序)。
(3) 参数拼接
将上述筛选和排序后的参数与其对应值，组合成“参数名=参数值(Key=Value)”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。
(4) 计算签名
使用APPSECRET对第三步拼接后的字符串采用HMAC-SHA256算法进行签名运算，最后经过Base64编码从而得到签名字符串。
2.3. 请求签名鉴权示例代码
3. API文档
3.1. 接口调用流程说明:
1. 首先调用 互签文件上传 接口获取文件的bId
2. 如果需要指定发起人和接收人的指定盖章位置坐标，可调用 接口3路径，获取盖章位置，其位置参数需要添加到步骤3中。
3. 创建互签的接口，传递相应的参数，获取返回参数。返回参数有两种
a. 互签发给一个人:则返回bId(互签业务id)和shortCode(互签短链码)
b. 互签发给多个人：则返回shortCode(互签短链码)childShortUrl(多人互签相关数据，其中包含多个不同的bId)
互签发给一个人，则发起人可通过bId进行签章，接收人通过shortCode进行签章。
互签发给多个人，发起人可通过返回多人互签相关数据，其中包含多个bId.中的其中一个bId进行签章，接收人通过shortCode进行签章。
发起人调用接口为 eachSign/getSignPage 进行签章
接收人调用接口为(接收人签章接口和其他接口有些许不同) q/{shortCode} 进行签章
如:http://forwave.picp.net:8888/q/{shortCode}
4. 接收者签章完成，根据配置可跳转默认页面或跳转配置后的路径。
以下接口都有具体java的调用demo,具体demo可查看提供的demo程序。
步骤3参数补充说明:签章id可在PC端的系统管理的签章管理里面查询，公司id可在系统管理的应用管理里面查询
接口前缀说明:
测试环境的apiUrl为 http://forwave.picp.net:8888/openapi/v1/
正式环境的apiURL为 https://www.weiqian.com.cn:8887/openapi/v1/
系统简称为微签(其测试接口前缀为:http://forwave.picp.net:8888/openapi/v1/)
接口如下：
3.2. 上传签章文件接口
接口描述：上传互签的签章文件
1.请求接口
A. 上传文件 eachSign/upload
2.上传文件请求信息
POST：
RequestBody：
{
“file”: “文件的数据流”,
}
ResponseBody：
{
code:10000,
msg:”返回消息varchar(200)”,
data:”响应数据,可能没有值(文件的业务id bId)”,
timestamp:时间戳
}
2.关键数据类型
3.3. 微签创建互签任务接口
接口描述：其他系统调用此接口后，将在微签创建一个互签任务，如果需要此任务，需要先调用上传文件接口，再调用此接口。
1.请求信息
POST：
RequestBody：
{
“launchAccount”: “发起者账号”,
“cId”: “发起者公司ID”,
“fBIds”: “发起者文件业务ID列表”,
“rType”: “接收者类型 1:个人 2:公司”,
“authType”: “授权类型 1:手机验证码 2:实名认证”,
“expiresTime”: “互签过期时间”,
“finishSignJumpPage”: “接收者签章完成跳转页面”,
“parm”: “跳转页面携带的额外参数”,
“receiverDTOS”: [{
“account”: “接收者账号”,
“rName”: “接收者名字”,
“idCard”: “接收者身份证号”,
“rCName”: “接收者公司名”
}],
” positionDTOS”: [{
“x”: “接收人指定位置x坐标”,
“y”: “接收人指定位置y坐标”,
“pageNum”: “接收人指定盖章页数”
}],
“launcherSignRule”: [{
“autosealType”: “自动盖章类型 1单页盖章、2多页盖章”,
“sealId”: “发起者自动固定盖章的章id”,
“x”: “发起者自动盖章的x坐标”,
“y”: “发起者自动盖章的y坐标”,
“autosealPage”: “发起者自动盖章页数”
}]
}
ResponseBody：
{
code:10000,
msg:”返 回 消 息 varchar(200)”,
data:”响应数据,可能没有值”,
timestamp:时间戳
}
2.关键数据类型
3.4. 发起人签章接口或者公共签章接口
接口描述：其他系统调用此接口后，将返回一个互签链接，手机打开此链接后可正常签署。
1.请求信息
POST：
RequestBody：
{
“signType”: “签署类型 basicFileType ,eachSignType”,
“fBId”: “发起者文件业务ID”,
“bBId”: “互签的业务ID”,
“account”: “签署人账号”,
“password”: “签署人密码”
}
ResponseBody：
{
code:10000,
msg:”返 回 消 息 varchar(200)”,
data:”响应数据,可能没有值”,
timestamp:时间戳
}
2.关键数据类型
3.5. 下载文件
接口描述：其他系统调用此接口后，可获取互签的文件字节流
1.请求信息
POST：
RequestBody：
{
“bId”: “互签的业务ID”
}
ResponseBody：
{
code:10000,
msg:”返 回 消 息 varchar(200)”,
data:”响应数据,可能没有值”,
timestamp:时间戳
}
2.关键数据类型
3.6. 删除文件
接口描述：其他系统调用此接口后，将删除互签文件
1.请求信息
POST：
RequestBody：
{
“bId”: “互签的业务ID”
}
ResponseBody：
{
code:10000,
msg:”返 回 消 息 varchar(200)”,
data:”响应数据,可能没有值”,
timestamp:时间戳
}
2.关键数据类型
4. API返回码
4.1. 常见HTTP状态码及处理方式
4.2. 公共错误码
4.3. 业务错误码-鉴权
4.4. 业务错误码-用户管理
4.5. 业务错误码-部门管理
4.6. 业务错误码-文件上传
4.7. 业务错误码-审批任务
5. 技术支持
如果您在使用中遇到问题，请仔细阅读此用户手册。如果仍不能解决问题，请与上海复园电子科技有限公司技术部取得联系，我们将为您提供及时、周到的服务。
上海复园电子科技有限公司
地址：上海市国定路335号2号楼20层
电话：021-65654240转技术支持
E-mail：support@forwave.com
网址：www.forwave.com
苏公网安备 32059002002276号
