通过多文件创建合同组签署流程
1. 接口描述
接口请求域名： essbasic.tencentcloudapi.com 。
接口（ChannelCreateFlowGroupByFiles）用于使用 PDF 文件创建合同组签署流程。
合同组是将多个合同签署流程组织在一起，多个合同同时创建，每个签署方得到一个签署链接，一次完成合同组中多个合同的签署。合同组的合同不能拆分一个一个签署，只能作为一个整体签署。
适用场景：该接口适用于需要一次性完成多份合同签署的情况，多份合同一般具有关联性，用户以目录的形式查看合同。
注:
- 此接口静默签(企业自动签)能力为白名单功能，使用前请联系对接的客户经理沟通。
- 合同组暂不支持抄送功能
- 此接口需要依赖文件上传接口生成pdf资源编号（FileIds）进行使用。
可以作为发起方和签署方的角色列表
| 场景编号 | 可作为发起方类型 | 可作为签署方的类型 |
|---|---|---|
| 场景一 | 第三方子企业A员工 | 第三方子企业A员工 |
| 场景二 | 第三方子企业A员工 | 第三方子企业B(不指定经办人) |
| 场景三 | 第三方子企业A员工 | 第三方子企业B员工 |
| 场景四 | 第三方子企业A员工 | 个人/自然人 |
| 场景五 | 第三方子企业A员工 | SaaS平台企业员工 |
注:
1. 发起合同时候, 作为发起方的第三方子企业A员工的企业和员工必须经过实名, 而作为签署方的第三方子企业A员工/个人/自然人/SaaS平台企业员工/第三方子企业B员工企业中的企业和个人/员工可以未实名
2. 不同类型的签署方传参不同, 可以参考开发者中心的FlowApproverInfo结构体说明
3. 合同发起后就会扣减合同的额度, 只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。（过期，拒签，签署完成，解除完成等状态不会返还额度），合同组中每个合同会扣减一个合同额度
4. 静默（自动）签署不支持合同签署方存在填写功能
默认接口请求频率限制：20次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：ChannelCreateFlowGroupByFiles。 |
| Version | 是 | String | 公共参数，本接口取值：2021-05-26。 |
| Region | 否 | String | 公共参数，此参数为可选参数。 |
| FlowFileInfos.N | 是 | Array of FlowFileInfo | 合同组中每个合同签署流程的信息，合同组中最少包含2个合同，不能超过50个合同。 |
| FlowGroupName | 是 | String | 合同组的名称（可自定义此名称），长度不能超过200，只能由中文、字母、数字和下划线组成。 示例值："2023年采购合同们" |
| Agent | 否 | Agent | 关于渠道应用的相关信息，包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容，您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。 此接口下面信息必填。
第三方平台子客企业和员工必须已经经过实名认证 |
| ApproverVerifyType | 否 | String | 合同组中签署人校验和认证的方式：
注意： 1. MobileCheck 方式，未实名的个人/自然人签署方无需进行人脸识别实名认证即可查看合同（但签署合同时仍然需要人脸实名），企业签署方需经过人脸认证。2. 合同组的校验和认证的方式会优先使用，会覆盖合同组中单个合同和合同签署方认证方式的限制配置。 |
| FlowGroupOptions | 否 | FlowGroupOptions | 合同组的签署配置项信息，例如在合同组签署过程中，是否需要对每个子合同进行独立的意愿确认。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| FlowGroupId | String | 合同组ID，为32位字符串。 建议开发者妥善保存此合同组ID，以便于顺利进行后续操作。 注意：此字段可能返回 null，表示取不到有效值。 示例值：yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm |
| FlowIds | Array of String | 合同组中每个合同流程ID，每个ID均为32位字符串。 注: 此数组的顺序和入参中的FlowGroupInfos顺序一致注意：此字段可能返回 null，表示取不到有效值。 示例值：["yDRSRUUgygj6rqi6UuO4zjEBDACwAjgT","yDRS4UUgygqdcjjdUuO4zjEC0osCOsHS"] |
| Approvers | Array of FlowGroupApprovers | 合同组签署方信息。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 创建三个合同组成的合同组
- 入参中FlowFileInfos有三个元素, 表示三个合同组成此合同组
- 每个合同都是B2C合同
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ChannelCreateFlowGroupByFiles
<公共请求参数>
{
"Agent": {
"ProxyOperator": {
"OpenId": "kevin"
},
"ProxyOrganizationOpenId": "zk_online_org",
"AppId": "394fc83e7a1cc97ba27c3342f425c836"
},
"FlowGroupName": "采购合同",
"FlowFileInfos": [
{
"FileIds": [
"yDR1nUU06b46rUy0fKyKocxqVM6QwE88"
],
"FlowName": "番茄的采购合同",
"Deadline": 0,
"FlowDescription": "2023年番茄的采购50吨合同",
"FlowType": "采购合同",
"FlowApprovers": [
{
"ApproverType": "ENTERPRISESERVER",
"OrganizationName": "王五示例企业",
"OrganizationOpenId": "zk_online_org",
"OpenId": "zk",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 100,
"ComponentHeight": 100,
"ComponentValue": "yDR1kUU0zproxUy0fKyKg4XBzdcXcTBg"
}
]
},
{
"Name": "典子谦",
"ApproverType": "PERSON",
"Mobile": "13200000000",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 200,
"ComponentHeight": 100
}
]
}
],
"CustomerData": "5ZCI5ZCM5Lus5ZCI5ZCM5Lus",
"Unordered": true,
"NeedSignReview": false
},
{
"FileIds": [
"yDR1nUU06b46rUy0fKyKocxqVM6QwE88"
],
"FlowName": "黄瓜的采购合同",
"Deadline": 0,
"FlowDescription": "2023年黄瓜的采购50吨合同",
"FlowType": "采购合同",
"FlowApprovers": [
{
"ApproverType": "ENTERPRISESERVER",
"OrganizationName": "李四示例企业",
"OrganizationOpenId": "zk_online_org",
"OpenId": "zk",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 100,
"ComponentHeight": 100,
"ComponentValue": "yDR1kUU0zproxUy0fKyKg4XBzdcXcTBg"
}
]
},
{
"Name": "典子谦",
"ApproverType": "PERSON",
"Mobile": "13200000000",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 200,
"ComponentHeight": 100
}
]
}
],
"CustomerData": "5paw55qE5a2Q5ZCI5ZCMMg==",
"Unordered": true,
"NeedSignReview": false
},
{
"FileIds": [
"yDR1nUU06b46rUy0fKyKocxqVM6QwE88"
],
"FlowName": "马铃薯的采购合同",
"Deadline": 0,
"FlowDescription": "2023年马铃薯的采购50吨合同",
"FlowType": "采购合同",
"FlowApprovers": [
{
"ApproverType": "ENTERPRISESERVER",
"OrganizationName": "张三示例企业",
"OrganizationOpenId": "zk_online_org",
"OpenId": "zk",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 100,
"ComponentHeight": 100,
"ComponentValue": "yDR1kUU0zproxUy0fKyKg4XBzdcXcTBg"
}
]
},
{
"Name": "典子谦",
"ApproverType": "PERSON",
"Mobile": "13200000000",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 200,
"ComponentHeight": 100
}
]
}
],
"CustomerData": "5paw55qE5a2Q5ZCI5ZCMMw==",
"Unordered": true,
"NeedSignReview": false
}
]
}
输出示例
{
"Response": {
"FlowGroupId": "yDwiSUUg0e3wmkUyoVjXzyZbNlhaVk85",
"FlowIds": [
"yDwiSUUg0e3wm2UyoVjXz1xWSYus0Jtc",
"yDwiSUUg0e3wmrUyoVjXzSP9OEVRSAlk",
"yDwiSUUg0e3wmhUyoVjXzByicWYPOymz"
],
"RequestId": "s1698139089675399175"
}
}
示例2 创建三个合同组成的合同组，指定每个子合同第一方为动态签署方
- 入参中FlowFileInfos有三个元素, 表示三个合同组成此合同组
- 每个合同都是B2C合同 3.三份子合同均指定一方为动态签署方（即不指定具体签署人，FillType=1），可在发起后再进行补充。
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ChannelCreateFlowGroupByFiles
<公共请求参数>
{
"Agent": {
"ProxyOperator": {
"OpenId": "kevin"
},
"ProxyOrganizationOpenId": "zk_online_org",
"AppId": "394fc83e7a1cc97ba27c3342f425c836"
},
"FlowGroupName": "采购合同",
"FlowFileInfos": [
{
"FileIds": [
"yDR1nUU06b46rUy0fKyKocxqVM6QwE88"
],
"FlowName": "番茄的采购合同",
"Deadline": 0,
"FlowDescription": "2023年番茄的采购50吨合同",
"FlowType": "采购合同",
"FlowApprovers": [
{
"ApproverType": "ENTERPRISESERVER",
"ApproverOption": {
"FillType": 1
},
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 100,
"ComponentHeight": 100,
"ComponentValue": "yDR1kUU0zproxUy0fKyKg4XBzdcXcTBg"
}
]
},
{
"Name": "典子谦",
"ApproverType": "PERSON",
"Mobile": "13200000000",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 200,
"ComponentHeight": 100
}
]
}
],
"CustomerData": "5ZCI5ZCM5Lus5ZCI5ZCM5Lus",
"Unordered": true,
"NeedSignReview": false
},
{
"FileIds": [
"yDR1nUU06b46rUy0fKyKocxqVM6QwE88"
],
"FlowName": "黄瓜的采购合同",
"Deadline": 0,
"FlowDescription": "2023年黄瓜的采购50吨合同",
"FlowType": "采购合同",
"FlowApprovers": [
{
"ApproverType": "ENTERPRISESERVER",
"ApproverOption": {
"FillType": 1
},
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 100,
"ComponentHeight": 100,
"ComponentValue": "yDR1kUU0zproxUy0fKyKg4XBzdcXcTBg"
}
]
},
{
"Name": "典子谦",
"ApproverType": "PERSON",
"Mobile": "13200000000",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 200,
"ComponentHeight": 100
}
]
}
],
"CustomerData": "5paw55qE5a2Q5ZCI5ZCMMg==",
"Unordered": true,
"NeedSignReview": false
},
{
"FileIds": [
"yDR1nUU06b46rUy0fKyKocxqVM6QwE88"
],
"FlowName": "马铃薯的采购合同",
"Deadline": 0,
"FlowDescription": "2023年马铃薯的采购50吨合同",
"FlowType": "采购合同",
"FlowApprovers": [
{
"ApproverType": "ENTERPRISESERVER",
"ApproverOption": {
"FillType": 1
},
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 100,
"ComponentHeight": 100,
"ComponentValue": "yDR1kUU0zproxUy0fKyKg4XBzdcXcTBg"
}
]
},
{
"Name": "典子谦",
"ApproverType": "PERSON",
"Mobile": "13200000000",
"SignComponents": [
{
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ComponentPage": 1,
"ComponentRequired": true,
"ComponentPosX": 100,
"ComponentPosY": 200,
"ComponentHeight": 100
}
]
}
],
"CustomerData": "5paw55qE5a2Q5ZCI5ZCMMw==",
"Unordered": true,
"NeedSignReview": false
}
]
}
输出示例
{
"Response": {
"Approvers": [
{
"Approvers": [
{
"ApproverRoleName": "",
"RecipientId": "yDCVHUUckpwbqu2fUuyXGHSxNMdtKoFQ",
"SignId": "yDCVHUUckpwbqu2xUuyXGHS1pifZeuEM"
},
{
"ApproverRoleName": "",
"RecipientId": "yDCVHUUckpwbqu24UuyXGHSwSOzFjmPR",
"SignId": "yDCVHUUckpwbqu2bUuyXGHSyMBsyo35X"
}
],
"FlowId": "yDCVHUUckpwbqu2eUuyXGHSubvJWEDif"
},
{
"Approvers": [
{
"ApproverRoleName": "",
"RecipientId": "yDCVHUUckpwbqu2mUuyXGHSx4AVZuJkj",
"SignId": "yDCVHUUckpwbqu29UuyXGHSS9mARSyFZ"
},
{
"ApproverRoleName": "",
"RecipientId": "yDCVHUUckpwbqu27UuyXGHSR81vG2CR9",
"SignId": "yDCVHUUckpwbqu2uUuyXGHS8JfqC4sho"
}
],
"FlowId": "yDCVHUUckpwbqu2zUuyXGHSBho2CDwGz"
},
{
"Approvers": [
{
"ApproverRoleName": "",
"RecipientId": "yDCVHUUckpwbqu28UuyXGHS1CLfd5m1g",
"SignId": "yDCVHUUckpwbqu22UuyXGHS8gj9IYCTL"
},
{
"ApproverRoleName": "",
"RecipientId": "yDCVHUUckpwbqu2rUuyXGHSw7ZeJH7Dk",
"SignId": "yDCVHUUckpwbqu25UuyXGHSu11RucwZR"
}
],
"FlowId": "yDCVHUUckpwbqu2qUuyXGHSvEB4yY7su"
}
],
"FlowGroupId": "yDCVHUUckpwbquhgUuyXGHSxM3rGJCM3",
"FlowIds": [
"yDCVHUUckpwbqu2eUuyXGHSubvJWEDif",
"yDCVHUUckpwbqu2zUuyXGHSBho2CDwGz",
"yDCVHUUckpwbqu2qUuyXGHSvEB4yY7su"
],
"RequestId": "s1711351873868654231"
}
}
5. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| FailedOperation | 操作失败。 |
| FailedOperation.AgeNotAchieveNormalLegal | 签署人未达到合法年龄。 |
| InternalError | 内部错误。 |
| InternalError.Db | 数据库错误。 |
| InternalError.DbConnection | 数据库连接出错。 |
| InternalError.Decryption | 解密错误。 |
| InternalError.Encryption | 加密错误。 |
| InternalError.GenerateId | 生成唯一ID错误。 |
| InternalError.System | 系统错误。 |
| InternalError.ThirdParty | 第三方错误。 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.Application | 应用号不存在。 |
| InvalidParameter.ApproverType | 参数错误，不合法的签署人类型，请修改后重试。 |
| InvalidParameter.ApproverVerifyType | ApproverVerifyType参数值非法 |
| InvalidParameter.BizApproverAlreadyExists | 重复添加签署人。 |
| InvalidParameter.CardType | 证件类型错误。 |
| InvalidParameter.CustomShowMap | 参数错误，无效的自定义页卡模板，仅支持{合同名称}{发起方姓名}{发起方企业}{签署方N姓名}{签署方N企业}，请修改后重试。 |
| InvalidParameter.CustomerData | 参数错误，UserData长度非法，请修改后重试。 |
| InvalidParameter.DataNotFound | 数据不存在。 |
| InvalidParameter.FlowApproverInfos | 参数错误，不合法的备选签署人数量，请检查后重试。 |
| InvalidParameter.FlowApprovers | 参数错误，参与者数量不能为空且不能超过数量限制，请修改后重试。 |
| InvalidParameter.FlowCallbackUrl | 参数错误，不合法的签署流程回调链接，请修改后重试。 |
| InvalidParameter.FlowDeadLine | 参数错误，不合法的签署流程截止日期，请修改后重试。 |
| InvalidParameter.FlowDescription | 参数错误，不合法的签署流程描述，请修改后重试。 |
| InvalidParameter.FlowFileIds | 参数错误，目前仅支持单个文件发起，请修改后重试。 |
| InvalidParameter.FlowName | 参数错误，不合法的签署流程名称，请修改后重试。 |
| InvalidParameter.FlowType | 参数错误，不合法的FlowType，请修改后重试。 |
| InvalidParameter.Name | 姓名不符合要求。 |
| InvalidParameter.NonsupportMobile | 不支持的手机号。 |
| InvalidParameter.OrganizationName | 企业名称不合法。 |
| InvalidParameter.ParamError | 参数错误。 |
| InvalidParameter.SignComponentType | 参数错误，不合法的签署控件类型，请修改后重试。 |
| InvalidParameter.Unordered | 参数错误，不合法的签署顺序，请检查后重试。 |
| InvalidParameter.UnsupportedComponentType | 参数错误，不支持的控件类型，请检查后重试。 |
| InvalidParameterValue | 参数取值错误。 |
| LimitExceeded | 超过配额限制。 |
| MissingParameter | 缺少参数错误。 |
| MissingParameter.MissComponentName | 缺少控件名称参数，请检查后重试。 |
| OperationDenied | 操作被拒绝。 |
| OperationDenied.ByFilesServerSignForbid | 文件发起静默签未开通白名单。 |
| OperationDenied.ErrNoResourceAccess | 无资源访问权限。 |
| OperationDenied.InvalidApproverAge | 签署人未达到合法年龄。 |
| OperationDenied.NoApproverMobileCheckPermission | 企业暂未开通手机号验证身份的服务，请在企业中心开通再使用 |
| OperationDenied.NoIdentityVerify | 未通过个人实名。 |
| OperationDenied.NoQuota | 流程配额不足。 |
| OperationDenied.OverseaAbilityNotOpen | 当前企业员工没有开通境外签署能力。 |
| ResourceNotFound | 资源不存在。 |
| ResourceNotFound.Application | 应用号不存在。 |
| ResourceNotFound.Resource | 资源不存在。 |
| ResourceNotFound.Seal | 印章不存在，请检查后重试。 |
| UnauthorizedOperation.NoPermissionFeature | 请升级到对应版本后即可使用该接口。 |