模板发起方案
一、接入说明
只需三步，即可完成通过模板发起的方式接入腾讯电子签电子处方单签署服务：
第一步：当医生或药师登录 HIS、EMR、PACS、LIS 等院内系统时，我们先确认医生或药师是否已开通腾讯电子处方单自动签署；如果没有则调用腾讯电子签接口生成自动签署开通链接，然后医生或药师通过扫描二维码打开腾讯电子签小程序或短信链接或院内的 APP 嵌入腾讯电子签 H5 等方式，按指引完成自动签署功能的开通，完成后会通过回调机制通知到院内系统；
第二步：当医生完成电子处方单开具，相应的药师（支持多个）完成审核后，调用腾讯电子签接口传入要使用的模板编号及对应的内容通过模板发起电子处方单的接口发起签署流程，之后腾讯电子签系统会自动完成医生和药师的数字签名；这一签署过程对医生和药师都是无感的，确保了良好的体验同时满足合规和监管的要求；
第三步：当腾讯电子签系统自动完成签署操作后，会通过回调机制通知到院内系统；此时再调用腾讯电子签下载链接查询接口获取电子处方单下载链接，再通过 HTTP 协议下载电子处方文件并归档；
二、接入准备
在开始做腾讯电子签接入之前，需要做一些准备工作，参考以下内容：
三、交互流程
1、核心接口
只需要接入核心接口即可完成电子处方单的签署和下载。
| 接口名称 | 接口说明 |
|---|---|
| CreateUserAutoSignEnableUrl | 获取微信小程序或 H5 链接，用于医生和药师开通自动签署；开通后发起对应医生和药师的电子处方单才会自动签署，否则需要人工签署；当医生或药师通过链接完成自动签署开通后会触发回调通知。 示例代码 |
| CreateFlow | 首先，通过 CreateFlow 接口创建一个签署流程，此时需要指定流程的名称，签署的医生和药师等信息，如果希望发起之后医生或药师自动完成签署，需要先调接口获取自动签署开通的链接发给医生和药师先完成自动签署的开通。 注意： 需要设置发起参数中 ApproverType 为 7 AutoSignScene 为 E_PRESCRIPTION_AUTO_SIGN 示例代码 |
| CreateDocument | 然后，通过 CreateDocument 接口传入指定的模板编号和内容创建电子处方文档，这个文档将用于签署。 示例代码 |
| StartFlow | 最后，通过 StartFlow 接口确认开始签署，签署完成后会通过回调通知到院内系统。 示例代码 |
| CreateFlowSignReview | 如果希望医生或药师在审批之后才能自动签署，在发起合同时需设置相应签署方的ApproverNeedSignReview字段为true使其签署阻塞。医生/药师审批之后再通过CreateFlowSignReview接口通知电子签放开阻塞。 |
| DescribeFileUrls | 查询电子处方单的下载链接，建议使用接收回调的方式接收医生和药师完成签署的信号，再调用此接口获取下载链接，未完成签署就获取链接会导致取到的是中间状态的文件，例如不包含签署印章。 示例代码 |
2、附加接口
附加的接入协助辅助流程的完成及异常流的处理。
| 接口名称 | 接口说明 |
|---|---|
| CancelUserAutoSignEnableUrl | 撤销已经生成的医生或药师的自动签署开通链接，撤销后原链接将即时失效，如果需要可以调用获取链接接口重新生成链接；注意如果已经完成开通将无法完成撤销，此时需要调用关闭自动签署接口做关闭操作。 示例代码 |
| DescribeUserAutoSignStatus | 查询指定的医生或药师是否完成自动签署的开通；除了调用本接口查询外，建议使用接收回调的方式接收医生和药师的开通信号。 示例代码 |
| CreateUserAutoSignSealUrl | 获取设置自动签印章小程序链接；通过调用此接口可以获取更换自动签印章链接，更换后新发起的电子处方单将自动使用更换后的印章完成签署。 |
| DisableUserAutoSign | 关闭医生或药师的自动签署功能，关闭后再发起的电子处方单将不会自动完成签署，而是需要人工打开并查阅电子处方单并做签署操作。 示例代码 |
| CreatePersonAuthCertificateImage | 查询医生或药师的个人用户证书证明图片，一般用于监管上传使用；需要指定的医生或药师完成了自动签署功能开通后才能查询，否则将返回未开通错误。 示例代码 |
| CreatePreparedPersonalEsign | 提前导入医生或药师的签名图片，如果医生或药师已经在贵司平台采集过签署图片将希望继续使用，可通过此接口提前导入，开通自动签署后将使用导入的签名图片做签署；需要在开通自动签署之前调用接口完成导入，开通后再导入将不生效；重复调用接口多次导入以最后一次为准；签名图片建议不超过 120*120 像素同时大小不超过 200KB； 示例代码 |
四、回调通知
1、回调通知功能说明
回调通知的说明文档请参考：回调通知功能说明
2、开通自动签署回调
当医生或药师完成自动签署的开通操作后会触发此通知，通知内容参考：
{
"MsgId": "12345",
"MsgType": "OpenUserAutoSign",
"MSgVersion": "CustomApp",
"MsgData": {
"Name":"string", // 开通自动签用户姓名
"IdCardNumber":"string", // 开通自动签用户证件号码
"IdCardType":"string", // 开通自动签用户证件类型
"SceneKey": "string", // 开通自动签场景，处方单场景为 E_PRESCRIPTION_AUTO_SIGN
"IsSuccess":true, // 是否成功
"LicenseFrom":1684413039, // 自动签 license 开始时间
"LicenseTo":1684413040, // 自动签 license 过期时间
"OrgInfo": { // 开通自动签的企业信息
"OrganizationId": "string", // 集成企业ID
"ProxyOrganizationId": "string", // 集团主企业ID
"OrganizationOpenId": "string", // 集成企业OpenID
"ProxyOrganizationOpenId": "string" // 集团主企业OpenID
}
}
}
3、创建自动签署印章签名回调
当医生或药师完成自动签署的开通后，在腾讯电子签创建个人自动签署签名时触发此回调
{
"MsgId": "12345",
"MsgType": "AutoSignSealImg",
"MSgVersion": "CustomApp",
"MsgData": {
"Name":"string", // 开通自动签用户姓名
"IdCardNumber":"string", // 开通自动签用户证件号码
"IdCardType":"string", // 开通自动签用户证件类型
"SceneKey": "string", // 开通自动签场景，处方单场景为 E_PRESCRIPTION_AUTO_SIGN
"ESignFileContent":"string", // 用户自动签使用的签名图片内容，格式为base64编码
"OrgInfo": { // 开通自动签的企业信息
"OrganizationId": "string", // 集成企业ID
"ProxyOrganizationId": "string", // 集团主企业ID
"OrganizationOpenId": "string", // 集成企业OpenID
"ProxyOrganizationOpenId": "string" // 集团主企业OpenID
}
}
}
4、关闭个人用户自动签署功能回调
当企业调用关闭个人用户自动签功能接口时触发此回调
{
"MsgId": "12345",
"MsgType": "DisableUserAutoSign",
"MSgVersion": "CustomApp",
"MsgData": {
"Name":"string", // 关闭自动签用户姓名
"IdCardNumber":"string", // 关闭自动签用户证件号码
"IdCardType":"string", // 关闭自动签用户证件类型
"SceneKey": "string", // 关闭自动签场景，处方单场景为 E_PRESCRIPTION_AUTO_SIGN
"IsSuccess":true, // 是否成功
"OrgInfo": { // 关闭个人用户自动签的企业信息
"OrganizationId": "string", // 集成企业ID
"ProxyOrganizationId": "string", // 集团主企业ID
"OrganizationOpenId": "string", // 集成企业OpenID
"ProxyOrganizationOpenId": "string" // 集团主企业OpenID
}
}
}
5、撤销个人用户自动签的开通链接回调
当企业调用撤销个人用户自动签的开通链接接口时触发此回调
{
"MsgId": "12345",
"MsgType": "CancelUserAutoSign",
"MSgVersion": "CustomApp",
"MsgData": {
"Name":"string", // 撤销自动签用户姓名
"IdCardNumber":"string", // 撤销自动签用户证件号码
"IdCardType":"string", // 撤销自动签用户证件类型
"SceneKey": "string", // 撤销自动签场景，处方单场景为 E_PRESCRIPTION_AUTO_SIGN
"IsSuccess":true, // 是否成功
"OrgInfo": { // 撤销个人用户自动签的企业信息
"OrganizationId": "string", // 集成企业ID
"ProxyOrganizationId": "string", // 集团主企业ID
"OrganizationOpenId": "string", // 集成企业OpenID
"ProxyOrganizationOpenId": "string" // 集团主企业OpenID
}
}
}
6、电子处方单签署完成回调
当发起的电子处方单完成了医生或药师的签署后，将会触发此回调，全部字段说明链接
{
"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": 7 // 电子处方单固定为 7
}
]
}
}
五、联调环境
在联调测试环境建议使用腾讯电子签测试环境，相关的域名如下：
测试环境接口请求域名（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
六、补充信息
跳转小程序签署的几种方式
使用CreateSchemeUrl接口，设置不同的 EndPoint
其中小程序的原始 Id 如下，或者查看小程序信息自助获取。
| 小程序 | AppID | 原始 ID |
|---|---|---|
| 腾讯电子签（正式版） | wxa023b292fd19d41d | gh_da88f6188665 |
| 腾讯电子签 Demo | wx371151823f6f3edf | gh_39a5d3de69fa |
