跳到主要内容

获取跳转至腾讯电子签小程序的签署链接

1. 接口描述

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

获取跳转至腾讯电子签小程序的签署链接

适用场景:如果需要签署人在自己的APP、小程序、H5应用中签署,可以通过此接口获取跳转腾讯电子签小程序的签署跳转链接。

跳转到小程序的实现,参考微信官方文档(分为全屏半屏两种方式),如何配置也可以请参考: 跳转电子签小程序配置

注:

  • 1. 如果签署人是在PC端扫码签署,可以通过生成跳转链接自主转换成二维码,让签署人在PC端扫码签署
  • 2. 签署链接的有效期为90天,超过有效期链接不可用
  • 3. 如果需跳转详情页(即PathType值为1)进行填写或签署合同,需指定签署方信息:姓名、手机号码、企业名称等,才能生成正确的跳转链接
  • 4. 生成的链路后面不能再增加参数(会出现覆盖链接中已有参数导致错误)

其中小程序的原始Id如下,或者查看小程序信息自助获取。

小程序AppID原始ID
腾讯电子签(正式版)wxa023b292fd19d41dgh_da88f6188665
腾讯电子签Demowx371151823f6f3edfgh_39a5d3de69fa

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

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

2. 输入参数

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

参数名称必选类型描述
ActionString公共参数,本接口取值:CreateSchemeUrl。
VersionString公共参数,本接口取值:2020-11-11。
RegionString公共参数,此参数为可选参数。
OperatorUserInfo执行本接口操作的员工信息, userId 必填。
注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。
OrganizationNameString合同流程签署方的组织机构名称。
如果名称中包含英文括号(),请使用中文括号()代替。
示例值:典子谦示例企业
NameString合同流程里边签署方经办人的姓名。

示例值:典子谦
MobileString合同流程里边签署方经办人手机号码, 支持国内手机号11位数字(无需加+86前缀或其他字符)。
示例值:13200000000
IdCardTypeString证件类型,支持以下类型
  • ID_CARD : 居民身份证
  • HONGKONG_AND_MACAO : 港澳居民来往内地通行证
  • HONGKONG_MACAO_AND_TAIWAN : 港澳台居民居住证(格式同居民身份证)

示例值:ID_CARD
IdCardNumberString证件号码,应符合以下规则
  • 居民身份证号码应为18位字符串,由数字和大写字母X组成(如存在X,请大写)。
  • 港澳居民来往内地通行证号码共11位。第1位为字母,“H”字头签发给香港居民,“M”字头签发给澳门居民;第2位至第11位为数字。
  • 港澳台居民居住证号码编码规则与中国大陆身份证相同,应为18位字符串。

示例值:620000198802020000
EndPointString要跳转的链接类型

  • HTTP:跳转电子签小程序的http_url, 短信通知或者H5跳转适合此类型 ,此时返回长链 (默认类型)
  • HTTP_SHORT_URL:跳转电子签小程序的http_url, 短信通知或者H5跳转适合此类型,此时返回短链
  • APP: 第三方APP或小程序跳转电子签小程序的path, APP或者小程序跳转适合此类型

示例值:HTTP
FlowIdString合同流程ID
注: 如果准备跳转到合同流程签署的详情页面(即PathType=1时)必传, 跳转其他页面可不传
示例值:yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm
FlowGroupIdString合同流程组的组ID, 在合同流程组场景下,生成合同流程组的签署链接时需要赋值
示例值:yDR1AUUgygjazuesUuO4zjESPW4PkfNi
PathTypeInteger要跳转到的页面类型

  • 0 : 腾讯电子签小程序个人首页 (默认)
  • 1 : 腾讯电子签小程序流程合同的详情页 (即合同签署页面)
  • 2 : 腾讯电子签小程序合同列表页
  • 3 : 腾讯电子签小程序合同封面页
    注:生成动态签署人补充链接时,必须指定为封面页

示例值:1
AutoJumpBackBoolean签署完成后是否自动回跳
  • false:否, 签署完成不会自动跳转回来(默认)
  • true:是, 签署完成会自动跳转回来


注:
1. 该参数只针对APP类型(电子签小程序跳转贵方小程序)场景 的签署链接有效
2. 手机应用APP 或 微信小程序需要监控界面的返回走后序逻辑, 微信小程序的文档可以参考这个
3. 电子签小程序跳转贵方APP,不支持自动跳转,必需用户手动点击完成按钮(微信的限制)
示例值:false
AgentAgent代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。
Hides.NArray of Integer生成的签署链接在签署页面隐藏的按钮列表,可设置如下:

  • 0 :合同签署页面更多操作按钮
  • 1 :合同签署页面更多操作的拒绝签署按钮
  • 2 :合同签署页面更多操作的转他人处理按钮
  • 3 :签署成功页的查看详情按钮


注: 字段为数组, 可以传值隐藏多个按钮
示例值:[1,2]
RecipientIdString签署节点ID,用于生成动态签署人链接完成领取。

注:生成动态签署人补充链接时必传。
FlowGroupUrlInfoFlowGroupUrlInfo合同组相关信息,指定合同组子合同和签署方的信息,用于补充动态签署人。

3. 输出参数

参数名称类型描述
SchemeUrlString腾讯电子签小程序的签署链接。

  • 如果EndPoint是APP,得到的链接类似于pages/guide?from=default&where=mini&id=yDwJSUUirqauh***7jNSxwdirTSGuH&to=CONTRACT_DETAIL&name=&phone=&shortKey=yDw***k1xFc5, 用法可以参加接口描述中的"跳转到小程序的实现"
  • 如果EndPoint是HTTP,得到的链接类似于 https://res.ess.tencent.cn/cdn/h5-activity/jump-mp.html?where=mini&from=SFY&id=yDwfEUUw**4rV6Avz&to=MVP_CONTRACT_COVER&name=%E9%83%**5%86%9B,点击后会跳转到腾讯电子签小程序进行签署
  • 如果EndPoint是HTTP_SHORT_URL,得到的链接类似于 https://essurl.cn/2n**42Nd,点击后会跳转到腾讯电子签小程序进行签署



注: 生成的链路后面不能再增加参数
示例值:https://essurl.cn/2n**42Nd
SchemeQrcodeUrlString二维码,在生成动态签署人跳转封面页链接时返回
RequestIdString唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 获取某个合同组的签署链接(短链)

  1. 获取合同组的签署链接(FlowGroupId设置成合同组的ID)
  2. 签署链接是短链(EndPoint设置成HTTP_SHORT_URL)

输入示例

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

{
"FlowGroupId": "yDwq7UUckpknjh4hUu1vFD6uHSIyKQPf",
"PathType": 1,
"Name": "典子谦",
"Mobile": "13200000000",
"EndPoint": "HTTP_SHORT_URL",
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
}
}

输出示例

{
"Response": {
"RequestId": "s1693796254269814638",
"SchemeQrcodeUrl": "",
"SchemeUrl": "https://essurl.cn/i3am**5Y9W"
}
}

示例2 获取动态签署人补充链接(短链)

获取动态签署人补充链接,创建合同时未指定具体签署人,可获取链接后推送给指定的人进行补充 注:获取动态签署人补充链接需指定PathType值为1或3,即跳转到合同封面页,并且指定对应签署节点的签署角色编号即RecipientId

输入示例

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

{
"FlowId": "yDwq7UU*Uu1vFD6uHSIyKQPf",
"RecipientId": "yDw7aUUckpkxxmljUE0xkKk1DlvwRdfK",
"PathType": 3,
"EndPoint": "HTTP_SHORT_URL",
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
}
}

输出示例

{
"Response": {
"RequestId": "s1693829642597082849",
"SchemeQrcodeUrl": "https://file.test.ess.tencent.cn/bresource/resource/resource/0/0.JPG?hkey=5d92f0db15e6bbba6aea641f64c5c06d01********************************f313b0728621415f3f14724c1d784e7737421333bf96a",
"SchemeUrl": "https://essurl.cn/i3am**5Y9W"
}
}

示例3 获取某个流程合同的签署链接(主代子)

  1. 主企业代子企业创建小程序签署链接(Agent参数中的ProxyOrganizationId设置成子企业ID)
  2. 签署链接是HTTP长链(EndPoint设置成HTTP,默认为此值)

输入示例

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

{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"Agent": {
"ProxyOrganizationId": "yDxbWUyKQDxgXVUuO4zjEB8mxCcDjAyF"
},
"FlowId": "yDwq7UU*Uu1vFD6uHSIyKQPf",
"PathType": 1,
"EndPoint": "HTTP",
"Name": "典子谦",
"Mobile": "13200000000"
}

输出示例

{
"Response": {
"RequestId": "s1693829642597082849",
"SchemeQrcodeUrl": "",
"SchemeUrl": "https://res.ess.tencent.cn/cdn/h5-activity/jump-mp.html?where=mini&from=SFY&id=yDwq7UU*Uu1vFD6uHSIyKQPf&to=MVP_CONTRACT_COVER&name=%E5**5%B2%A9&phone=M**c3NjA%3D&idtype=0&idcard=2****************6&createUserIdKeyByFlowKey=id&approverVerifyTypes=1&ignoreApproverSwitch=1&shortKey=yDwJCUemZ**A43"
}
}

示例4 获取某个流程合同的小程序跳转签署链接

1.链接是在 第三方APP或小程序中使用(EndPoint设置成APP) 2.签署完成后自动跳回第三方APP或小程序 (AutoJumpBack设置成true)

输入示例

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

{
"FlowId": "yDwq7UU*Uu1vFD6uHSIyKQPf",
"PathType": 1,
"Name": "典子谦",
"Mobile": "13200000000",
"EndPoint": "APP",
"AutoJumpBack": true,
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
}
}

输出示例

{
"Response": {
"RequestId": "s1693795766610672060",
"SchemeQrcodeUrl": "",
"SchemeUrl": "pages/guide?from=default&where=mini&id=yDwq7UU*Uu1vFD6uHSIyKQPf&to=CONTRACT_DETAIL&name=%E5%91%&phone=MTkx**0OTc3NjA%3D&autoJumpBack=true&idtype=0&idcard=2****************6&createUserIdKeyByFlowKey=id&approverVerifyTypes=1&shortKey=yDwJ**cJKQWef"
}
}

示例5 获取合同组动态签署人的领取链接以及二维码

获取动态签署人补充链接,创建合同组时未指定具体签署人,可获取链接后推送给指定的人进行补充 注:获取动态签署人补充链接需指定PathType值为1或3,即跳转到合同封面页,并且指定对应签署节点的签署角色编号即RecipientId

输入示例

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

{
"FlowGroupId": "yDwq7UUckpknjh4hUu1vFD6uHSIyKQPf",
"FlowGroupUrlInfo": {
"FlowGroupApproverInfos": [
{
"FlowId": "yDCVHUUckpwbquk8UuyXGHS86DkTCzfY",
"RecipientId": "yDCVHUUckpwbqoyiUx2jLf4wRXKt9ZGp"
},
{
"FlowId": "yDCVHUUckpwbquk2UuyXGHSuTPHxyR6u",
"RecipientId": "yDCVHUUckpwbqoyeUx2jLf48NQhgRXND"
}
]
},
"PathType": 1,
"EndPoint": "HTTP_SHORT_URL",
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
}
}

输出示例

{
"Response": {
"RequestId": "s1711335464242636975",
"SchemeQrcodeUrl": "https://file.test.ess.tencent.cn/bresource/resource/resource/0/0.JPG?hkey=5d92f0db15e6******0a251eda6ea8b",
"SchemeUrl": "https://test.essurl.cn/yG*****us"
}
}

示例6 获取某个流程合同的小程序跳转签署链接(隐藏某些按钮)

  1. 签署界面隐藏 更多操作按钮 和 查看详情按钮按钮 (Hides设置成[0,3])

输入示例

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

{
"FlowId": "yDwq7UU*Uu1vFD6uHSIyKQPf",
"PathType": 1,
"Name": "典子谦",
"Mobile": "13200000000",
"EndPoint": "APP",
"AutoJumpBack": true,
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"Hides": [
0,
3
]
}

输出示例

{
"Response": {
"RequestId": "s1693791166610672060",
"SchemeQrcodeUrl": "",
"SchemeUrl": "pages/guide?from=default&where=mini&id=yDwq7UU*Uu1vFD6uHSIyKQPf&to=CONTRACT_DETAIL&name=%E5%91%&phone=MTkx**0OTc3NjA%3D&autoJumpBack=true&idtype=0&idcard=2****************6&createUserIdKeyByFlowKey=id&approverVerifyTypes=1&shortKey=yDwJ**cJKQWef"
}
}

示例7 指定证件信息,给企业员工生成跳转到电子签小程序的签署链接

  1. 获取合同的签署链接(FlowId设置成合同的ID)
  2. 签署链接是短链(EndPoint设置成HTTP_SHORT_URL)
  3. 根据证件信息匹配签署人(指定IdCardType, IdCardNumber参数)

输入示例

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

{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwq7UU*Uu1vFD6uHSIyKQPf",
"PathType": 1,
"EndPoint": "HTTP_SHORT_URL",
"Name": "典子谦",
"Mobile": "13200000000",
"IdCardType": "ID_CARD",
"IdCardNumber": "620000198802020000"
}

输出示例

{
"Response": {
"RequestId": "s1693*****49",
"SchemeQrcodeUrl": "",
"SchemeUrl": "https://essurl.cn/3a****tM"
}
}

示例8 错误的示例- 获取某个流程合同的小程序跳转签署链接,PathType值没有传对(应该传1- 小程序合同详情)

  1. 获取小程序跳转签署链接(EndPoint设置成APP)
  2. 不指定跳转的页面类型(不传PathType或者传0值)

输入示例

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

{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwq7UU*Uu1vFD6uHSIyKQPf",
"EndPoint": "APP",
"Name": "典子谦",
"Mobile": "13200000000"
}

输出示例

{
"Response": {
"Error": {
"Code": "OperationDenied.NoSupportJumpPage",
"Message": "APP类型不支持跳转到电子签主页或合同列表页"
},
"RequestId": "s1693830251815551087"
}
}

5. 错误码

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

错误码描述
FailedOperation操作失败。
InternalError内部错误。
InternalError.Db数据库异常。
InternalError.DbRead内部错误,数据库查询失败,请稍后重试。
InternalError.System系统错误,请稍后重试。
InvalidParameter.DataNotFound数据不存在。
InvalidParameter.Mobile不合法的手机号,请检查后重试。
InvalidParameter.Name不合法的用户名称,请修改后重试。
InvalidParameter.ParamError参数错误。
InvalidParameterValue参数取值错误。
MissingParameter缺少参数错误。
OperationDenied操作被拒绝。
OperationDenied.ErrNoResourceAccess此企业无该资源使用权限。
OperationDenied.Forbid禁止此项操作。
OperationDenied.NoFlowPermission无权限操作签署流程,请联系客服了解权限,并在修改后重试。
OperationDenied.NoIdentityVerify未通过个人实名认证。
OperationDenied.NoLogin用户未登录,请先登录后再操作。
OperationDenied.NoSupportJumpPage不支持的跳转页,请联系客服了解跳转配置规则,修改后重试。
OperationDenied.WhiteListForbid未开通功能白名单,请联系客服处理。
ResourceNotFound.Application应用号不存在或已删除。
ResourceNotFound.Flow签署流程未找到,请检查参数。
ResourceUnavailable资源不可用。
UnauthorizedOperation.NoPermissionFeature请升级到对应版本后即可使用该接口。
更多开发者交流反馈
购买咨询
微信客服
4006-808-062
4006-808-062