获取跳转至腾讯电子签小程序的签署链接
1. 接口描述
接口请求域名: ess.tencentcloudapi.com 。
获取跳转至腾讯电子签小程序的签署链接
适用场景:如果需要签署人在自己的APP、小程序、H5应用中签署,可以通过此接口获取跳转腾讯电子签小程序的签署跳转链接。
跳转到小程序的实现,参考微信官方文档(分为全屏、半屏两种方式),如何配置也可以请参考: 跳转电子签小程序配置
注:
- 1. 如果签署人是在PC端扫码签署,可以通过生成跳转链接自主转换成二维码,让签署人在PC端扫码签署
- 2. 签署链接的有效期为90天,超过有效期链接不可用
- 3. 如果需跳转详情页(即PathType值为1)进行填写或签署合同,需指定签署方信息:姓名、手机号码、企业名称等,才能生成正确的跳转链接
- 4. 生成的链路后面不能再增加参数(会出现覆盖链接中已有参数导致错误)
其中小程序的原始Id如下,或者查看小程序信息自助获取。
小程序 | AppID | 原始ID |
---|---|---|
腾讯电子签(正式版) | wxa023b292fd19d41d | gh_da88f6188665 |
腾讯电子签Demo | wx371151823f6f3edf | gh_39a5d3de69fa |
默认接口请求频率限制:300次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:CreateSchemeUrl。 |
Version | 是 | String | 公共参数,本接口取值:2020-11-11。 |
Region | 否 | String | 公共参数,此参数为可选参数。 |
Operator | 是 | UserInfo | 执行本接口操作的员工信息, userId 必填。 注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。 |
OrganizationName | 否 | String | 合同流程签署方的组织机构名称。 如果名称中包含英文括号(),请使用中文括号()代替。 示例值:典子谦示例企业 |
Name | 否 | String | 合同流程里边签署方经办人的姓名。 示例值:典子谦 |
Mobile | 否 | String | 合同流程里边签署方经办人手机号码, 支持国内手机号11位数字(无需加+86前缀或其他字符)。 示例值:13200000000 |
IdCardType | 否 | String | 证件类型,支持以下类型
示例值:ID_CARD |
IdCardNumber | 否 | String | 证件号码,应符合以下规则
示例值:620000198802020000 |
EndPoint | 否 | String | 要跳转的链接类型
示例值:HTTP |
FlowId | 否 | String | 合同流程ID 注: 如果准备跳转到合同流程签署的详情页面(即PathType=1时)必传, 跳转其他页面可不传 示例值:yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm |
FlowGroupId | 否 | String | 合同流程组的组ID, 在合同流程组场景下,生成合同流程组的签署链接时需要赋值 示例值:yDR1AUUgygjazuesUuO4zjESPW4PkfNi |
PathType | 否 | Integer | 要跳转到的页面类型
示例值:1 |
AutoJumpBack | 否 | Boolean | 签署完成后是否自动回跳
注: 1. 该参数只针对APP类型(电子签小程序跳转贵方小程序)场景 的签署链接有效 2. 手机应用APP 或 微信小程序需要监控界面的返回走后序逻辑, 微信小程序的文档可以参考这个 3. 电子签小程序跳转贵方APP,不支持自动跳转,必需用户手动点击完成按钮(微信的限制) 示例值:false |
Agent | 否 | Agent | 代理企业和员工的信息。 在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。 |
Hides.N | 否 | Array of Integer | 生成的签署链接在签署页面隐藏的按钮列表,可设置如下:
注: 字段为数组, 可以传值隐藏多个按钮 示例值:[1,2] |
RecipientId | 否 | String | 签署节点ID,用于生成动态签署人链接完成领取。 注: 生成动态签署人补充链接时必传。 |
FlowGroupUrlInfo | 否 | FlowGroupUrlInfo | 合同组相关信息,指定合同组子合同和签署方的信息,用于补充动态签署人。 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
SchemeUrl | String | 腾讯电子签小程序的签署链接。
注: 生成的链路后面不能再增加参数 示例值:https://essurl.cn/2n**42Nd |
SchemeQrcodeUrl | String | 二维码,在生成动态签署人跳转封面页链接时返回 |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 获取某个合同组的签署链接(短链)
- 获取合同组的签署链接(FlowGroupId设置成合同组的ID)
- 签署链接是短链(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 获取某个流程合同的签署链接(主代子)
- 主企业代子企业创建小程序签署链接(Agent参数中的ProxyOrganizationId设置成子企业ID)
- 签署链接是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 获取某个流程合同的小程序跳转签署链接(隐藏某些按钮)
- 签署界面隐藏 更多操作按钮 和 查看详情按钮按钮 (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 指定证件信息,给企业员工生成跳转到电子签小程序的签署链接
- 获取合同的签署链接(FlowId设置成合同的ID)
- 签署链接是短链(EndPoint设置成HTTP_SHORT_URL)
- 根据证件信息匹配签署人(指定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- 小程序合同详情)
- 获取小程序跳转签署链接(EndPoint设置成APP)
- 不指定跳转的页面类型(不传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 | 请升级到对应版本后即可使用该接口。 |