跳到主要内容

获取个人用户H5签署链接

1. 接口描述

接口请求域名: ess.tencentcloudapi.com 。

该接口用于发起合同后,生成个人用户的签署链接, 暂时不支持企业端签署

注意:
1. 该接口目前仅支持签署人类型是个人签署方的场景(PERSON)。
2. 该接口可生成签署链接的C端签署人必须仅有手写签名和时间类型的签署控件,不支持填写控件 。
3. 该签署链接有效期为30分钟,过期后将失效,如需签署可重新创建签署链接 。
4. 该接口返回的签署链接是用于APP集成的场景,支持APP打开或浏览器直接打开,不支持微信小程序嵌入
跳转到小程序的实现,参考微信官方文档(分为全屏半屏两种方式),如何配置也可以请参考: 跳转电子签小程序配置

默认接口请求频率限制:20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称必选类型描述
ActionString公共参数,本接口取值:CreateFlowSignUrl。
VersionString公共参数,本接口取值:2020-11-11。
RegionString公共参数,此参数为可选参数。
FlowIdString合同流程ID,为32位字符串。
建议开发者妥善保存此流程ID,以便于顺利进行后续操作。
可登录腾讯电子签控制台,在 "合同"->"合同中心" 中查看某个合同的FlowId(在页面中展示为合同ID)。
示例值:yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm
FlowApproverInfos.NArray of FlowCreateApprover流程签署人列表,其中结构体的ApproverName,ApproverMobile和ApproverType必传,其他可不传,

注:
1. ApproverType目前只支持个人类型的签署人。
2. 签署人只能有手写签名和时间类型的签署控件,其他类型的填写控件和签署控件暂时都未支持。
OperatorUserInfo执行本接口操作的员工信息。
注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。
AgentAgent代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。
JumpUrlString签署完之后的H5页面的跳转链接,此链接及支持http://和https://,最大长度1000个字符。(建议https协议)

3. 输出参数

参数名称类型描述
FlowApproverUrlInfosArray of FlowApproverUrlInfo签署人签署链接信息
RequestIdString唯一请求 ID,每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 创建个人用户H5签署链接

发起流程后,给其中的C端签署人创建签署链接

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowSignUrl
<公共请求参数>

{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowApproverInfos": [
{
"ApproverType": 1,
"ApproverMobile": "13200000000",
"ApproverName": "典子谦"
}
],
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm"
}

输出示例

{
"Response": {
"FlowApproverUrlInfos": [
{
"ApproverMobile": "13200000000",
"ApproverName": "典子谦",
"ApproverType": 1,
"LongUrl": "https://quick.test.qian.tencent.cn/home?ApproverIdCardNumber=Mi**Kio2&ApproverMobile=MTk***NjA%3D&ApproverName=%25**A&ApproverType=1&Code=yDwJCUUck****V2R5K&CodeType=QUICK&FlowId=yDwF**1f3cqjkGm&ShowHeader=1&shortKey=yDwq5**M5GlG1c&token=bR8**HA",
"SignUrl": "https://essurl.cn/bR8**HA"
}
],
"RequestId": "s1693832180480950012"
}
}

示例2 创建个人用户H5签署链接(签署完成后跳转到指定地址)

  1. 给个人用户创建签署链接
  2. 签署完成后跳转到指定页面地址(设置跳转地址JumpUrl)

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowSignUrl
<公共请求参数>

{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowApproverInfos": [
{
"ApproverType": 1,
"ApproverMobile": "13200000000",
"ApproverName": "典子谦"
}
],
"JumpUrl": "https://www.example.com",
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm"
}

输出示例

{
"Response": {
"FlowApproverUrlInfos": [
{
"ApproverMobile": "13200000000",
"ApproverName": "典子谦",
"ApproverType": 1,
"LongUrl": "https://quick.test.qian.tencent.cn/home?ApproverIdCardNumber=MioqKi**Kio2&ApproverMobile=MTk***NjA%3D&ApproverName=%25**A&ApproverType=1&Code=yDwJCUUck****V2R5K&CodeType=QUICK&FlowId=yDwF**1f3cqjkGm&ShowHeader=1&shortKey=yDwq5**M5GlG1c&token=bR8**HA",
"SignUrl": "https://essurl.cn/bR8**HA"
}
],
"RequestId": "s1693832180480950012"
}
}

示例3 错误示例-创建个人用户签署链接,传错签署人姓名

  1. 给个人用户创建签署链接
  2. 用户姓名不是合同的参与人

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowSignUrl
<公共请求参数>

{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowApproverInfos": [
{
"ApproverType": 1,
"ApproverMobile": "13200000000",
"ApproverName": "张三"
}
],
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm"
}

输出示例

{
"Response": {
"Error": {
"Code": "ResourceNotFound",
"Message": "无法找到参与人"
},
"RequestId": "s1693832578941223891"
}
}

示例4 错误示例-创建个人用户签署链接,该用户还有些控件需要填写

  1. 给个人用户创建签署链接
  2. 该个人用户除了签署控件,还有填写控件需要补充

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowSignUrl
<公共请求参数>

{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowApproverInfos": [
{
"ApproverType": 1,
"ApproverMobile": "13200000000",
"ApproverName": "典子谦"
}
],
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm"
}

输出示例

{
"Response": {
"Error": {
"Code": "FailedOperation",
"Message": "该用户有暂不支持H5端的控件,请删除后重新发起流程"
},
"RequestId": "s1693901602090298421"
}
}

5. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码描述
FailedOperation操作失败。
InternalError内部错误。
InternalError.Api第三方接口失败。
InvalidParameter参数错误。
MissingParameter缺少参数错误。
OperationDenied.ErrNoResourceAccess此企业无该资源使用权限。
OperationDenied.Forbid禁止此项操作。
OperationDenied.NoIdentityVerify未通过个人实名认证。
OperationDenied.NoLogin用户未登录,请先登录后再操作。
ResourceNotFound资源不存在。
ResourceNotFound.Flow签署流程未找到,请检查参数。
UnauthorizedOperation.NoPermissionFeature请升级到对应版本后即可使用该接口。