跳到主要内容

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

1. 接口描述

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

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

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

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

注: 1. 如果签署人是在PC端扫码签署,可以通过生成跳转链接自主转换成二维码,让签署人在PC端扫码签署 2. 签署链接的有效期为90天,超过有效期链接不可用

其中小程序的原始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
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 : 腾讯电子签小程序合同列表页

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

注: 该参数只针对"APP" 类型的签署链接有效
示例值:false
AgentAgent代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。
Hides.NArray of Integer生成的签署链接在签署页面隐藏的按钮列表,可设置如下:

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


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

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。

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",
"SchemeUrl": "https://essurl.cn/i3am**5Y9W"
}
}

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

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",
"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"
}
}

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

  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",
"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"
}
}

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

  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",
"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"
}
}

示例5 错误的示例- 获取某个流程合同的小程序跳转签署链接,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请升级到对应版本后即可使用该接口。