文件发起方案
一、适用场景
该方案适用于医院内部系统中集成电子签名功能，从而实现患者单方在线签署知情同意书等文件。
二、接入准备
在开始接入腾讯电子签之前，需要进行一些准备工作。参考以下内容：
企业自动签署使用说明【可选】
三、交互流程
- 分别调用【多文件上传】、【用PDF文件创建签署流程】接口完成流程的发起;
- 通过短信 或者 通过【获取小程序签署链接】得到的签署链接, 通知C端用户进入电子签进行签署;
- 签署完成后, 电子签系统会通过回调机制通知开发者系统; 此时再调用【查询文件下载URL】获取下载链接, 进行下载归档。
核心接口
1、 多文件上传
UploadFiles 上传准备好的文件以备后续签署。需要注意的是，文件发起后不支持再往文件里面填写内容。
2、 用 PDF 文件创建签署流程
CreateFlowByFiles 使用上传文件接口返回的文件编号，发起一个签署流程。
可参考参数如下：
// 单C签署、关键字定位
{
"Approvers" : [{
"ApproverMobile" : "189********", // 签署方手机号
"ApproverName" : "张三", // 签署方姓名
"ApproverType" : 1, // 签署方类型, 1-个人
"NotifyType" : "NONE", // 通知方式, SMS-由电子签发送短信通知 NONE-不发送短信
"SignComponents" : [{
"ComponentHeight" : 100, // 签署区高度
"ComponentWidth" : 100, // 签署区宽度
"ComponentId" : "签字人", // 关键字
"ComponentType" : "SIGN_SIGNATURE", // 签名
"GenerateMode" : "KEYWORD", // 签署区定位方式, KEYWORD-关键字
"RelativeLocation" : "Right" // 关键字位置模式, Right-正右方
}]
}],
"FileIds" : [
"yDw****************7ZHf" // 上传文件得到的文件FileId
],
"FlowName" : "合同名", // 签署文件名
"Operator" : {
"UserId" : "****************ZVF3f" // 操作人的电子签用户Id, 可以从电子签控制台组织架构中获取
}
}
3、 获取小程序签署链接【可选】
如果在上一步设置了不发送短信，可以使用CreateSchemeUrl接口，设置不同的 EndPoint，以获得跳转小程序签署的不同方式。
其中小程序的原始 Id 如下，或者查看小程序信息自助获取。
| 小程序 | AppID | 原始 ID |
|---|---|---|
| 腾讯电子签（正式版） | wxa023b292fd19d41d | gh_da88f6188665 |
| 腾讯电子签 Demo | wx371151823f6f3edf | gh_39a5d3de69fa |
4、 查询文件下载 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": 1, // 签署方类型
}]
}
}
五、联调环境
在联调测试环境建议使用腾讯电子签测试环境，相关的域名如下：
测试环境接口请求域名（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
