跳到主要内容

获取跳转小程序查看或签署链接

1. 接口描述

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

创建跳转小程序查看或签署的链接。

跳转小程序的几种方式:主要是设置不同的EndPoint

  1. 通过链接Url直接跳转到小程序,不需要返回 设置EndPoint为WEIXINAPP,得到链接打开即可。(与短信提醒用户签署形式一样)。

  2. 通过链接Url打开H5引导页-->点击跳转到小程序-->签署完退出小程序-->回到H5引导页-->跳转到指定JumpUrl 设置EndPoint为CHANNEL,指定JumpUrl,得到链接打开即可。

  3. 客户App直接跳转到小程序-->小程序签署完成-->返回App 跳转到小程序的实现,参考官方文档 https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/launchApp.html 其中小程序的原始Id,请联系<对接技术人员>获取,或者查看小程序信息自助获取。 使用CreateSignUrls,设置EndPoint为APP,得到path。

  4. 客户小程序直接跳到电子签小程序-->签署完成退出电子签小程序-->回到客户小程序 跳转到小程序的实现,参考官方文档(分为全屏、半屏两种方式) 全屏方式: (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
腾讯电子签(正式版)wxa023b292fd19d41dgh_da88f6188665
腾讯电子签Demowx371151823f6f3edfgh_39a5d3de69fa

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

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

2. 输入参数

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

参数名称必选类型描述
ActionString公共参数,本接口取值:CreateSignUrls。
VersionString公共参数,本接口取值:2021-05-26。
RegionString公共参数,此参数为可选参数。
AgentAgent应用相关信息。 此接口Agent.ProxyOrganizationOpenId、Agent. ProxyOperator.OpenId、Agent.AppId 必填。
FlowIds.NArray of String流程(合同)的编号列表,最多支持100个。(备注:该参数和合同组编号必须二选一)
示例值:["xxx", "yyy"]
FlowGroupIdString合同组编号(备注:该参数和合同(流程)编号数组必须二选一)
EndpointString签署链接类型,可以设置的参数如下

- WEIXINAPP:短链直接跳小程序 (默认类型)
- CHANNEL:跳转H5页面
- APP:第三方APP或小程序跳转电子签小程序
- LONGURL2WEIXINAPP:长链接跳转小程序
示例值:”WEIXINAPP“
GenerateTypeString签署链接生成类型,可以选择的类型如下

- ALL:全部签署方签署链接,此时不会给自动签署的签署方创建签署链接(默认类型)
- CHANNEL:第三方平台子客企业企业
- NOT_CHANNEL:非第三方平台子客企业企业
- PERSON:个人
- FOLLOWER:关注方,目前是合同抄送方
示例值:CHANNEL
OrganizationNameString非第三方平台子客企业参与方的企业名称,GenerateType为"NOT_CHANNEL"时必填
示例值:测试企业
NameString参与人姓名
GenerateType为"PERSON"(即个人签署方)时必填
示例值:张三
MobileString参与人手机号
GenerateType为"PERSON"或"FOLLOWER"时必填
示例值:xxx
OrganizationOpenIdString第三方平台子客企业的企业OpenId,GenerateType为"CHANNEL"时必填
示例值:xxx
OpenIdString第三方平台子客企业参与人OpenId,GenerateType为"CHANNEL"时可用,指定到具体参与人, 仅展示已经实名的经办人信息
示例值:xxx
AutoJumpBackBooleanEndpoint为"APP" 类型的签署链接,可以设置此值;支持调用方小程序打开签署链接,在电子签小程序完成签署后自动回跳至调用方小程序
示例值:false
JumpUrlString签署完之后的H5页面的跳转链接,针对Endpoint为CHANNEL时有效,最大长度1000个字符。
示例值:“https://qq.com”
Hides.NArray of Integer生成的签署链接在签署过程隐藏的按钮列表, 可以设置隐藏的按钮列表如下

- 0:合同签署页面更多操作按钮
- 1:合同签署页面更多操作的拒绝签署按钮
- 2:合同签署页面更多操作的转他人处理按钮
- 3:签署成功页的查看详情按钮
RecipientIds.NArray of String签署节点ID,用于补充动态签署人,使用此参数需要与flow_ids数量一致

3. 输出参数

参数名称类型描述
SignUrlInfosArray of SignUrlInfo签署参与者签署H5链接信息数组
ErrorMessagesArray of String生成失败时的错误信息,成功返回”“,顺序和出参SignUrlInfos保持一致
示例值:["xx","yy"]
RequestIdString唯一请求 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请升级到对应版本后即可使用该接口。