获取跳转至腾讯电子签小程序的签署链接
1. 接口描述
接口请求域名: essbasic.tencentcloudapi.com 。
创建跳转小程序查看或签署的链接
腾讯电子签小程序的AppID 和 原始Id如下:
小程序 | AppID | 原始ID |
---|---|---|
腾讯电子签(正式版) | wxa023b292fd19d41d | gh_da88f6188665 |
腾讯电子签Demo | wx371151823f6f3edf | gh_39a5d3de69fa |
主要使用场景EndPoint分类
EndPoint | 场景 | 说明和示例 |
---|---|---|
WEIXINAPP | 短链跳转腾讯电子签小程序签署场景 | 点击链接打开电子签小程序(与腾讯电子签官方短信提醒用户签署形式一样) 示例: https://essurl.cn/x9nvWU8fTg |
LONGURL2WEIXINAPP | 长链跳转腾讯电子签小程序签署场景 | 点击链接打开电子签小程序, 是WEIXINAPP生成短链代表的那个长链 |
CHANNEL | 带有H5引导页的跳转腾讯电子签小程序签署场景 | 点击链接打开一个H5引导页面, 页面中有个"前往小程序"的按钮, 点击后会跳转到腾讯电子签小程序签署场景; 签署完成会回到H5引导页面, 然后跳转到指定创建链接指定的JumpUrl 示例: https://res.ess.tencent.cn/cdn/h5-activity-beta/jump-mp.html?use=channel-guide&type=warning&token=uIFKIU8fTd |
APP | 贵方APP跳转腾讯电子签小程序签署场景 | 贵方App直接跳转到小程序后, 在腾讯电子签小程序签署完成后返回贵方App的场景 跳转到腾讯电子签小程序的实现可以参考微信的官方文档:开放能力/打开 App 示例: pages/guide?from=default&where=mini& to=CONTRACT_DETAIL& id=yDwiBUUc*duRvquCSX8wd& shortKey=yDwivUA**W1yRsTre3 |
APP | 贵方小程序跳转腾讯电子签小程序签署场景 | 贵方小程序直接跳转到小程序后, 在腾讯电子签小程序签署完成后返回贵方小程序的场景 跳转到腾讯电子签小程序的实现可以参考微信官方文档全屏方式和半屏方式 此时返回的SignUrl就是官方文档中的path 示例:pages/guide?from=default&where=mini& to=CONTRACT_DETAIL& id=yDwiBUUc*duRvquCSX8wd& shortKey=yDwivUA**W1yRsTre3 |
默认接口请求频率限制:20次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:CreateSignUrls。 |
Version | 是 | String | 公共参数,本接口取值:2021-05-26。 |
Region | 否 | String | 公共参数,此参数为可选参数。 |
Agent | 是 | Agent | 关于渠道应用的相关信息,包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容,您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。 此接口下面信息必填。
第三方平台子客企业和员工必须已经过实名认证 |
FlowIds.N | 否 | Array of String | 合同流程ID数组,最多支持100个。 注: 该参数和合同组编号必须二选一 示例值:["yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm"] |
FlowGroupId | 否 | String | 合同组编号 注: 该参数和合同流程ID数组必须二选一 |
Endpoint | 否 | String | 签署链接类型,可以设置的参数如下
注:动态签署人场景,如果签署链接类型设置为 APP ,则仅支持跳转到封面页。详细使用场景可以参考接口描述说明中的 主要使用场景EndPoint分类 示例值:”WEIXINAPP“ |
GenerateType | 否 | String | 签署链接生成类型,可以选择的类型如下
示例值:CHANNEL |
OrganizationName | 否 | String | SaaS平台企业员工签署方的企业名称 如果名称中包含英文括号(),请使用中文括号()代替。 注: GenerateType为"NOT_CHANNEL"时必填 示例值:典子谦示例企业 |
Name | 否 | String | 合同流程里边参与方的姓名。 注: GenerateType为"PERSON"(即个人签署方)时必填 示例值:典子谦 |
Mobile | 否 | String | 合同流程里边签署方经办人手机号码, 支持国内手机号11位数字(无需加+86前缀或其他字符)。 注: GenerateType为"PERSON"或"FOLLOWER"时必填 示例值:13200000000 |
IdCardType | 否 | String | 证件类型,支持以下类型
示例值:ID_CARD |
IdCardNumber | 否 | String | 证件号码,应符合以下规则
示例值:620000198802020000 |
OrganizationOpenId | 否 | String | 第三方平台子客企业的企业的标识, 即OrganizationOpenId 注: GenerateType为"CHANNEL"时必填 示例值:org_dianziqian |
OpenId | 否 | String | 第三方平台子客企业员工的标识OpenId,GenerateType为"CHANNEL"时可用,指定到具体参与人, 仅展示已经实名的经办人信息 注: 如果传进来的OpenId已经实名并且加入企业, 则忽略Name,IdCardType,IdCardNumber,Mobile这四个入参(会用此OpenId实名的身份证和登录的手机号覆盖) 示例值:n9527 |
AutoJumpBack | 否 | Boolean | 签署完成后是否自动回跳
注: 1. 该参数只针对APP类型(电子签小程序跳转贵方小程序)场景 的签署链接有效 2. 手机应用APP 或 微信小程序需要监控界面的返回走后序逻辑, 微信小程序的文档可以参考这个 3. 电子签小程序跳转贵方APP,不支持自动跳转,必需用户手动点击完成按钮(微信的限制) 示例值:false |
JumpUrl | 否 | String | 签署完之后的H5页面的跳转链接,针对Endpoint为CHANNEL时有效,最大长度1000个字符。 示例值:https://qq.com |
Hides.N | 否 | Array of Integer | 生成的签署链接在签署页面隐藏的按钮列表,可设置如下:
注: 字段为数组, 可以传值隐藏多个按钮 |
RecipientIds.N | 否 | Array of String | 参与方角色ID,用于生成动态签署人链接完成领取。 注: 使用此参数需要与flow_ids数量一致并且一一对应, 表示在对应同序号的流程中的参与角色ID , |
FlowGroupUrlInfo | 否 | FlowGroupUrlInfo | 合同组相关信息,指定合同组子合同和签署方的信息,用于补充动态签署人。 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
SignUrlInfos | Array of SignUrlInfo | 签署参与者签署H5链接信息数组 |
ErrorMessages | Array of String | 生成失败时的错误信息,成功返回”“,顺序和出参SignUrlInfos保持一致 示例值:["无效的流程合同Id","无此参与人"] |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 给子客企业生成签署链接
给子客企业生成签署链接 GenerateType设置为CHANNEL, 并传子客企业的OrganizationOpenId 和子客员工的OpenId
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateSignUrls
<公共请求参数>
{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "dianziqian"
},
"ProxyAppId": ""
},
"FlowIds": [
"yDwiBUUckpo27hrfUuLiduRSc29fh7OX"
],
"Endpoint": "WEIXINAPP",
"GenerateType": "CHANNEL",
"OrganizationOpenId": "org_zhansan",
"OpenId": "n1357"
}
输出示例
{
"Response": {
"SignUrlInfos": [
{
"SignUrl": "https://test.essurl.cn/ePXXNU8fSh",
"Deadline": 0,
"SignOrder": 0,
"SignId": "",
"CustomUserId": "",
"Name": "",
"Mobile": "",
"OrganizationName": "",
"ApproverType": "",
"IdCardNumber": "",
"FlowId": "yDwiBUUckpo27hrfUuLiduRSc29fh7OX",
"OpenId": "",
"FlowGroupId": "",
"SignQrcodeUrl": ""
}
],
"ErrorMessages": [],
"RequestId": "65552999-e0c6-47b7-a8db-c5e2a26b353b"
}
}
示例2 给所有签署人的签署链接
给所有签署人的签署链接 GenerateType设置为ALL
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateSignUrls
<公共请求参数>
{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_zhixinlian",
"ProxyOperator": {
"OpenId": "zhixinlian"
},
"ProxyAppId": ""
},
"FlowIds": [
"yDwiBUUckpo2726cUuLiduRx1WvBLD5l "
],
"Endpoint": "WEIXINAPP",
"GenerateType": "ALL"
}
输出示例
{
"Response": {
"SignUrlInfos": [
{
"SignUrl": "https://test.essurl.cn/cOwbkU8fRh",
"Deadline": 1706260744,
"SignOrder": 0,
"SignId": "yDwiBUUckpo2726iUuLiduRQSyCSCIK4",
"CustomUserId": "",
"Name": "张三",
"Mobile": "18888888888",
"OrganizationName": "",
"ApproverType": "PERSON",
"IdCardNumber": "",
"FlowId": "yDwiBUUckpo2726cUuLiduRx1WvBLD5l ",
"OpenId": "",
"FlowGroupId": "",
"SignQrcodeUrl": "https://file.test.ess.tencent.cn/bresource/resource/resource/0/0.JPG?hkey=5d92f0d***"
},
{
"SignUrl": "https://test.essurl.cn/QH1dqU8eta",
"Deadline": 1706260744,
"SignOrder": 0,
"SignId": "yDwiBUUckpo2726mUuLiduR8RkpoTHLy",
"CustomUserId": "",
"Name": "王五",
"Mobile": "13700000000",
"OrganizationName": "",
"ApproverType": "ORGANIZATION",
"IdCardNumber": "3****************3",
"FlowId": "yDwiBUUckpo2726cUuLiduRx1WvBLD5l ",
"OpenId": "n1379",
"FlowGroupId": "",
"SignQrcodeUrl": "https://file.test.ess.tencent.cn/bresource/resource/resource/0/0.JPG?hkey=5d92f0d***"
},
{
"SignUrl": "https://test.essurl.cn/RaqWRU8fRg",
"Deadline": 1706260744,
"SignOrder": 0,
"SignId": "yDwiBUUckpo27269UuLiduRCK7cW8oxv",
"CustomUserId": "",
"Name": "李四",
"Mobile": "15100000000",
"OrganizationName": "",
"ApproverType": "ORGANIZATION",
"IdCardNumber": "",
"FlowId": "yDwiBUUckpo2726cUuLiduRx1WvBLD5l ",
"OpenId": "",
"FlowGroupId": "",
"SignQrcodeUrl": "https://file.test.ess.tencent.cn/bresource/resource/resource/0/0.JPG?hkey=5d92f***"
}
],
"ErrorMessages": [
""
],
"RequestId": "6f4198d9-2e9a-4ff7-a4f6-3ea8bd3f79ae"
}
}
示例3 获取动态签署人补充链接
获取动态签署人补充链接,创建合同时未指定具体签署人,可获取链接后推送给指定的人进行补充
注:
1.参数GenerateType需传值为RECIPIENT
2.需指定对应的签署方角色编号(即RecipientId)
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateSignUrls
<公共请求参数>
{
"FlowIds": [
"yDwhGUUfe5g******CX8ZwTiSg8gISocy"
],
"RecipientIds": [
"yDwJDUUckpkv98zbUEF1GNmv6ln4ga9W"
],
"GenerateType": "RECIPIENT",
"Agent": {
"ProxyOrganizationOpenId": "1000***8062",
"ProxyOperator": {
"OpenId": "yDR3L****eTdCt5TVx"
},
"AppId": "125***319"
},
"Endpoint": ""
}
输出示例
{
"Response": {
"ErrorMessages": [],
"RequestId": "s1696937862717144539",
"SignUrlInfos": [
{
"ApproverType": "",
"CustomUserId": "",
"Deadline": 0,
"FlowGroupId": "",
"FlowId": "yDwhGUUfe5g******CX8ZwTiSg8gISocy",
"IdCardNumber": "",
"Mobile": "",
"Name": "",
"OpenId": "",
"OrganizationName": "",
"SignId": "",
"SignOrder": 0,
"SignQrcodeUrl": "https://file.test.ess.tencent.cn/bresource/resource/resource/0/0.JPG?hkey=5d92f0db15e6bbba6aea641f64c5c06dcbe2797f**************69ee4e24cd976dd8376dbd41c6ff227c803c4c561c",
"SignUrl": "https://test.essurl.cn/gGI***nZC"
}
]
}
}
示例4 给个人/自然人生成签署链接
给个人/自然人生成签署链接 GenerateType设置为PERSON, 并传个人的名字和手机号来生成
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateSignUrls
<公共请求参数>
{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "n9527"
},
"ProxyAppId": ""
},
"FlowIds": [
"yDwiBUUckpo27hh3UuLiduR83BEL3kSb"
],
"Endpoint": "WEIXINAPP",
"GenerateType": "PERSON",
"Name": "张三",
"Mobile": "18888888888"
}
输出示例
{
"Response": {
"SignUrlInfos": [
{
"SignUrl": "https://test.essurl.cn/9oJhnU8evP",
"Deadline": 0,
"SignOrder": 0,
"SignId": "",
"CustomUserId": "",
"Name": "",
"Mobile": "",
"OrganizationName": "",
"ApproverType": "",
"IdCardNumber": "",
"FlowId": "yDwiBUUckpo27hh3UuLiduR83BEL3kSb",
"OpenId": "",
"FlowGroupId": "",
"SignQrcodeUrl": ""
}
],
"ErrorMessages": [],
"RequestId": "0ec76ecb-467c-4761-8466-edb0a25bde91"
}
}
示例5 获取合同组动态签署人补充链接
获取动态签署人补充链接,创建合同组时未指定具体签署人,可获取链接后推送给指定的人进行补充
注:
1.参数GenerateType需传值为RECIPIENT
2.需指定对应的合同组FlowGroupUrlInfo签署方角色编号(即RecipientId)
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateSignUrls
<公共请求参数>
{
"FlowGroupId": "yDCVAUUckpwa592pUxoLjOlRVS9Zgusf",
"FlowGroupUrlInfo": {
"FlowGroupApproverInfos": [
{
"FlowId": "yDCVAUUckpwa59rcUxoLjOlEctyesTzj",
"RecipientId": "yDCVAUUckpwa59riUxoLjOluu9cf6B3s"
},
{
"FlowId": "yDCVAUUckpwa592dUxoLjOl8StWKvg9K",
"RecipientId": "yDCVAUUckpwa59r6UxoLjOlCC6ZHk7rL"
}
]
},
"GenerateType": "RECIPIENT",
"Agent": {
"ProxyOrganizationOpenId": "1000***8062",
"ProxyOperator": {
"OpenId": "yDR3L****eTdCt5TVx"
},
"AppId": "125***319"
},
"Endpoint": ""
}
输出示例
{
"Response": {
"ErrorMessages": [],
"RequestId": "s1696937862717144539",
"SignUrlInfos": [
{
"ApproverType": "",
"CustomUserId": "",
"Deadline": 0,
"FlowGroupId": "",
"FlowId": "yDwhGUUfe5g******CX8ZwTiSg8gISocy",
"IdCardNumber": "",
"Mobile": "",
"Name": "",
"OpenId": "",
"OrganizationName": "",
"SignId": "",
"SignOrder": 0,
"SignQrcodeUrl": "https://file.test.ess.tencent.cn/bresource/resource/resource/0/0.JPG?hkey=5d92f0db15e6bbba6aea641f64c5c06dcbe2797f**************69ee4e24cd976dd8376dbd41c6ff227c803c4c561c",
"SignUrl": "https://test.essurl.cn/gGI***nZC"
}
]
}
}
示例6 给SaaS平台企业员工签署方生成签署链接
给SaaS平台企业员工签署方生成签署链接 GenerateType设置为NOT_CHANNEL, 并传SaaS平台企业的名称和员工的名字与手机号
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateSignUrls
<公共请求参数>
{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "dianziqian"
},
"ProxyAppId": ""
},
"FlowIds": [
"yDwiBUUckpo27hrfUuLiduRSc29fh7OX"
],
"Endpoint": "WEIXINAPP",
"GenerateType": "NOT_CHANNEL",
"OrganizationName": "李四示例企业",
"Name": "李四",
"Mobile": "15100000000"
}
输出示例
{
"Response": {
"SignUrlInfos": [
{
"SignUrl": "https://test.essurl.cn/pr987U8euz",
"Deadline": 1706256392,
"SignOrder": 0,
"SignId": "",
"CustomUserId": "",
"Name": "李四",
"Mobile": "15100000000",
"OrganizationName": "",
"ApproverType": "ORGANIZATION",
"IdCardNumber": "",
"FlowId": "yDwiBUUckpo27hrfUuLiduRSc29fh7OX",
"OpenId": "",
"FlowGroupId": "",
"SignQrcodeUrl": "https://file.test.ess.tencent.cn/bresource/resource/resource/0/0.JPG?hkey=5d9**2f0"
}
],
"ErrorMessages": [],
"RequestId": "f6db6abf-512c-441f-b7e3-d17adf4a863c"
}
}
示例7 指定证件信息,为个人/自然人生成签署链接
给个人/自然人生成签署链接 GenerateType设置为PERSON, 并传个人的名字、手机号和证件信息来生成
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateSignUrls
<公共请求参数>
{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "n9527"
},
"ProxyAppId": ""
},
"FlowIds": [
"yDwiBUUckpo27hh3UuLiduR83BEL3kSb"
],
"Endpoint": "WEIXINAPP",
"GenerateType": "PERSON",
"Name": "张三",
"Mobile": "18888888888",
"IdCardType": "ID_CARD",
"IdCardNumber": "620000198802020000"
}
输出示例
{
"Response": {
"SignUrlInfos": [
{
"SignUrl": "https://essurl.cn/9oJ**P",
"Deadline": 0,
"SignOrder": 0,
"SignId": "",
"CustomUserId": "",
"Name": "",
"Mobile": "",
"OrganizationName": "",
"ApproverType": "",
"IdCardNumber": "",
"FlowId": "yDwiBUUckpo27hh3UuLiduR83BEL3kSb",
"OpenId": "",
"FlowGroupId": "",
"SignQrcodeUrl": ""
}
],
"ErrorMessages": [],
"RequestId": "0ec76ecb**bde91"
}
}
5. 错误码
以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。
错误码 | 描述 |
---|---|
FailedOperation | 操作失败。 |
InternalError | 内部错误。 |
InternalError.System | 系统错误。 |
InvalidParameter | 参数错误。 |
InvalidParameter.Application | 应用号不存在。 |
InvalidParameter.EndPoint | 不合法的EndPoint,请检查修改后重试。 |
InvalidParameter.FlowIds | 参数错误,合同id列表长度非法,请检查后重试。 |
InvalidParameter.GenerateType | 参数错误,不受支持的GenerateType,请检查后重试。 |
InvalidParameter.ParamError | 参数错误。 |
InvalidParameterValue | 参数取值错误。 |
MissingParameter | 缺少参数错误。 |
MissingParameter.FlowIdsOrFlowGroupId | 请传入需要查询的合同或合同组的ID。 |
OperationDenied | 操作被拒绝。 |
OperationDenied.NoIdentityVerify | 未通过个人实名。 |
OperationDenied.UserNotInOrganization | 用户不归属于当前企业,无法操作,请检查后重试。 |
ResourceNotFound | 资源不存在。 |
ResourceNotFound.Application | 应用号不存在。 |
ResourceNotFound.FlowGroup | 合同组不存在。 |
ResourceNotFound.Template | 模板不存在。 |
ResourceUnavailable | 资源不可用。 |
UnauthorizedOperation.NoPermissionFeature | 请升级到对应版本后即可使用该接口。 |