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

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	合同流程签署方的组织机构名称。如果名称中包含英文括号()，请使用中文括号（）代替。注: `获取B端动态签署人领取链接时,可指定此字段来预先设定签署人的企业,预设后只能以该企业身份去领取合同并完成签署` 示例值：典子谦示例企业
Name	否	String	合同流程里边签署方经办人的姓名。示例值：典子谦
Mobile	否	String	合同流程里边签署方经办人手机号码，支持国内手机号11位数字(无需加+86前缀或其他字符)。示例值：13200000000
IdCardType	否	String	证件类型，支持以下类型 ID_CARD : 居民身份证 HONGKONG_AND_MACAO : 港澳居民来往内地通行证 HONGKONG_MACAO_AND_TAIWAN : 港澳台居民居住证(格式同居民身份证) 示例值：ID_CARD
IdCardNumber	否	String	证件号码，应符合以下规则居民身份证号码应为18位字符串，由数字和大写字母X组成(如存在X，请大写)。港澳居民来往内地通行证号码共11位。第1位为字母，“H”字头签发给香港居民，“M”字头签发给澳门居民；第2位至第11位为数字。港澳台居民居住证号码编码规则与中国大陆身份证相同，应为18位字符串。示例值：620000198802020000
EndPoint	否	String	要跳转的链接类型 HTTP：跳转电子签小程序的http_url, 短信通知或者H5跳转适合此类型，此时返回长链 (默认类型) HTTP_SHORT_URL：跳转电子签小程序的http_url, 短信通知或者H5跳转适合此类型，此时返回短链 APP：第三方APP或小程序跳转电子签小程序的path, APP或者小程序跳转适合此类型示例值：HTTP
FlowId	否	String	合同流程ID 注: `如果准备跳转到合同流程签署的详情页面(即PathType=1时)必传, 跳转其他页面可不传` 示例值：yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm
FlowGroupId	否	String	合同流程组的组ID, 在合同流程组场景下，生成合同流程组的签署链接时需要赋值示例值：yDR1AUUgygjazuesUuO4zjESPW4PkfNi
PathType	否	Integer	要跳转到的页面类型 0 : 腾讯电子签小程序个人首页 (默认) 点击查看示例页面 1 : 腾讯电子签小程序流程合同的详情页,即合同签署页面(注:`仅生成短链或者小程序Path时支持跳转合同详情页,即EndPoint传HTTP_SHORT_URL或者APP`)点击查看示例页面 2 : 腾讯电子签小程序合同列表页点击查看示例页面 3 : 腾讯电子签小程序合同封面页（注：`生成动态签署人补充链接时，必须指定为封面页`）点击查看示例页面示例值：1
AutoJumpBack	否	Boolean	签署完成后是否自动回跳 false：否, 签署完成不会自动跳转回来(默认) true：是, 签署完成会自动跳转回来注: 1. 该参数只针对APP类型（电子签小程序跳转贵方小程序）场景的签署链接有效 2. 手机应用APP 或微信小程序需要监控界面的返回走后序逻辑, 微信小程序的文档可以参考这个 3. 电子签小程序跳转贵方APP，不支持自动跳转，必需用户手动点击完成按钮（微信的限制）示例值：false
Agent	否	Agent	代理企业和员工的信息。在集团企业代理子企业操作的场景中，需设置此参数。在此情境下，ProxyOrganizationId（子企业的组织ID）为必填项。
Hides.N	否	Array of Integer	生成的签署链接在签署页面隐藏的按钮列表，可设置如下： 0 :合同签署页面更多操作按钮 1 :合同签署页面更多操作的拒绝签署按钮 2 :合同签署页面更多操作的转他人处理按钮 3 :签署成功页的查看详情按钮注: `字段为数组, 可以传值隐藏多个按钮` 示例值：[1,2]
RecipientId	否	String	签署节点ID，用于生成动态签署人链接完成领取。注：`生成动态签署人补充链接时必传。`
FlowGroupUrlInfo	否	FlowGroupUrlInfo	合同组相关信息，指定合同组子合同和签署方的信息，用于补充动态签署人。

3. 输出参数

参数名称	类型	描述
SchemeUrl	String	腾讯电子签小程序的签署链接。如果EndPoint是APP，得到的链接类似于`pages/guide?from=default&where=mini&id=yDwJSUUirqauh*7jNSxwdirTSGuH&to=CONTRACT_DETAIL&name=&phone=&shortKey=yDwk1xFc5`, 用法可以参加接口描述中的"跳转到小程序的实现" 如果EndPoint是HTTP，得到的链接类似于 `https://res.ess.tencent.cn/cdn/h5-activity/jump-mp.html?where=mini&from=SFY&id=yDwfEUUw4rV6Avz&to=MVP_CONTRACT_COVER&name=%E9%83%5%86%9B`，点击后会跳转到腾讯电子签小程序进行签署如果EndPoint是HTTP_SHORT_URL，得到的链接类似于 `https://essurl.cn/2n42Nd`，点击后会跳转到腾讯电子签小程序进行签署注：生成的链路后面不能再增加参数示例值：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"
    }
}

示例9 获取动态签署人补充链接（短链）并预设企业名

获取动态签署人补充链接，创建合同时未指定具体签署人，可获取链接后推送给指定的人进行补充，预设了企业名称后进入领取链接只能以该企业身份去领取并签署合同注：获取动态签署人补充链接需指定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",
    "OrganizationName": "典子谦有限公司",
    "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"
    }
}

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	请升级到对应版本后即可使用该接口。

1. 接口描述​

2. 输入参数​

3. 输出参数​

4. 示例​

示例1 获取某个合同组的签署链接(短链)​

输入示例​

输出示例​

示例2 获取动态签署人补充链接（短链）​

输入示例​

输出示例​

示例3 获取某个流程合同的签署链接(主代子)​

输入示例​

输出示例​

示例4 获取某个流程合同的小程序跳转签署链接​

输入示例​

输出示例​

示例5 获取合同组动态签署人的领取链接以及二维码​

输入示例​

输出示例​

示例6 获取某个流程合同的小程序跳转签署链接(隐藏某些按钮)​

输入示例​

输出示例​

示例7 指定证件信息，给企业员工生成跳转到电子签小程序的签署链接​

输入示例​

输出示例​

示例8 错误的示例- 获取某个流程合同的小程序跳转签署链接，PathType值没有传对（应该传1- 小程序合同详情）​

输入示例​

输出示例​

示例9 获取动态签署人补充链接（短链）并预设企业名​

输入示例​

输出示例​

5. 错误码​

1. 接口描述

2. 输入参数

3. 输出参数

4. 示例

示例1 获取某个合同组的签署链接(短链)

输入示例

输出示例

示例2 获取动态签署人补充链接（短链）

输入示例

输出示例

示例3 获取某个流程合同的签署链接(主代子)

输入示例

输出示例

示例4 获取某个流程合同的小程序跳转签署链接

输入示例

输出示例

示例5 获取合同组动态签署人的领取链接以及二维码

输入示例

输出示例

示例6 获取某个流程合同的小程序跳转签署链接(隐藏某些按钮)

输入示例

输出示例

示例7 指定证件信息，给企业员工生成跳转到电子签小程序的签署链接

输入示例

输出示例

示例8 错误的示例- 获取某个流程合同的小程序跳转签署链接，PathType值没有传对（应该传1- 小程序合同详情）

输入示例

输出示例

示例9 获取动态签署人补充链接（短链）并预设企业名

输入示例

输出示例

5. 错误码