文件发起方案
一、适用场景
此方案适用于企业通过第三方应用平台系统集成电子签名功能，从而实现线上办理采购业务，签署采购合同。
二、接入准备
在开始接入腾讯电子签之前，需要进行一些准备工作。参考以下内容：
第三方应用平台企业注册腾讯电子签 接入准备
子客企业通过第三方平台的入口注册腾讯电子签 子客企业认证
三、交互流程
- 分别调用【文件上传】、【通过文件创建签署流程】接口完成流程的发起;
- 通过短信 或者 通过【获取跳转小程序查看或签署链接】得到的签署链接, 通知B端企业用户进入电子签进行签署;
- 签署完成后, 电子签系统会通过回调机制通知开发者系统; 此时再调用【根据签署流程信息批量获取资源下载链接】获取下载链接, 进行下载归档。
核心接口
1、 文件上传
UploadFiles 上传准备好的文件以备后续签署。需要注意的是，文件发起后不支持再往文件里面填写内容。
2、 用 PDF 文件创建签署流程
ChannelCreateFlowByFiles 使用上传文件接口返回的文件编号，发起一个签署流程。
可参考参数如下：
// B2B签署、关键字定位
{
"FlowApprovers" : [
{
"ApproverType": "ORGANIZATION", // 签署方类型, ORGANIZATION-企业
"OrganizationOpenId": "ProxyOrganizationOpenId", // 第三方平台子客企业的唯一标识
"OpenId": "OpenId" // 三方平台子客企业员的唯一标识
"SignComponents" : [{
"ComponentHeight" : 100, // 签署区高度
"ComponentWidth" : 100, // 签署区宽度
"ComponentId" : "甲方", // 关键字
"ComponentType" : "SIGN_SEAL", // 印章
"GenerateMode" : "KEYWORD", // 签署区定位方式, KEYWORD-关键字
"RelativeLocation" : "Right" // 关键字位置模式, Right-正右方
}]
},
{
"NotChannelOrganization": true, // 签署企业非子客企业
"ApproverType": "ORGANIZATION", // 签署方类型, ORGANIZATION-企业
"OrganizationName": "企业名", // 签署方企业名
"Mobile" : "188********", // 签署方手机号
"Name" : "王五", // 签署方姓名
"SignComponents" : [{
"ComponentHeight" : 100, // 签署区高度
"ComponentWidth" : 100, // 签署区宽度
"ComponentId" : "乙方", // 关键字
"ComponentType" : "SIGN_SEAL", // 印章
"GenerateMode" : "KEYWORD", // 签署区定位方式, KEYWORD-关键字
"RelativeLocation" : "Right" // 关键字位置模式, Right-正右方
}]
}
],
"FileIds" : [
"yDw****************7ZHf" // 上传文件得到的文件FileId
],
"FlowName" : "合同名", // 签署文件名
"Agent": {
"ProxyOrganizationOpenId": "ProxyOrganizationOpenId", // 第三方应用平台自定义, 对应第三方平台子客企业的唯一标识
"ProxyOperator": {
"OpenId": "OpenId" // 第三方应用平台自定义, 对应第三方平台子客企业员的唯一标识
},
"AppId": "AppId" // 应用的唯一标识。不同的业务系统可以采用不同的AppId, 不同AppId下的数据是隔离的。可以由控制台开发者中心-应用集成自主生成
}
}
3、 获取跳转小程序查看或签署链接【可选】
除了短信通知，也可以使用CreateSignUrls接口，设置不同的 EndPoint，以获得跳转小程序签署的不同方式。
其中小程序的原始 Id 如下，或者查看小程序信息自助获取。
| 小程序 | AppID | 原始 ID |
|---|---|---|
| 腾讯电子签（正式版） | wxa023b292fd19d41d | gh_da88f6188665 |
| 腾讯电子签 Demo | wx371151823f6f3edf | gh_39a5d3de69fa |
4、 根据签署流程信息批量获取资源下载链接
DescribeResourceUrlsByFlows 查询签署文件的下载链接，建议使用接收回调的方式接收完成签署的信号，再调用此接口获取下载链接，未完成签署就获取链接会导致取到的是中间状态的文件，例如不包含签署印章。
注意：下载合同文件需要提前开通下载应用内全量合同文件及内容数据。
四、回调通知
1、回调通知功能说明
回调通知的说明文档请参考：回调通知功能说明
2、签署完成回调
当发起的流程完成签署后，将会触发此回调，全部字段说明链接
{
"MsgId": "yDwf******************nIf",
"MsgType": "FlowStatusChange",
"MsgData": {
"ApplicationId": "yDw*************ea",
"ProxyOrganizationOpenId": "ProxyOrganizationOpenId",
"CustomerData": "",
"FlowId": "yD*************oF",
"FlowName": "合同名",
"FlowType": "",
"FlowStatus": "ALL",
"FlowMessage": "",
"CreateOn": 1682407518,
"Deadline": 1713943518,
"FlowApproverInfo": [
{
"ProxyOperatorOpenId":"",
"ProxyOrganizationOpenId": "",
"ProxyOrganizationName": "子客企业名2",
"RecipientId": "yD**********v0w",
"PhoneNumber": "189********",
"SignOrder": 1,
"ApproveName": "张三",
"ApproveStatus": "ACCEPT",
"ApproveMessage": "",
"ApproveTime": 1682408194,
"CaSign": ""
},
{
"ProxyOperatorOpenId":"",
"ProxyOrganizationOpenId": "",
"ProxyOrganizationName": "子客企业名1",
"RecipientId": "yD**********v0w",
"PhoneNumber": "188********",
"SignOrder": 1,
"ApproveName": "王五",
"ApproveStatus": "ACCEPT",
"ApproveMessage": "",
"ApproveTime": 1682408194,
"CaSign": ""
}
],
"OccurTime": 1682408494,
"CcInfo": []
}
}
五、联调环境
在联调测试环境建议使用腾讯电子签测试环境，相关的域名如下：
测试环境接口请求域名（EndPoint）
essbasic.test.ess.tencent.cn
文件上传域名 - UploadFiles接口使用
file.test.ess.tencent.cn
平台企业控制台域名
https://beta.qian.tencent.cn
联调测试环境完成调试验证后，发布到生产环境需要修改相关的域名，如下：
生产环境接口请求域名（EndPoint）
essbasic.tencentcloudapi.com
文件上传域名 - UploadFiles接口使用
file.ess.tencent.cn
平台企业控制台域名
https://qian.tencent.com