获取H5批量签署或查看链接

最近更新时间:2025-05-23 01:18:45

我的收藏

1. 接口描述

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

该接口用于发起合同后,生成个人/企业用户的批量待办链接。
注意:

  1. 该接口可生成签署人的批量、合同组签署/查看链接 。
  2. 该签署链接有效期为30分钟,过期后将失效,如需签署可重新创建批量签署链接 。
  3. 该接口返回的签署链接适用于APP集成的场景,支持APP打开或浏览器直接打开,不支持微信小程序嵌入
    跳转到小程序的实现,参考微信官方文档(分为全屏半屏两种方式),如何配置也可以请参考: 跳转电子签小程序配置
  4. 因h5涉及人脸身份认证能力基于慧眼人脸核身,对Android和iOS系统均有一定要求, 因此App嵌入H5签署合同需要按照慧眼提供的慧眼人脸核身兼容性文档做兼容性适配
  5. H5签署现在仅支持中国大陆身份证和中国港澳台居民居住证。

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

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

2. 输入参数

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

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:CreateBatchQuickSignUrl。
Version String 公共参数,本接口取值:2020-11-11。
Region String 公共参数,此参数为可选参数。
FlowApproverInfo FlowCreateApprover 批量签署的流程签署人,其中姓名(ApproverName)、参与人类型(ApproverType)必传,手机号(ApproverMobile)和证件信息(ApproverIdCardType、ApproverIdCardNumber)可任选一种或全部传入。

  • 若为个人参与方:ApproverType=1
  • 若为企业参与方:ApproverType=0。同时 OrganizationName 参数需传入参与方企业名称。


注:
1. 暂不支持签署人拖动签署控件功能,以及签批控件。
2. 当需要通过短信验证码签署时,手机号ApproverMobile需要与发起合同时填写的用户手机号一致。
Agent Agent 代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。
Operator UserInfo 执行本接口操作的员工信息。
注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。
FlowIds.N Array of String 批量签署的合同流程ID数组。
注: 在调用此接口时,请确保合同流程均为本企业发起,且合同数量不超过100个。
示例值:["yDtwEUUckp7f8w6uUuBHsZJd9KcpXpMH"]
FlowGroupId String 合同组编号
注:该参数和合同流程ID数组必须二选一
示例值:yDwFdUUckpsveo27UEQPEVo14KnASuGI
JumpUrl String 签署完之后的H5页面的跳转链接,此链接及支持http://和https://,最大长度1000个字符。(建议https协议)
示例值:https://jump.cn/jump
SignatureTypes.N Array of Integer 指定批量签署合同的签名类型,可传递以下值:
  • 0:手写签名(默认)
  • 1:OCR楷体
  • 2:姓名印章
  • 3:图片印章
  • 4:系统签名

注:
  • 默认情况下,签名类型为手写签名
  • 您可以传递多种值,表示可用多种签名类型。
  • 该参数会覆盖您合同中的签名类型,若您在发起合同时限定了签名类型(赋值签名类型给ComponentTypeLimit),请将这些签名类型赋予此参数
  • 若签署方为企业员工,此参数无效,签名方式将以合同中为准。


示例值:[0, 1, 2, 3, 4]
ApproverSignTypes.N Array of Integer 指定批量签署合同的认证校验方式,可传递以下值:
  • 1:人脸认证(默认),需进行人脸识别成功后才能签署合同
  • 2:密码认证(默认),需输入与用户在腾讯电子签设置的密码一致才能校验成功进行合同签署
  • 3:运营商三要素,需到运营商处比对手机号实名信息(名字、手机号、证件号)校验一致才能成功进行合同签署。

注:
  • 默认情况下,认证校验方式为人脸和密码认证
  • 您可以传递多种值,表示可用多种认证校验方式。

示例值:[1, 2, 3]
SignTypeSelector Integer 生成H5签署链接时,您可以指定签署方签署合同的认证校验方式的选择模式,可传递一下值:
  • 0:签署方自行选择,签署方可以从预先指定的认证方式中自由选择;
  • 1:自动按顺序首位推荐,签署方无需选择,系统会优先推荐使用第一种认证方式。

注:
不指定该值时,默认为签署方自行选择。
示例值:LoginWithoutMobile
FlowBatchUrlInfo FlowBatchUrlInfo 批量签署合同相关信息,指定合同和签署方的信息,用于补充动态签署人。

注: 若签署方为企业员工,暂不支持通过H5端进行动态签署人的补充
Intention Intention 只有在生成H5签署链接的情形下( 如调用获取H5签署链接获取H5批量签署链接等接口),该配置才会生效。 您可以指定H5签署视频核身的意图配置,选择问答模式或点头模式的语音文本。

注意:
1. 视频认证为白名单功能,使用前请联系对接的客户经理沟通
2. 使用视频认证时,生成H5签署链接的时候必须将签署认证方式指定为人脸(即ApproverSignTypes设置成人脸签署)。
3. 签署完成后,可以通过查询签署认证人脸视频获取到当时的视频。
CacheApproverInfo Boolean 缓存签署人信息。在H5签署链接动态领取场景,首次填写后,选择缓存签署人信息,在下次签署人点击领取链接时,会自动将个人信息(姓名、身份证号、手机号)填入,否则需要每次手动填写。

注: 若参与方为企业员工时,暂不支持对参与方信息进行缓存
示例值:false
CanBatchReject Boolean 是否允许此链接中签署方批量拒签。
  • false (默认): 不允许批量拒签
  • true : 允许批量拒签。


注:合同组暂不支持批量拒签功能。

示例值:false
PresetApproverInfo PresetApproverInfo 预设的动态签署方的补充信息,仅匹配对应信息的签署方才能领取合同。暂时仅对个人参与方生效。

3. 输出参数

参数名称 类型 描述
FlowApproverUrlInfo FlowApproverUrlInfo 签署人签署链接信息
RequestId String 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 为个人用户,创建合同组批量签署链接

  1. 为个人用户生成合同组H5批量签署链接
  2. 使用默认的签名类型
  3. 使用默认的签署方式
  4. 默认跳转到合同列表页

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "Operator": {
        "ClientIp": "1.2.3.4",
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FlowApproverInfo": {
        "ApproverType": 1,
        "ApproverMobile": "13200000000",
        "ApproverName": "典子谦",
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD"
    },
    "FlowGroupId": "yDSLcUUck****ysv1OQYIe9H"
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverMobile": "13200000000",
            "ApproverName": "典子谦",
            "ApproverType": 1,
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0U**xoK&CodeType=QUICK&shortKey=yDw**S2ATh95&token=Y9b**O",
            "SignUrl": "https://essurl.cn/Y9b**O"
        },
        "RequestId": "s169**68"
    }
}

示例2 集团主企业代子企业创建H5批量签署链接

  1. 集团主企业有权限代替子企业发起合同
  2. 个人用户在批量签署的合同中是待签署的状态
  3. 签署的合同中个人用户没有填写控件,只有签名控件
  4. 主企业的版本符合专业版及以上企业版本
  5. 批量签署链接中指定签名类型为手写签名和OCR楷体签名
  6. 批量签署链接中指定意愿确认方式为人脸认证和手机号认证

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "Operator": {
        "ClientIp": "1.2.3.4",
        "UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
    },
    "Agent": {
        "ProxyOrganizationId": "yDxbNUyKQDx3oAUuO4zjEBQGidlGe4hP"
    },
    "FlowApproverInfo": {
        "ApproverType": 1,
        "ApproverMobile": "13200000000",
        "ApproverName": "典子谦",
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD"
    },
    "SignatureTypes": [
        0,
        1
    ],
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowIds": [
        "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
        "yDwFmUUckpst10i3UubBSat8PWOt2iQF"
    ]
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverMobile": "13200000000",
            "ApproverName": "典子谦",
            "ApproverType": 1,
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0U**xoK&CodeType=QUICK&shortKey=yDw**S2ATh95&token=Y9b**O",
            "SignUrl": "https://essurl.cn/Y9b**O"
        },
        "RequestId": "s169**68"
    }
}

示例3 发起合同后,为C端签署人创建H5批量签署链接

  1. 创建批量签署链接的企业与待批量签署的合同属于同一个企业
  2. 批量签署的合同数量不少于1份,不超过100份
  3. 上述合同均为待该C端签署人签署状态
  4. 该C端签署人仅有手写签名控件,不需要填写合同
  5. 企业已经购买了专业版或以上版本套餐

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowApproverInfo": {
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD",
        "ApproverMobile": "13200000000",
        "ApproverName": "典子谦",
        "ApproverType": 1
    },
    "FlowIds": [
        "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
        "yDwFmUUckpst10i3UubBSat8PWOt2iQF"
    ],
    "JumpUrl": "https://abc.com",
    "SignatureTypes": [
        0,
        1
    ]
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverMobile": "13200000000",
            "ApproverName": "典子谦",
            "ApproverType": 1,
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwiB**FOE&CodeType=QUICK&shortKey=yDwiB**1e5&token=Rg0**Q",
            "SignUrl": "https://essurl.cn/Rg0**Q"
        },
        "RequestId": "s1698**9686"
    }
}

示例4 创建H5批量签署链接,签署完成后跳转到指定地址

  1. 个人用户在批量签署的合同中是待签署的状态
  2. 签署的合同中个人用户没有填写控件,只有签名控件
  3. 企业的版本符合专业版及以上企业版本
  4. 批量签署链接中指定签名类型为手写签名和OCR楷体签名
  5. 批量签署链接中指定意愿确认方式为人脸认证和手机号认证
  6. 批量签署链接中指定签署完成后的跳转地址为https://abc.com

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "Operator": {
        "ClientIp": "1.2.3.4",
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FlowApproverInfo": {
        "ApproverType": 1,
        "ApproverMobile": "13200000000",
        "ApproverName": "典子谦",
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD"
    },
    "JumpUrl": "https://abc.com",
    "SignatureTypes": [
        0,
        1
    ],
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowIds": [
        "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
        "yDwFmUUckpst10i3UubBSat8PWOt2iQF"
    ]
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverMobile": "13200000000",
            "ApproverName": "典子谦",
            "ApproverType": 1,
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0U**xoK&CodeType=QUICK&shortKey=yDw**S2ATh95&token=Y9b**O",
            "SignUrl": "https://essurl.cn/Y9b**O"
        },
        "RequestId": "s169**68"
    }
}

示例5 错误示例-创建签署链接的企业不是待批量签署合同的发起方

  1. 企业A创建了一些合同
  2. 企业B用上述合同编号创建批量签署链接

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "Operator": {
        "ClientIp": "1.2.3.4",
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FlowApproverInfo": {
        "ApproverType": 1,
        "ApproverMobile": "13200000000",
        "ApproverName": "典子谦",
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD"
    },
    "SignatureTypes": [
        0,
        1
    ],
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowIds": [
        "yDwFkUUckpstzjhfUugNAWf1KibXqS26"
    ]
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "FailedOperation",
            "Message": "不支持非当前企业发起的合同,生成批量签署链接。不满足合同:[\"yDwFkUUckpstzjhfUugNAWf1KibXqS26\"]"
        },
        "RequestId": "s1698**02"
    }
}

示例6 错误示例-创建签署链接中指定的C端个人用户不在合同参与人列表中

  1. 合同已经创建完成,其中个人用户为A
  2. 创建个人H5批量签署链接中的ApproverType指定了个人类型(ApproverType=1)
  3. 创建个人H5批量签署链接中的姓名、手机号、证件信息指定为用户B

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "Operator": {
        "ClientIp": "1.2.3.4",
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FlowApproverInfo": {
        "ApproverType": 1,
        "ApproverMobile": "13200000000",
        "ApproverName": "典子谦",
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD"
    },
    "SignatureTypes": [
        0,
        1
    ],
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowIds": [
        "yDwFkUUckpstzjhfUugNAWf1KibXqS26"
    ]
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "FailedOperation",
            "Message": "在合同[yDwFkUUckpstzjhfUugNAWf1KibXqS26]中无法找到参与人[姓名:典子谦,手机号:13200000000,证件号:620000198802020000,证件类型:ID_CARD,参与人类型:1]"
        },
        "RequestId": "s1698**53"
    }
}

示例7 错误示例,为个人用户生成H5批量签署链接,没有指定合同流程ID信息,也没有指定合同组ID信息

  1. 没有指定合同流程ID信息
  2. 没有指定合同组ID信息

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "Operator": {
        "ClientIp": "1.2.3.4",
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FlowApproverInfo": {
        "ApproverType": 1,
        "ApproverMobile": "13200000000",
        "ApproverName": "典子谦",
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD"
    }
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "FailedOperation",
            "Message": "流程ID和合同组ID不能同时为空,请检查参数后再试"
        },
        "RequestId": "s17007***76147"
    }
}

示例8 发起合同后,获取C端签署人的H5批量领取链接

  1. 创建批量签署链接的合同签署方,必须都是动态签署人且未补充。
  2. 批量签署的合同数量不少于1份,不超过100份
  3. 上述合同签署方类型必须一致,均为待C端签署人签署状态
  4. 企业已经购买了专业版或以上版本套餐

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowApproverInfo": {
        "ApproverType": 1
    },
    "FlowIds": [
        "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
        "yDwFmUUckpst10i3UubBSat8PWOt2iQF"
    ],
    "JumpUrl": "https://abc.com",
    "SignatureTypes": [
        0,
        1
    ],
    "FlowBatchUrlInfo": {
        "FlowBatchApproverInfos": [
            {
                "FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
                "RecipientId": "yDCmvUUckpup6xhwUxKRs1rIRejg254i"
            },
            {
                "FlowId": "yDwFmUUckpst10i3UubBSat8PWOt2iQF",
                "RecipientId": "yDCmvUUckpup6xh1UxKRs1rwHjT5QyHH"
            }
        ]
    }
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverMobile": "",
            "ApproverName": "",
            "ApproverType": 1,
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwiB**FOE&CodeType=QUICK&shortKey=yDwiB**1e5&token=Rg0**Q",
            "SignUrl": "https://essurl.cn/Rg0**Q"
        },
        "RequestId": "s1698**9686"
    }
}

示例9 为个人用户,创建合同组批量签署链接,并且指定视频问答模式的认证方式

  1. 为个人用户生成合同组H5批量签署链接
  2. 使用默认的签名类型
  3. 使用默认的签署方式
  4. 默认跳转到合同列表页
    5.指定视频问答模式的认证方式

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "Operator": {
        "ClientIp": "1.2.3.4",
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FlowApproverInfo": {
        "ApproverType": 1,
        "ApproverMobile": "13200000000",
        "ApproverName": "典子谦",
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD"
    },
    "FlowGroupId": "yDSLcUUck****ysv1OQYIe9H",
    "ApproverSignTypes": [
        1
    ],
    "Intention": {
        "IntentionType": 1,
        "IntentionQuestions": [
            {
                "Question": "请问,您是否同意签署本协议?可语音回复“同意”或“不同意”。",
                "Answers": [
                    "同意",
                    "我同意"
                ]
            }
        ]
    }
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverMobile": "13200000000",
            "ApproverName": "典子谦",
            "ApproverType": 1,
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0U**xoK&CodeType=QUICK&shortKey=yDw**S2ATh95&token=Y9b**O",
            "SignUrl": "https://essurl.cn/Y9b**O"
        },
        "RequestId": "s169**68"
    }
}

示例10 为企业用户,创建合同批量签署链接

  1. 为企业员工生成合同组H5批量签署链接
  2. 使用默认的签署方式

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateBatchQuickSignUrl
<公共请求参数>

{
    "Operator": {
        "ClientIp": "1.2.3.4",
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FlowApproverInfo": {
        "ApproverType": 1,
        "ApproverMobile": "13200000000",
        "ApproverName": "典员工",
        "ApproverIdCardNumber": "620000198802020000",
        "ApproverIdCardType": "ID_CARD",
        "OrganizationName": "xxxx公司"
    },
    "FlowIds": [
        "yDSLcUUck****ysv1OQYIe9H",
        "ysv1OQYIe9H****yDSLcUUck"
    ]
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverMobile": "13200000000",
            "ApproverName": "典员工",
            "ApproverType": 0,
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0U**xoK&CodeType=QUICK&shortKey=yDw**S2ATh95&token=Y9b**O",
            "SignUrl": "https://essurl.cn/Y9b**O"
        },
        "RequestId": "s169**68"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码 描述
FailedOperation 操作失败。
InvalidParameterValue 参数取值错误。
MissingParameter 缺少参数错误。
ResourceNotFound 资源不存在。
UnauthorizedOperation.NoPermissionFeature 请升级到对应版本后即可使用该接口。