跳到主要内容

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

1. 接口描述​

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

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

腾讯电子签小程序的AppID 和 原始Id如下:

小程序AppID原始ID
腾讯电子签（正式版）wxa023b292fd19d41dgh_da88f6188665
腾讯电子签Demowx371151823f6f3edfgh_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 结构体以获取详细定义。

此接口下面信息必填。

  • 渠道应用标识: 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跳转适合此类型，此时返回长链


注：动态签署人场景，如果签署链接类型设置为APP，则仅支持跳转到封面页。

详细使用场景可以参考接口描述说明中的 主要使用场景EndPoint分类

示例值：”WEIXINAPP“
GenerateType否String签署链接生成类型，可以选择的类型如下

  • ALL：(默认)全部签署方签署链接，此时不会给自动签署(静默签署)的签署方创建签署链接
  • CHANNEL：第三方子企业员工签署方
  • NOT_CHANNEL：SaaS平台企业员工签署方
  • PERSON：个人/自然人签署方
  • FOLLOWER：关注方，目前是合同抄送方
  • RECIPIENT：获取RecipientId对应的签署链接，可用于生成动态签署人补充链接

示例值：CHANNEL
OrganizationName否StringSaaS平台企业员工签署方的企业名称
如果名称中包含英文括号()，请使用中文括号（）代替。

注: 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，请大写)。
  • 港澳居民来往内地通行证号码共11位。第1位为字母，“H”字头签发给香港居民，“M”字头签发给澳门居民；第2位至第11位为数字。
  • 港澳台居民居住证号码编码规则与中国大陆身份证相同，应为18位字符串。

示例值：620000198802020000
OrganizationOpenId否String第三方平台子客企业的企业的标识, 即OrganizationOpenId
注: GenerateType为"CHANNEL"时必填
示例值：org_dianziqian
OpenId否String第三方平台子客企业员工的标识OpenId，GenerateType为"CHANNEL"时可用，指定到具体参与人, 仅展示已经实名的经办人信息

注：
如果传进来的OpenId已经实名并且加入企业， 则忽略Name，IdCardType，IdCardNumber，Mobile这四个入参（会用此OpenId实名的身份证和登录的手机号覆盖）
示例值：n9527
AutoJumpBack否Boolean签署完成后是否自动回跳
  • false：否, 签署完成不会自动跳转回来(默认)
  • true：是, 签署完成会自动跳转回来


注:
1. 该参数只针对APP类型（电子签小程序跳转贵方小程序）场景 的签署链接有效
2. 手机应用APP 或 微信小程序需要监控界面的返回走后序逻辑, 微信小程序的文档可以参考这个
3. 电子签小程序跳转贵方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，
FlowGroupUrlInfo否FlowGroupUrlInfo合同组相关信息，指定合同组子合同和签署方的信息，用于补充动态签署人。

3. 输出参数​

参数名称类型描述
SignUrlInfosArray of SignUrlInfo签署参与者签署H5链接信息数组
ErrorMessagesArray of String生成失败时的错误信息，成功返回”“，顺序和出参SignUrlInfos保持一致
示例值：["无效的流程合同Id","无此参与人"]
RequestIdString唯一请求 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请升级到对应版本后即可使用该接口。
更多开发者交流反馈
购买咨询
4006-808-062
4006-808-062