1、前言

项目中需要使用到电子签名的功能，经过调研决定使用腾讯电子签。官网：腾讯电子签-电子合同-腾讯在线合同签约平台

2、接入流程

2.1 结合业务需求确定接入方式。

腾讯电子签产品很多，具体需要提前阅读官网或者联系售前客户之类的了解。本人在项目中接入方式是通过模板方式发起，其中模板是在腾讯的电子签工作台画好的。（也可以放在本地，通过文件上传的形式，然后发起）

2.2 首先登录腾讯电子签工作台。

（以下以测试环境为例，正式环境需要企业认证注册，然后进入控制台。）

img

点击创建模板，上传合同模板（对应系统中的会诊病例），word和pdf都行。

img

添加签署区，设置一些属性（控件）名称，在调用接口时，要传参填充数据。

img

在要签名的地方，添加签署控件，以个人签名为例。

img

设置签署流程时，注意在添加签署人时，要注意选择个人，然后签署区要选择已添加好的签署方名称，特别是多个专家的场景，一定要把签署区和对应签署的专家绑定起来。

img

多个签署人，可以指定是否按顺序签署。注意调用腾讯接口时，默认是按顺序签署的，不按顺序，需要显示设置unorder=true参数值。

img

最后保存，得到模板id，这个在调用接口是必要的参数。

img

2.3 获取调用腾讯接口的必要参数配置。

img

签名验证token，在调用API时，需要携带**secretToken

回调的加密key，以及回调的url地址。

img

secretId. 腾讯云ak/sk (secretId/secretKey)调用API的密钥对，通过腾讯云后台CAM控制台获取

secretKey.腾讯云ak/sk (secretId/secretKey) 调用API的密钥对，通过腾讯云后台CAM控制台获取

img

还需要一个经办人id即管理员用户id或者员工用户id，电子签控制台获取。在更多–》组织管理可以得到。

img

最后就是腾讯云API域名地址：

测试环境：endPoint = “ess.test.ess.tencent.cn”，fileServiceEndPoint = “file.test.ess.tencent.cn”

正式环境：endPoint = “ess.tencentcloudapi.com”，fileServiceEndPoint = “file.ess.tencent.cn”

2.4 对接腾讯SDK，进行业务开发

2.4.1 引入依赖

项目中接入腾讯云SDK：使用最新的版本。

img

img

2.4.2 通过模板发起合同接口调用的主要流程

image-20260219142450517

在获取到签署流程链接后，返回给前端，生成二维码在页面展示，不使用发送短信的方式。

2.4.3 核心代码

TxElectronicSignatureConfig，对接腾讯SDK所需要的各种配置。

img

TxElectronicSignatureClient，api交互的客户端。

img

TxElectronicSignatureApi，项目中主要涉及到的api方法。

img

TxElectronicSignatureService，对接的业务逻辑处理方法

img

TxElectronicSignatureController，对外提供的接口

img

3、示例

项目接口及数据对象说明

需要写明接口名称和接口访问path；数据对象需要明确写出对象定义字段和描述；做了哪些模板；

3.1创建医疗会诊电子签流程接口

名称 内容 说明
接口名称 /txqian/createConsFlowByTemplate
请求方式 POST POST提交数据

请求报文格式

参数名称 参数中文名称 参数类型 是否必填 备注
adviceForm 表单信息 Obejct 是 MedAdviceForm类型
diagnAdvice 签署人的诊断建议 List 是 与 approvers 中签署人顺序保持一致
flowName 流程名称 String 是 长度限制为1~200个字符
approvers 签署人信息 List 是
customData 自定义参数 String 是 json格式，回调接口会透传
MedAdviceForm参数名称 中文名称 参数类型 是否必须 备注
patientName 患者姓名 String 是
sex 患者性别 String 是
age 患者年龄 String 是
consType 会诊类型 String 是
followupFlag 会诊类别 String 是 初诊，复诊
isUrgent 申请类型 String 是 普通，急诊
medCenterCode 会诊单位 String 是
applyTime 申请日期 String 是
consTime 会诊时间 String 是
experts 专家 String 是 多个专家逗号分隔
preDiagnosis 初步诊断 String 是
TxFlowCreateApprover参数名称 中文名称 参数类型 是否必须 备注
approverName 签署方的姓名 String 是 真实姓名
approverMobile 签署方的手机号 String 是 真实手机号
approverType 签署方的类型 Long 是 0:企业B端，1:个人C端。 3:企业B端静默（自动）签署，无需签署人参与，自动签署可以参考自动签署使用说明文档。7:个人C端自动签署，适用于个人自动签场景
notifyType 签署人通知类型 String 是 sms:短信，none:无

报文响应格式：

参数名称 参数中文名称 参数类型 是否一定存在 参数说明 备注
currTime 服务器时间 Long 是 时间戳
message 返回消息 string 否
state 状态码 int 是 1000:成功
data 数据 Object 否 FlowReturnModel类型
FlowReturnModel参数 中文名称 参数类型 是否必须 备注
flowId 流程id(合同id) String 是
signUrl 合同签署url String 是 跳转小程序的签署链接的有效期为90天，超过有效期链接不可用
downloadUrl 合同下载url String 是 有效期5分钟

响应示例：

{

“state”: 1000,

“message”: “”,

“currTime”: 1,

“data”: {

​ “flowId”: “”,

​ “signUrl”: “”,

​ “downloadUrl”: “”

}

}

目前共创建了8个模板，最多支持8个专家同时参与会诊。

img

3.2查询电子签合同文件url接口

名称 内容 说明
接口名称 /txqian/getFlowFileUrl
请求方式 GET GET请求

请求报文格式

参数名称 参数中文名称 参数类型 是否必填 备注
flowId 流程id String 是

报文响应格式：

参数名称 参数中文名称 参数类型 是否一定存在 参数说明 备注
currTime 服务器时间 Long 是 时间戳
message 返回消息 string 否
state 状态码 int 是 1000:成功
data 数据 String 否 url地址，有效期五分钟

响应示例:

{

“state”: 1000,

“message”: “”,

“currTime”: 1,

“data”: “”

}

3.3电子签流程回调接口

名称 内容 说明
接口名称 /txqian/callBackFlow
请求方式 POST POST接收数据

请求报文格式

参数名称 参数中文名称 参数类型 是否必填 备注
encrypt 数据 String 是 base64后的密文，解密后是CallBackInfoModel类型
CallBackInfoModelr参数名称 中文名称 参数类型 是否必须 备注
msgId 回调消息id String 是
msgType 回调消息类型 String 是
msgVersion 回调消息版本号 String 是
msgData 回调消息结构体 Object 是 不同的回调消息，结构不同

报文响应格式：

参数名称 参数中文名称 参数类型 是否一定存在 参数说明 备注
currTime 服务器时间 Long 是 时间戳
message 返回消息 string 否
state 状态码 int 是 1000:成功
data 数据 Object 否

响应示例:

{

“state”: 1000,

“message”: “”,

“currTime”: 1,

“data”: null

}

3.4项目对接时序图

需要从用户操作开始——>业务系统接口——>腾讯接口——>回调

img