跳到主要内容

用模板创建签署流程

1. 接口描述

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

接口(CreateFlowsByTemplates)用于使用模板批量创建签署流程。当前可批量发起合同(签署流程)数量为1-20个。 如若在模板中配置了动态表格, 上传的附件必须为A4大小 合同发起人必须在电子签已经进行实名。

整体的逻辑如下

image

可以作为发起方和签署方的角色列表

场景编号可作为发起方类型可作为签署方的类型
场景一第三方子企业A员工第三方子企业A员工
场景二第三方子企业A员工第三方子企业B(不指定经办人)
场景三第三方子企业A员工第三方子企业B员工
场景四第三方子企业A员工个人/自然人
场景五第三方子企业A员工SaaS平台企业员工

: 1. 发起合同时候, 作为发起方的第三方子企业A员工的企业和员工必须经过实名, 而作为签署方的第三方子企业A员工/个人/自然人/SaaS平台企业员工/第三方子企业B员工企业中的企业和个人/员工可以未实名 2. 不同类型的签署方传参不同, 可以参考开发者中心的FlowApproverInfo结构体说明

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

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

2. 输入参数

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

参数名称必选类型描述
ActionString公共参数,本接口取值:CreateFlowsByTemplates。
VersionString公共参数,本接口取值:2021-05-26。
RegionString公共参数,此参数为可选参数。
AgentAgent关于渠道应用的相关信息,包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容,您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。

此接口下面信息必填。

  • 渠道应用标识: Agent.AppId
  • 第三方平台子客企业标识: Agent.ProxyOrganizationOpenId
  • 第三方平台子客企业中的员工标识: Agent.ProxyOperator.OpenId

FlowInfos.NArray of FlowInfo要创建的合同信息列表,最多支持一次创建20个合同
NeedPreviewBoolean是否为预览模式,取值如下:
  • false:非预览模式(默认),会产生合同流程并返回合同流程编号FlowId。
  • true:预览模式,不产生合同流程,不返回合同流程编号FlowId,而是返回预览链接PreviewUrl,有效期为300秒,用于查看真实发起后合同的样子。


注:

如果预览的文件中指定了动态表格控件,此时此接口返回的是合成前的文档预览链接,合成完成后的文档预览链接需要通过回调通知的方式或使用返回的TaskInfo中的TaskId通过ChannelGetTaskResultApi接口查询得到

示例值:false
PreviewTypeInteger预览模式下产生的预览链接类型
  • 0 :(默认) 文件流 ,点开后下载预览的合同PDF文件
  • 1 :H5链接 ,点开后在浏览器中展示合同的样子

注: 此参数在NeedPreview 为true时有效

示例值:0

3. 输出参数

参数名称类型描述
FlowIdsArray of String生成的合同流程ID数组,合同流程ID为32位字符串。
建议开发者妥善保存此流程ID数组,以便于顺利进行后续操作。
示例值:["yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm","yDwFmUUckpst10i3UubBSat8PWOt2iQF"]
CustomerDataArray of String第三方应用平台的业务信息, 与创建合同的FlowInfos数组中的CustomerData一一对应
示例值:eyJpZCI6ImNvbWVmIiwibmFtZSI6IuWRseWRseWPqyJ9
ErrorMessagesArray of String创建消息,对应多个合同ID,
成功为“”,创建失败则对应失败消息
示例值:["缺少用户信息","缺少手机信息"]
PreviewUrlsArray 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"]
TaskInfosArray of TaskInfo复杂文档合成任务(如,包含动态表格的预览任务)的任务信息数组;
如果文档需要异步合成,此字段会返回该异步任务的任务信息,后续可以通过ChannelGetTaskResultApi接口查询任务详情;
FlowApproversArray of FlowApproverItem签署方信息,如角色ID、角色名称等
RequestIdString唯一请求 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.ApproverVerifyTypeApproverVerifyType参数值非法
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请升级到对应版本后即可使用该接口。