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

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=yDwiBUUcduRvquCSX8wd& shortKey=yDwivUA*W1yRsTre3
APP	贵方小程序跳转腾讯电子签小程序签署场景	贵方App直接跳转到小程序后, 在腾讯电子签小程序签署完成后返回贵方小程序的场景跳转到腾讯电子签小程序的实现可以参考微信官方文档全屏方式和半屏方式此时返回的SignUrl就是官方文档中的path 示例:pages/guide?from=default&where=mini& to=CONTRACT_DETAIL& id=yDwiBUUcduRvquCSX8wd& shortKey=yDwivUA*W1yRsTre3

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

推荐使用 API Explorer

点击调试

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

2. 输入参数

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

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateSignUrls。
Version	是	String	公共参数，本接口取值：2021-05-26。
Region	否	String	公共参数，此参数为可选参数。
Agent	是	Agent	关于渠道应用的相关信息，包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容，您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。此接口下面信息必填。渠道应用标识: Agent.AppId 第三方平台子客企业标识: Agent.ProxyOrganizationOpenId 第三方平台子客企业中的员工标识: Agent. ProxyOperator.OpenId 第三方平台子客企业和员工必须已经过实名认证
FlowIds.N	否	Array of String	合同流程ID数组，最多支持100个。注: `该参数和合同组编号必须二选一` 示例值：["yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm"]
FlowGroupId	否	String	合同组编号注：`该参数和合同流程ID数组必须二选一`
Endpoint	否	String	签署链接类型,可以设置的参数如下 WEIXINAPP :(默认)跳转电子签小程序的http_url, 短信通知或者H5跳转适合此类型，此时返回短链 CHANNEL :带有H5引导页的跳转电子签小程序的链接 APP :第三方App或小程序跳转电子签小程序的path, App或者小程序跳转适合此类型 LONGURL2WEIXINAPP :跳转电子签小程序的链接, H5跳转适合此类型，此时返回长链详细使用场景可以参数接口说明中的主要使用场景可以更加EndPoint分类如下示例值：”WEIXINAPP“
GenerateType	否	String	签署链接生成类型，可以选择的类型如下 ALL：(默认)全部签署方签署链接，此时不会给自动签署(静默签署)的签署方创建签署链接 CHANNEL：第三方子企业员工签署方 NOT_CHANNEL：SaaS平台企业员工签署方 PERSON：个人/自然人签署方 FOLLOWER：关注方，目前是合同抄送方 RECIPIENT：获取RecipientId对应的签署链接，可用于生成动态签署人补充链接示例值：CHANNEL
OrganizationName	否	String	SaaS平台企业员工签署方的企业名称如果名称中包含英文括号()，请使用中文括号（）代替。注: `GenerateType为"NOT_CHANNEL"时必填` 示例值：典子谦示例企业
Name	否	String	合同流程里边参与方的姓名。注: `GenerateType为"PERSON"(即个人签署方)时必填` 示例值：典子谦
Mobile	否	String	合同流程里边签署方经办人手机号码，支持国内手机号11位数字(无需加+86前缀或其他字符)。注: `GenerateType为"PERSON"或"FOLLOWER"时必填` 示例值：13200000000
IdCardType	否	String	证件类型，支持以下类型 ID_CARD : 居民身份证 HONGKONG_AND_MACAO : 港澳居民来往内地通行证 HONGKONG_MACAO_AND_TAIWAN : 港澳台居民居住证(格式同居民身份证) 示例值：ID_CARD
IdCardNumber	否	String	证件号码，应符合以下规则居民身份证号码应为18位字符串，由数字和大写字母X组成(如存在X，请大写)。港澳居民来往内地通行证号码应为9位字符串，第1位为“C”，第2位为英文字母(但“I”、“O”除外)，后7位为阿拉伯数字。港澳台居民居住证号码编码规则与中国大陆身份证相同，应为18位字符串。示例值：620000198802020000
OrganizationOpenId	否	String	第三方平台子客企业的企业的标识, 即OrganizationOpenId 注: `GenerateType为"CHANNEL"时必填` 示例值：org_dianziqian
OpenId	否	String	第三方平台子客企业员工的标识OpenId，GenerateType为"CHANNEL"时可用，指定到具体参与人, 仅展示已经实名的经办人信息示例值：n9527
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数量一致并且一一对应, 表示在对应同序号的流程中的参与角色ID`，

3. 输出参数

参数名称	类型	描述
SignUrlInfos	Array of SignUrlInfo	签署参与者签署H5链接信息数组
ErrorMessages	Array of String	生成失败时的错误信息，成功返回”“，顺序和出参SignUrlInfos保持一致示例值：["无效的流程合同Id","无此参与人"]
RequestId	String	唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 获取动态签署人补充链接

获取动态签署人补充链接，创建合同时未指定具体签署人，可获取链接后推送给指定的人进行补充注： 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"
            }
        ]
    }
}

示例2 给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"
    }
}

示例3 给个人/自然人生成签署链接

给个人/自然人生成签署链接 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"
    }
}

示例4 给子客企业生成签署链接

给子客企业生成签署链接 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"
    }
}

示例5 给所有签署人的签署链接

给所有签署人的签署链接 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"
    }
}

示例6 指定证件信息，为个人/自然人生成签署链接

给个人/自然人生成签署链接 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	请升级到对应版本后即可使用该接口。

1. 接口描述​

2. 输入参数​

3. 输出参数​

4. 示例​

示例1 获取动态签署人补充链接​

输入示例​

输出示例​

示例2 给SaaS平台企业员工签署方生成签署链接​

输入示例​

输出示例​

示例3 给个人/自然人生成签署链接​

输入示例​

输出示例​

示例4 给子客企业生成签署链接​

输入示例​

输出示例​

示例5 给所有签署人的签署链接​

输入示例​

输出示例​

示例6 指定证件信息，为个人/自然人生成签署链接​

输入示例​

输出示例​

5. 错误码​

1. 接口描述

2. 输入参数

3. 输出参数

4. 示例

示例1 获取动态签署人补充链接

输入示例

输出示例

示例2 给SaaS平台企业员工签署方生成签署链接

输入示例

输出示例

示例3 给个人/自然人生成签署链接

输入示例

输出示例

示例4 给子客企业生成签署链接

输入示例

输出示例

示例5 给所有签署人的签署链接

输入示例

输出示例

示例6 指定证件信息，为个人/自然人生成签署链接

输入示例

输出示例

5. 错误码