模板发起方案
一、适用场景
此方案适用于业务系统中集成电子签名功能，从而实现线上办理采购业务，签署采购合同。
二、接入准备
在开始接入腾讯电子签之前，需要进行一些准备工作。参考以下内容：
企业自动签署使用说明【可选】
三、交互流程
- 通过电子签控制台配置模板, 得到模板ID后; 分别调用【创建签署流程】、【创建电子文档】、【发起签署流程】接口完成流程的发起;
- 通过短信 或者 通过【获取小程序签署链接】得到的签署链接, 通知B端企业用户进入电子签进行签署;
- 签署完成后, 电子签系统会通过回调机制通知开发者系统; 此时再调用【查询文件下载URL】获取下载链接, 进行下载归档。
核心接口
1、 模板发起合同-创建电子文档
CreateFlow 创建一个签署流程，此时需要指定流程的名称，签署方的信息。
可参考参数如下：
// B2B签署
{
"Approvers" : [{
"ApproverType": 0, // 签署方类型, 0-企业
"OrganizationName": "企业名1", // 签署方企业名
"ApproverName": "张三", // 签署方姓名
"ApproverMobile": "189********", // 签署方手机号
},{
"ApproverType": 0, // 签署方类型, 0-企业
"OrganizationName": "企业名2", // 签署方企业名
"ApproverName": "李四", // 签署方姓名
"ApproverMobile": "188********", // 签署方手机号
}],
"FlowName" : "合同名", // 签署文件名
"Operator" : {
"UserId" : "****************ZVF3f" // 操作人的电子签用户Id, 可以从电子签控制台组织架构中获取
}
}
2、 模板发起合同-创建电子文档
CreateDocument 传入指定的模板编号和内容创建签署流程文档，这个文档将用于签署。
3、 模板发起合同-发起签署流程
StartFlow 确认开始签署，签署完成后会有相应的回调通知。
4、 获取小程序签署链接【可选】
如果在上一步设置了不发送短信，可以使用CreateSchemeUrl接口，设置不同的 EndPoint，以获得跳转小程序签署的不同方式。
其中小程序的原始 Id 如下，或者查看小程序信息自助获取。
| 小程序 | AppID | 原始 ID |
|---|---|---|
| 腾讯电子签（正式版） | wxa023b292fd19d41d | gh_da88f6188665 |
| 腾讯电子签 Demo | wx371151823f6f3edf | gh_39a5d3de69fa |
5、 查询文件下载 URL
DescribeFileUrls 查询签署文件的下载链接，建议使用接收回调的方式接收签署完成的信号，再调用此接口获取下载链接。如果在签署完成之前获取链接，可能会取到中间状态的文件，例如不包含签名。
四、回调通知
1、回调通知功能说明
回调通知的说明文档请参考：回调通知功能说明
2、签署完成回调
当发起的流程完成签署后，将会触发此回调，全部字段说明链接
{
"MsgId":"xxx",
"MsgType":"FlowStatusChange",
"MsgVersion":"CustomApp",
"MsgData":{
"CallbackType": "sign", // sign: 签署回调，具体参考文档
"CreateOn": 1691656285, // 流程发起时间
"DeadLine": 1723192285, // 流程过期时间
"FlowCallbackStatus": 4, // 流程现在的状态，具体参考文档
"FlowDescription": "", // 流程描述信息
"FlowId": "123", // 流程唯一编号
"FlowName": "123", // 流程名称
"Operate": "sign", // sign: 签署完成，具体参考文档
"UserData": "", // 自定义数据
"Approvers": [{
"ApproveCallbackStatus": 3, // 当前签署方签署状态，具体参考文档
"ApproveMessage": "", // 拒签的原因，非拒签为空
"ApproveTime": 1691656288, // 签署或拒签时间
"ApproverIdCardNumber": "123", // 签署方证件号码
"ApproverIdCardType": "ID_CARD", // 签署方证件类型
"ApproverIdCardTypeDesc": "居民身份证", // 签署方证件描述
"ApproverMobile": "123", // 签署方手机号码
"ApproverName": "123", // 签署方中文姓名
"ApproverType": 3, // 签署方类型
"OrganizationName": "企业名1" // 企业名
},{
"ApproveCallbackStatus": 3, // 当前签署方签署状态，具体参考文档
"ApproveMessage": "", // 拒签的原因，非拒签为空
"ApproveTime": 1691656288, // 签署或拒签时间
"ApproverIdCardNumber": "123", // 签署方证件号码
"ApproverIdCardType": "ID_CARD", // 签署方证件类型
"ApproverIdCardTypeDesc": "居民身份证", // 签署方证件描述
"ApproverMobile": "123", // 签署方手机号码
"ApproverName": "123", // 签署方中文姓名
"ApproverType": 3, // 签署方类型
"OrganizationName": "企业名2" // 企业名
}]
}
}
五、联调环境
在联调测试环境建议使用腾讯电子签测试环境，相关的域名如下：
测试环境接口请求域名（EndPoint）
ess.test.ess.tencent.cn
文件上传域名 - UploadFiles接口使用
file.test.ess.tencent.cn
企业控制台域名
https://beta.qian.tencent.cn
联调测试环境完成调试验证后，发布到生产环境需要修改相关的域名，如下：
生产环境接口请求域名（EndPoint）
ess.tencentcloudapi.com
文件上传域名 - UploadFiles接口使用
file.ess.tencent.cn
平台企业控制台域名
https://qian.tencent.com
