用模板创建签署流程
1. 接口描述
接口请求域名： essbasic.tencentcloudapi.com 。
接口（CreateFlowsByTemplates）用于使用模板批量创建签署流程。当前可批量发起合同（签署流程）数量为1-20个。 如若在模板中配置了动态表格, 上传的附件必须为A4大小 合同发起人必须在电子签已经进行实名。
整体的逻辑如下
可以作为发起方和签署方的角色列表
| 场景编号 | 可作为发起方类型 | 可作为签署方的类型 |
|---|---|---|
| 场景一 | 第三方子企业A员工 | 第三方子企业A员工 |
| 场景二 | 第三方子企业A员工 | 第三方子企业B(不指定经办人) |
| 场景三 | 第三方子企业A员工 | 第三方子企业B员工 |
| 场景四 | 第三方子企业A员工 | 个人/自然人 |
| 场景五 | 第三方子企业A员工 | SaaS平台企业员工 |
注:
1. 发起合同时候, 作为发起方的第三方子企业A员工的企业和员工必须经过实名, 而作为签署方的第三方子企业A员工/个人/自然人/SaaS平台企业员工/第三方子企业B员工企业中的企业和个人/员工可以未实名
2. 不同类型的签署方传参不同, 可以参考开发者中心的FlowApproverInfo结构体说明
默认接口请求频率限制：20次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：CreateFlowsByTemplates。 |
| Version | 是 | String | 公共参数，本接口取值：2021-05-26。 |
| Region | 否 | String | 公共参数，此参数为可选参数。 |
| Agent | 是 | Agent | 关于渠道应用的相关信息，包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容，您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。 此接口下面信息必填。
|
| FlowInfos.N | 是 | Array of FlowInfo | 要创建的合同信息列表，最多支持一次创建20个合同 |
| NeedPreview | 否 | Boolean | 是否为预览模式，取值如下：
注: 如果预览的文件中指定了动态表格控件，此时此接口返回的是合成前的文档预览链接，合成完成后的文档预览链接需要通过回调通知的方式或使用返回的TaskInfo中的TaskId通过ChannelGetTaskResultApi接口查询得到示例值：false |
| PreviewType | 否 | Integer | 预览模式下产生的预览链接类型
注: 此参数在NeedPreview 为true时有效示例值：0 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| FlowIds | Array of String | 生成的合同流程ID数组，合同流程ID为32位字符串。 建议开发者妥善保存此流程ID数组，以便于顺利进行后续操作。 示例值：["yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm","yDwFmUUckpst10i3UubBSat8PWOt2iQF"] |
| CustomerData | Array of String | 第三方应用平台的业务信息, 与创建合同的FlowInfos数组中的CustomerData一一对应 示例值：eyJpZCI6ImNvbWVmIiwibmFtZSI6IuWRseWRseWPqyJ9 |
| ErrorMessages | Array of String | 创建消息，对应多个合同ID， 成功为“”,创建失败则对应失败消息 示例值：["缺少用户信息","缺少手机信息"] |
| PreviewUrls | Array of String | 合同预览链接URL数组。 注：如果是预览模式(即NeedPreview设置为true)时, 才会有此预览链接URL 示例值：["https://test.ess.tencent.cn/document-url-preview?channel=PROXYCHANNEL&scene=SINGLEPAGE&code=yDwqoUUcKny&codeType=QUICK&businessType=RESOURCE&businessId=yDwqcUUck"] |
| TaskInfos | Array of TaskInfo | 复杂文档合成任务（如，包含动态表格的预览任务）的任务信息数组； 如果文档需要异步合成，此字段会返回该异步任务的任务信息，后续可以通过ChannelGetTaskResultApi接口查询任务详情； |
| FlowApprovers | Array of FlowApproverItem | 签署方信息，如角色ID、角色名称等 |
| RequestId | String | 唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 B2B 模板发起示例
双方企业均已认证 发起示例
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowsByTemplates
<公共请求参数>
{
"Agent": {
"ProxyOrganizationOpenId": "d7c13a8b***********68c0ee248f04",
"ProxyOperator": {
"OpenId": "00498cc***********3aff766cac"
},
"AppId": "65fb0c59***********a382cc5ed0e"
},
"FlowInfos": [
{
"FlowName": "测试流程一",
"TemplateId": "005c***********4f7f64e8c",
"FlowDescription": "测试流程一的描述信息",
"FlowType": "合同",
"Deadline": 1604910797,
"CallbackUrl": "",
"FormFields": [
{
"ComponentName": "姓名",
"ComponentValue": "李四"
}
],
"FlowApprovers": [
{
"ApproverType": "ORGANIZATION",
"OpenId": "00498cc8***********aff766cac",
"RecipientId": "yDxjbUU***********zjEuCkSaxt8n"
},
{
"ApproverType": "ORGANIZATION",
"OpenId": "eezi_openid",
"OrganizationOpenId": "organization1_open_id",
"OrganizationName": "鹅鹅子的企业",
"RecipientId": "yDxjbUU***********ChJBkK7qS"
}
]
}
]
}
输出示例
{
"Response": {
"CustomerData": [
""
],
"FlowIds": [
"yDxMqU***********vaigGvi"
],
"PreviewUrls": [
""
],
"ErrorMessages": [
""
],
"TaskInfos": [
{
"TaskId": "taskid",
"TaskStatus": "status"
}
],
"RequestId": "s16294xxxxx0001803"
}
}
示例2 使用模板批量创建签署流程
使用模板批量创建签署流程
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowsByTemplates
<公共请求参数>
{
"Agent": {
"ProxyOrganizationOpenId": "d7c13a8***********0ee248f04",
"ProxyOperator": {
"OpenId": "00498cc***********3aff766cac"
},
"AppId": "65f***********aa382cc5ed0e"
},
"FlowInfos": [
{
"FlowName": "测试签署流程一",
"TemplateId": "005c7f***********4f7f64e8c",
"FlowDescription": "测试签署流程一的描述信息",
"FlowType": "合同",
"Deadline": 1604910797,
"CallbackUrl": "",
"FormFields": [
{
"ComponentName": "姓名",
"ComponentValue": "李四"
}
],
"FlowApprovers": [
{
"Name": "李四",
"Mobile": "13888888888",
"Deadline": 1604910798
}
]
},
{
"FlowName": "测试签署流程二",
"TemplateId": "005c7***********oqwnrf4e8c",
"FlowDescription": "测试签署流程二的描述信息",
"FlowType": "合同",
"Deadline": 1604910797,
"CallbackUrl": "",
"FormFields": [
{
"ComponentName": "姓名",
"ComponentValue": "张三"
}
],
"FlowApprovers": [
{
"Name": "鹅鹅子",
"ApproverType": "PERSON",
"Mobile": "13200000000",
"Deadline": 1663336465
},
{
"Name": "发起方",
"ApproverType": "ORGANIZATION",
"Mobile": "13700000000",
"OpenId": "12345678",
"Deadline": 1663336465
}
]
}
]
}
输出示例
{
"Response": {
"CustomerData": [
"",
""
],
"FlowIds": [
"yDxM***********trvvaigGvi",
"yDxMq***********1trvvaigGv2"
],
"PreviewUrls": [
"",
""
],
"ErrorMessages": [
"",
""
],
"TaskInfos": [
{
"TaskId": "taskid",
"TaskStatus": "status"
}
],
"RequestId": "s162944xxxxx3"
}
}
示例3 创建含有动态签署人流程，签署方不指定具体的签署人
创建一个B2C流程，两方签署方不指定具体的签署人
注：
1.签署人相关信息为空，如：姓名、手机号码等
2.FillType需传值为1，表示为动态签署人（不确定具体的签署人），需后续进行补充。
3.需保留对应的角色编号，即RecipientId，后续补充具体的签署人时需指定对应的RecipientId
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowsByTemplates
<公共请求参数>
{
"Agent": {
"ProxyOrganizationOpenId": "d7c13a8b***********68c0ee248f04",
"ProxyOperator": {
"OpenId": "00498cc***********3aff766cac"
},
"AppId": "65fb0c59***********a382cc5ed0e"
},
"FlowInfos": [
{
"FlowName": "测试流程一",
"TemplateId": "005c***********4f7f64e8c",
"FlowDescription": "测试流程一的描述信息",
"FlowType": "合同",
"Deadline": 1604910797,
"CallbackUrl": "",
"FormFields": [
{
"ComponentName": "姓名",
"ComponentValue": "李四"
}
],
"FlowApprovers": [
{
"ApproverType": "ORGANIZATION",
"ApproverRoleName": "企业签署方",
"RecipientId": "yDxjbUU***********zjEuCkSaxt8n",
"ApproverOption": {
"FillType": 1
}
},
{
"ApproverType": "PERSON",
"ApproverRoleName": "个人签署方",
"RecipientId": "yDxjbUU***********ChJBkK7qS",
"ApproverOption": {
"FillType": 1
}
}
]
}
]
}
输出示例
{
"Response": {
"CustomerData": [
""
],
"FlowIds": [
"yDxMqU***********vaigGvi"
],
"PreviewUrls": [
""
],
"ErrorMessages": [
""
],
"TaskInfos": [
{
"TaskId": "taskid",
"TaskStatus": "status"
}
],
"FlowApprovers": [
{
"Approvers": [
{
"ApproverRoleName": "企业签署方",
"RecipientId": "yDxjbUU***********zjEuCkSaxt8n",
"SignId": "yDw7hUUckpkmtvenURxlqRxRcrWD0zVk"
},
{
"ApproverRoleName": "个人签署方",
"RecipientId": "yDxjbUU***********ChJBkK7qS",
"SignId": "yDw7hUUckpkmtvegURxlqRxSV5qDMex1"
}
],
"FlowId": "yDxMqU***********vaigGvi"
}
],
"RequestId": "s16294xxxxx0001803"
}
}
5. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| FailedOperation | 操作失败。 |
| InternalError | 内部错误。 |
| InternalError.System | 系统错误。 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.Application | 应用号不存在。 |
| InvalidParameter.ApproverVerifyType | ApproverVerifyType参数值非法 |
| InvalidParameter.BizApproverAlreadyExists | 重复添加签署人。 |
| InvalidParameter.DataNotFound | 数据不存在。 |
| InvalidParameter.FlowInfos | 参数错误，FlowInfos非法，请修改后重试。 |
| InvalidParameter.MissingRequiredParameterValue | 缺少必填参数的值。 |
| InvalidParameter.Mobile | 手机号码不正确。 |
| InvalidParameter.ParamError | 参数错误。 |
| InvalidParameterValue | 参数取值错误。 |
| LimitExceeded | 超过配额限制。 |
| LimitExceeded.CreateFlowNum | 超出流程创建数量限制。 |
| MissingParameter | 缺少参数错误。 |
| OperationDenied | 操作被拒绝。 |
| OperationDenied.NoIdentityVerify | 未通过个人实名。 |
| OperationDenied.UserNotInOrganization | 用户不归属于当前企业，无法操作，请检查后重试。 |
| ResourceNotFound | 资源不存在。 |
| ResourceNotFound.Application | 应用号不存在。 |
| ResourceNotFound.Template | 模板不存在。 |
| ResourceNotFound.User | 用户信息不存在。 |
| ResourceUnavailable | 资源不可用。 |
| UnauthorizedOperation | 未授权操作。 |
| UnauthorizedOperation.NoPermissionFeature | 请升级到对应版本后即可使用该接口。 |