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

1. 接口描述

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

该接口用于发起合同后，生成个人用户的批量待办链接, 暂时不支持企业端签署。 注意：

该接口目前仅支持签署人类型是个人签署方的批量签署场景(ApproverType=1)。
该接口可生成C端签署人的批量签署/查看链接，签署控件仅支持手写签名(控件类型为SIGN_SIGNATURE)和时间类型的签署控件 。
该签署链接有效期为30分钟，过期后将失效，如需签署可重新创建批量签署链接。
该接口返回的签署链接适用于APP集成的场景，支持APP打开或浏览器直接打开，不支持微信小程序嵌入。跳转到小程序的实现，参考微信官方文档(分为全屏、半屏两种方式)，如何配置也可以请参考: 跳转电子签小程序配置。
因h5涉及人脸身份认证能力基于慧眼人脸核身，对Android和iOS系统均有一定要求，因此App嵌入H5签署合同需要按照慧眼提供的慧眼人脸核身兼容性文档做兼容性适配。

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

推荐使用 API Explorer

点击调试

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

2. 输入参数

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

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：ChannelCreateBatchQuickSignUrl。
Version	是	String	公共参数，本接口取值：2021-05-26。
Region	否	String	公共参数，此参数为可选参数。
FlowApproverInfo	是	FlowApproverInfo	批量签署的流程签署人，其中姓名(ApproverName)、参与人类型(ApproverType)必传，手机号(ApproverMobile)和证件信息(ApproverIdCardType、ApproverIdCardNumber)可任选一种或全部传入。注: `1. ApproverType目前只支持个人类型的签署人。` `2. 签署人只能有手写签名和时间类型的签署控件，其他类型的填写控件和签署控件暂时都未支持。` `3. 当需要通过短信验证码签署时，手机号ApproverMobile需要与发起合同时填写的用户手机号一致。`
Agent	否	Agent	关于渠道应用的相关信息，包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容，您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。
FlowIds.N	否	Array of String	批量签署的合同流程ID数组。注: `在调用此接口时，请确保合同流程均为本企业发起，且合同数量不超过100个。`
FlowGroupId	否	String	合同组编号注：`该参数和合同流程ID数组必须二选一` 示例值：yDwFdUUckpsveo27UEQPEVo14KnASuGI
JumpUrl	否	String	签署完之后的H5页面的跳转链接，此链接及支持http://和https://，最大长度1000个字符。(建议https协议)
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：自动按顺序首位推荐，签署方无需选择，系统会优先推荐使用第一种认证方式。注： `不指定该值时，默认为签署方自行选择。` 示例值：0
FlowBatchUrlInfo	否	FlowBatchUrlInfo	批量签署合同相关信息，指定合同和签署方的信息，用于补充动态签署人。
Intention	否	Intention	只有在生成H5签署链接的情形下（如调用获取H5签署链接、获取H5批量签署链接等接口），该配置才会生效。您可以指定H5签署视频核身的意图配置，选择问答模式或点头模式的语音文本。注意： 1. 视频认证为白名单功能，使用前请联系对接的客户经理沟通。 2. 使用视频认证时，生成H5签署链接的时候必须将签署认证方式指定为人脸（即ApproverSignTypes设置成人脸签署）。 3. 签署完成后，可以通过查询签署认证人脸视频获取到当时的视频。
CacheApproverInfo	否	Boolean	是否开启缓存签署人信息

3. 输出参数

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

4. 示例

示例1 为个人用户生成合同组H5批量签署链接

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

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "Mobile": "13200000000",
        "Name": "典子谦",
        "IdCardNumber": "620000198802020000",
        "IdCardType": "ID_CARD"
    },
    "FlowGroupId": "yDSL9UUckpo*****jwSsug2y3cW"
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverType": "PERSON",
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0**BWW4MYlpI&CodeType=QUICK&shortKey=yDwi**KF45&token=C**E",
            "Mobile": "13200000000",
            "Name": "典子谦",
            "SignUrl": "https://test.essurl.cn/C**E"
        },
        "RequestId": "s16986**08"
    }
}

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

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

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "IdCardNumber": "620000198802020000",
        "IdCardType": "ID_CARD",
        "Mobile": "13200000000",
        "Name": "典子谦"
    },
    "FlowIds": [
        "yDwFkUUckpstin4sUuZjBEY5Ia2XB7sz",
        "yDwFkUUckpstzjhfUugNAWf1KibXqS26"
    ],
    "JumpUrl": "https://abc.com",
    "SignatureTypes": [
        0,
        1
    ]
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverType": "PERSON",
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0**BWW4MYlpI&CodeType=QUICK&shortKey=yDwi**KF45&token=C**E",
            "Mobile": "13200000000",
            "Name": "典子谦",
            "SignUrl": "https://test.essurl.cn/C**E"
        },
        "RequestId": "s16986**08"
    }
}

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

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

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "Mobile": "13200000000",
        "Name": "典子谦",
        "IdCardNumber": "620000198802020000",
        "IdCardType": "ID_CARD"
    },
    "JumpUrl": "https://abc.com",
    "SignatureTypes": [
        0,
        1
    ],
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowIds": [
        "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
        "yDwFmUUckpst10i3UubBSat8PWOt2iQF"
    ]
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverType": "PERSON",
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0**BWW4MYlpI&CodeType=QUICK&shortKey=yDwi**KF45&token=C**E",
            "Mobile": "13200000000",
            "Name": "典子谦",
            "SignUrl": "https://test.essurl.cn/C**E"
        },
        "RequestId": "s16986**08"
    }
}

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

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

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "Mobile": "13200000000",
        "Name": "典子谦",
        "IdCardNumber": "620000198802020000",
        "IdCardType": "ID_CARD"
    },
    "SignatureTypes": [
        0,
        1
    ],
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowIds": [
        "yDwFkUUckpstzjhfUugNAWf1KibXqS26"
    ]
}

输出示例

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

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

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

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "Mobile": "13200000000",
        "Name": "典子谦",
        "IdCardNumber": "620000198802020000",
        "IdCardType": "ID_CARD"
    },
    "SignatureTypes": [
        0,
        1
    ],
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowIds": [
        "yDwFkUUckpstzjhfUugNAWf1KibXqS26"
    ]
}

输出示例

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

示例6 错误示例-为个人用户生成H5批量签署链接，既传入了合同流程ID信息，又传入了合同组ID信息

指定了合同流程ID信息
指定了合同组ID信息

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "Mobile": "13200000000",
        "Name": "典子谦",
        "IdCardNumber": "620000198802020000",
        "IdCardType": "ID_CARD"
    },
    "FlowGroupId": "yDSL9UUckpo*****jwSsug2y3cW",
    "FlowIds": [
        "yDRSRUUgygj6******7wUuaaadqccc",
        "yDRSRUUgygj6rq***Cpxxxsdfa"
    ]
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "FailedOperation",
            "Message": "请勿同时传入流程ID和合同组ID，请检查参数后再试"
        },
        "RequestId": "s17007305****493"
    }
}

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

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

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "Mobile": "13200000000",
        "Name": "典子谦",
        "IdCardNumber": "620000198802020000",
        "IdCardType": "ID_CARD"
    }
}

输出示例

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

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

创建批量签署链接的合同签署方，必须都是动态签署人且未补充。
批量签署的合同数量不少于1份，不超过100份
上述合同签署方类型必须一致，均为待C端签署人签署状态
企业已经购买了专业版或以上版本套餐
获取领取链接通过指定RecipientId定位签署方，可以从发起合同的返回结果中获取

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "ApproverSignTypes": [
        1,
        3
    ],
    "FlowApproverInfo": {
        "ApproverType": "PERSON"
    },
    "FlowIds": [
        "yDwFkUUckpstin4sUuZjBEY5Ia2XB7sz",
        "yDwFkUUckpstzjhfUugNAWf1KibXqS26"
    ],
    "JumpUrl": "https://abc.com",
    "SignatureTypes": [
        0,
        1
    ],
    "FlowBatchUrlInfo": {
        "FlowBatchApproverInfos": [
            {
                "FlowId": "yDwFkUUckpstin4sUuZjBEY5Ia2XB7sz",
                "RecipientId": "yDCmvUUckpup6xhwUxKRs1rIRejg254i"
            },
            {
                "FlowId": "yDwFkUUckpstzjhfUugNAWf1KibXqS26",
                "RecipientId": "yDCmvUUckpup6xh1UxKRs1rwHjT5QyHH"
            }
        ]
    }
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverType": "PERSON",
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0**BWW4MYlpI&CodeType=QUICK&shortKey=yDwi**KF45&token=C**E",
            "Mobile": "",
            "Name": "",
            "SignUrl": "https://test.essurl.cn/C**E"
        },
        "RequestId": "s16986**08"
    }
}

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

为个人用户生成合同组H5批量签署链接, 并且指定视频问答模式的认证方式

输入示例

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

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6rq7wUuO4zjECxndqQApl"
    },
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "Mobile": "13200000000",
        "Name": "典子谦",
        "IdCardNumber": "620000198802020000",
        "IdCardType": "ID_CARD"
    },
    "ApproverSignTypes": [
        1
    ],
    "Intention": {
        "IntentionType": 1,
        "IntentionQuestions": [
            {
                "Question": "请问，您是否同意签署本协议？可语音回复“同意”或“不同意”。",
                "Answers": [
                    "同意",
                    "我同意"
                ]
            }
        ]
    },
    "FlowGroupId": "yDSL9UUckpo*****jwSsug2y3cW"
}

输出示例

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverType": "PERSON",
            "LongUrl": "https://quick.qian.tencent.cn/guide?Code=yDwi0**BWW4MYlpI&CodeType=QUICK&shortKey=yDwi**KF45&token=C**E",
            "Mobile": "13200000000",
            "Name": "典子谦",
            "SignUrl": "https://test.essurl.cn/C**E"
        },
        "RequestId": "s16986**08"
    }
}

5. 错误码

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

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

1. 接口描述​

2. 输入参数​

3. 输出参数​

4. 示例​

示例1 为个人用户生成合同组H5批量签署链接​

输入示例​

输出示例​

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

输入示例​

输出示例​

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

输入示例​

输出示例​

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

输入示例​

输出示例​

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

输入示例​

输出示例​

示例6 错误示例-为个人用户生成H5批量签署链接，既传入了合同流程ID信息，又传入了合同组ID信息​

输入示例​

输出示例​

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

输入示例​

输出示例​

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

输入示例​

输出示例​

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

输入示例​

输出示例​

5. 错误码​

1. 接口描述

2. 输入参数

3. 输出参数

4. 示例

示例1 为个人用户生成合同组H5批量签署链接

输入示例

输出示例

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

输入示例

输出示例

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

输入示例

输出示例

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

输入示例

输出示例

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

输入示例

输出示例

示例6 错误示例-为个人用户生成H5批量签署链接，既传入了合同流程ID信息，又传入了合同组ID信息

输入示例

输出示例

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

输入示例

输出示例

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

输入示例

输出示例

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

输入示例

输出示例

5. 错误码