获取跳转小程序查看或签署链接
1. 接口描述
接口请求域名: essbasic.tencentcloudapi.com 。
创建跳转小程序查看或签署的链接。
跳转小程序的几种方式:主要是设置不同的EndPoint
通过链接Url直接跳转到小程序,不需要返回 设置EndPoint为WEIXINAPP,得到链接打开即可。(与短信提醒用户签署形式一样)。
通过链接Url打开H5引导页-->点击跳转到小程序-->签署完退出小程序-->回到H5引导页-->跳转到指定JumpUrl 设置EndPoint为CHANNEL,指定JumpUrl,得到链接打开即可。
客户App直接跳转到小程序-->小程序签署完成-->返回App 跳转到小程序的实现,参考官方文档 https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/launchApp.html 其中小程序的原始Id,请联系<对接技术人员>获取,或者查看小程序信息自助获取。 使用CreateSignUrls,设置EndPoint为APP,得到path。
客户小程序直接跳到电子签小程序-->签署完成退出电子签小程序-->回到客户小程序 跳转到小程序的实现,参考官方文档(分为全屏、半屏两种方式) 全屏方式: (https://developers.weixin.qq.com/miniprogram/dev/api/navigate/wx.navigateToMiniProgram.html) 半屏方式: (https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/openEmbeddedMiniProgram.html) 其中小程序的原始Id,请联系<对接技术人员>获取,或者查看小程序信息自助获取。 使用CreateSignUrls,设置EndPoint为APP,得到path。
其中小程序的原始Id如下,或者查看小程序信息自助获取。
小程序 | AppID | 原始ID |
---|---|---|
腾讯电子签(正式版) | wxa023b292fd19d41d | gh_da88f6188665 |
腾讯电子签Demo | wx371151823f6f3edf | gh_39a5d3de69fa |
默认接口请求频率限制:20次/秒。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:CreateSignUrls。 |
Version | 是 | String | 公共参数,本接口取值:2021-05-26。 |
Region | 否 | String | 公共参数,此参数为可选参数。 |
Agent | 是 | Agent | 应用相关信息。 此接口Agent.ProxyOrganizationOpenId、Agent. ProxyOperator.OpenId、Agent.AppId 必填。 |
FlowIds.N | 否 | Array of String | 流程(合同)的编号列表,最多支持100个。(备注:该参数和合同组编号必须二选一) 示例值:["xxx", "yyy"] |
FlowGroupId | 否 | String | 合同组编号(备注:该参数和合同(流程)编号数组必须二选一) |
Endpoint | 否 | String | 签署链接类型,可以设置的参数如下 - WEIXINAPP:短链直接跳小程序 (默认类型) - CHANNEL:跳转H5页面 - APP:第三方APP或小程序跳转电子签小程序 - LONGURL2WEIXINAPP:长链接跳转小程序 示例值:”WEIXINAPP“ |
GenerateType | 否 | String | 签署链接生成类型,可以选择的类型如下 - ALL:全部签署方签署链接,此时不会给自动签署的签署方创建签署链接(默认类型) - CHANNEL:第三方平台子客企业企业 - NOT_CHANNEL:非第三方平台子客企业企业 - PERSON:个人 - FOLLOWER:关注方,目前是合同抄送方 示例值:CHANNEL |
OrganizationName | 否 | String | 非第三方平台子客企业参与方的企业名称,GenerateType为"NOT_CHANNEL"时必填 示例值:测试企业 |
Name | 否 | String | 参与人姓名 GenerateType为"PERSON"(即个人签署方)时必填 示例值:张三 |
Mobile | 否 | String | 参与人手机号 GenerateType为"PERSON"或"FOLLOWER"时必填 示例值:xxx |
OrganizationOpenId | 否 | String | 第三方平台子客企业的企业OpenId,GenerateType为"CHANNEL"时必填 示例值:xxx |
OpenId | 否 | String | 第三方平台子客企业参与人OpenId,GenerateType为"CHANNEL"时可用,指定到具体参与人, 仅展示已经实名的经办人信息 示例值:xxx |
AutoJumpBack | 否 | Boolean | Endpoint为"APP" 类型的签署链接,可以设置此值;支持调用方小程序打开签署链接,在电子签小程序完成签署后自动回跳至调用方小程序 示例值:false |
JumpUrl | 否 | String | 签署完之后的H5页面的跳转链接,针对Endpoint为CHANNEL时有效,最大长度1000个字符。 示例值:“https://qq.com” |
Hides.N | 否 | Array of Integer | 生成的签署链接在签署过程隐藏的按钮列表, 可以设置隐藏的按钮列表如下 - 0:合同签署页面更多操作按钮 - 1:合同签署页面更多操作的拒绝签署按钮 - 2:合同签署页面更多操作的转他人处理按钮 - 3:签署成功页的查看详情按钮 |
RecipientIds.N | 否 | Array of String | 签署节点ID,用于补充动态签署人,使用此参数需要与flow_ids数量一致 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
SignUrlInfos | Array of SignUrlInfo | 签署参与者签署H5链接信息数组 |
ErrorMessages | Array of String | 生成失败时的错误信息,成功返回”“,顺序和出参SignUrlInfos保持一致 示例值:["xx","yy"] |
RequestId | String | 唯一请求 ID,每次请求都会返回。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 批量创建签署参与者签署H5链接
创建链接,适用于APP或者小程序跳转
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateSignUrls
<公共请求参数>
{
"FlowIds": [
"yDwhGUUfe5g******CX8ZwTiSg8gISocy"
],
"Agent": {
"ProxyOrganizationOpenId": "1000***8062",
"ProxyOperator": {
"OpenId": "yDR3L****eTdCt5TVx"
},
"AppId": "125***319"
},
"Endpoint": "APP"
}
输出示例
{
"Response": {
"ErrorMessages": [
""
],
"RequestId": "022cf4af-cd7a-4a53-bb94-860673a7c6dc",
"SignUrlInfos": [
{
"ApproverType": "PERSON",
"CustomUserId": "",
"Deadline": 1722132728,
"FlowGroupId": "",
"FlowId": "yDwhG****iSg8gISocy",
"IdCardNumber": "",
"Mobile": "186****51",
"Name": "张三",
"OpenId": "",
"OrganizationName": "",
"SignId": "yDwhGUU****lVyjX8Q5w",
"SignOrder": 0,
"SignUrl": "pages/guide?from=default&where=mini&to=CONTRACT_DETAIL&id=yDwhGUU****ISocy&name=%E6%9D****8F%8D&phone=MTg2***Y%3D&approverVerifyTypes=1&shortKey=yDwhG***qy32"
}
]
}
}
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 | 请升级到对应版本后即可使用该接口。 |