跳到主要内容

用模板创建签署流程

1. 接口描述

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

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

一. 整体的逻辑如下

image

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

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

三. 填充模板中定义的填写控件

模板中配置的发起人填充控件可以通过本接口的FormFields数组字段填充

image 填充的传参示例如下

    request.FormFields = [{
"ComponentName": "项目的名字",
"ComponentValue": "休闲山庄"
}, {
"ComponentName": "项目的地址",
"ComponentValue": "凤凰山北侧",
}, {
"ComponentName": "范围",
"ComponentValue": "凤凰山至107国道",
}, {
"ComponentName": "面积",
"ComponentValue": "100亩",
}, {
"ComponentName": "基本情况",
"ComponentValue": "完好",
}, , {
"ComponentName": "用途",
"ComponentValue": "经营农家乐",
}
]

合成后合同样子示例

image

四. 注意

  1. 发起合同时候, 作为发起方的第三方子企业A员工的企业和员工必须经过实名, 而作为签署方的第三方子企业A员工/个人/自然人/SaaS平台企业员工/第三方子企业B员工企业中的企业和个人/员工可以未实名

  2. 不同类型的签署方传参不同, 可以参考开发者中心的FlowApproverInfo结构体说明

  3. 调用接口发起合同成功就会扣减合同的额度, 如果未签署完成时撤销合同会返还此额度(过期,拒签,签署完成,解除完成等状态不会返还额度)
  4. 静默(自动)签署不支持合同签署方存在填写
  5. 在下一步创建签署链接前,建议等待DocumentFill PDF合成完成的回调或者睡眠几秒,尤其是当模板中存在动态表格等复杂填写控件时,因为合成过程可能会耗费秒级别的时间。

默认接口请求频率限制: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数组,以便于顺利进行后续操作。

点击产看FlowId在控制台上的位置
示例值:["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 创建含有动态签署人流程,签署方不指定具体的签署人

创建一个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"
}
}

示例2 使用模板批量创建两个签署流程

使用模板批量创建两个签署流程 第一个签署流程是 一个 单 C 合同,有发起方控件姓名,在发起的时候进行了填充, 即在 formfields 中填入了 components 对象 第二个签署流程是 一个 C2B 合同, 第一方 ApproverType 设置为 PERSON,第二方的 ApproverType设置为 ORGANIZATION, 有发起方控件姓名,在发起的时候进行了填充, 即在 formfields 中填入了 components 对象

输入示例

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

{
"Agent": {
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "n9527"
},
"AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
},
"FlowInfos": [
{
"FlowName": "测试签署流程一",
"TemplateId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"FlowDescription": "测试签署流程一的描述信息",
"Deadline": 1989688460,
"FormFields": [
{
"ComponentName": "姓名",
"ComponentValue": "李四"
}
],
"FlowApprovers": [
{
"ApproverType": "PERSON",
"Name": "李四",
"Mobile": "13888888888",
"RecipientId": "yDwJ2UUckpk1rwrdUrWKfEcuxn5DMpeI"
}
]
},
{
"FlowName": "测试签署流程二",
"TemplateId": "yDRS4UUgygqdcj56UuO4zjExBQcOiB68",
"FlowDescription": "测试签署流程二的描述信息",
"CallbackUrl": "",
"FormFields": [
{
"ComponentName": "姓名",
"ComponentValue": "张三"
}
],
"Deadline": 1989688460,
"FlowApprovers": [
{
"Name": "典子谦",
"ApproverType": "PERSON",
"Mobile": "13200000000",
"RecipientId": "yDxZzUyKQDKuihUuO4zjEy09jfapyHjn"
},
{
"Name": "张三",
"ApproverType": "ORGANIZATION",
"OrganizationOpenId": "ess_open_organization_1",
"OrganizationName": "org_zhangsan",
"Mobile": "18888888888",
"OpenId": "n02468",
"RecipientId": "yDwJ0UUckpk2077lUxgm9jJ9eZgZChJe"
}
]
}
]
}

输出示例

{
"Response": {
"CustomerData": [
""
],
"ErrorMessages": [
""
],
"FlowApprovers": [
{
"Approvers": [
{
"ApproverRoleName": "个人签署方",
"RecipientId": "yDwJ2UUckpk1rwrdUrWKfEcuxn5DMpeI",
"SignId": "yDCNsUUckpvsadteUEEw4Igush89GzOR"
}
],
"FlowId": "yDCNsUUckpvsadtiUEEw4Ig1G1yak1QY"
},
{
"Approvers": [
{
"ApproverRoleName": "个人签署方",
"RecipientId": "yDxZzUyKQDKuihUuO4zjEy09jfapyHjn",
"SignId": "yDCNsUUckpvsadteUEEw4Igush87GzOR"
},
{
"ApproverRoleName": "张三示例企业",
"RecipientId": "yDwJ0UUckpk2077lUxgm9jJ9eZgZChJe",
"SignId": "yDCNsUUckpvsadtzUEEw4IgycXgrG82a"
}
],
"FlowId": "yDCNsUUckpvsadtiUEEw4Ig1G1ybk1QY"
}
],
"FlowIds": [
"yDCNsUUckpvsadtiUEEw4Ig1G1yak1QY",
"yDCNsUUckpvsadtiUEEw4Ig1G1ybk1QY"
],
"PreviewUrls": [
"",
""
],
"RequestId": "s1706111849162794392",
"TaskInfos": [
{
"TaskId": "",
"TaskStatus": ""
},
{
"TaskId": "",
"TaskStatus": ""
}
]
}
}

示例3 发起一份 BBC 流程

发起一份 BBC 签署流程 其中第一方 B 为子客,即 ApproverType = ORGANIZATION,需要传递子客的 OrganizationOpenId, OrganizationName,经办人的 OpenId,Name 和 Mobile 第二方 B 为渠道外企业,即 SaaS 企业, 即 ApproverType=ORGANIZATION且NotChannelOrganization=True,需要传递企业的 OrganizationName,经办人的 Name 和 Mobile 第三方为个人,即ApproverType = PERSON, 只需要传递 Name 和 Mobile 即可

输入示例

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

{
"Agent": {
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "n9527"
},
"AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
},
"FlowInfos": [
{
"FlowName": "三方签署合同",
"FlowApprovers": [
{
"ApproverType": "ORGANIZATION",
"OrganizationOpenId": "org_dianziqian",
"OrganizationName": "典子谦示例企业",
"OpenId": "n9527",
"Name": "典子谦",
"Mobile": "13200000000",
"Deadline": 1989688460,
"RecipientId": "yDRSOUUgygqno04sUuO4zjEugoGg49nT"
},
{
"ApproverType": "ORGANIZATION",
"NotChannelOrganization": true,
"OrganizationName": "张三示例企业",
"Name": "张三",
"Mobile": "18888888888",
"Deadline": 1989688460,
"RecipientId": "yDRSOUUgygqno04jUuO4zjE8SXYVwrjH"
},
{
"ApproverType": "PERSON",
"Name": "李四",
"Mobile": "15100000000",
"Deadline": 1989688460,
"RecipientId": "yDRSOUUgygqno043UuO4zjE8NnYYihhQ"
}
],
"Deadline": 2089688460,
"TemplateId": "yDRSOUUgygqnordgUuO4zjE8NqahJdam"
}
]
}

输出示例

{
"Response": {
"CustomerData": [],
"ErrorMessages": [
""
],
"FlowApprovers": [
{
"Approvers": [
{
"ApproverRoleName": "典子谦示例企业",
"RecipientId": "yDRSOUUgygqno04sUuO4zjEugoGg49nT",
"SignId": "yDCNsUUckpvs1o70UuxBSommqdahMmPb"
},
{
"ApproverRoleName": "企业签署方1",
"RecipientId": "yDRSOUUgygqno04jUuO4zjE8SXYVwrjH",
"SignId": "yDCNsUUckpvs1o7pUuxBSomCdAKFk0MP"
},
{
"ApproverRoleName": "个人签署方1",
"RecipientId": "yDRSOUUgygqno043UuO4zjE8NnYYihhQ",
"SignId": "yDCNsUUckpvs1o7nUuxBSomy9T24RbPy"
}
],
"FlowId": "yDCNsUUckpvs1o75UuxBSomCyxVzORYK"
}
],
"FlowIds": [
"yDCNsUUckpvs1o75UuxBSomCyxVzORYK"
],
"PreviewUrls": [
""
],
"RequestId": "s1706113495983439953",
"TaskInfos": [
{
"TaskId": "",
"TaskStatus": ""
}
]
}
}

示例4 带填写控件的B2B模板发起示例

发起一份B2B 合同(流程),双方企业均已认证,并且设置了一个发起方填写控件,控件 Name 是姓名。

输入示例

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

{
"Agent": {
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "n9527"
},
"AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
},
"FlowInfos": [
{
"FlowName": "测试流程一",
"TemplateId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"FlowDescription": "测试流程一的描述信息",
"Deadline": 1604910797,
"FormFields": [
{
"ComponentName": "姓名",
"ComponentValue": "李四"
}
],
"FlowApprovers": [
{
"ApproverType": "ORGANIZATION",
"OrganizationOpenId": "org_zhangsan",
"OrganizationName": "典子谦示例企业",
"OpenId": "n02468",
"RecipientId": "yDwJ2UUckpk1rwrdUrWKfEcuxn5DMpeI"
},
{
"ApproverType": "ORGANIZATION",
"OpenId": "n02468",
"OrganizationOpenId": "org_zhangsan",
"OrganizationName": "张三示例企业",
"RecipientId": "yDxZzUyKQDKuihUuO4zjEy09jfapyHjn"
}
]
}
]
}

输出示例

{
"Response": {
"CustomerData": [
""
],
"ErrorMessages": [
""
],
"FlowApprovers": [
{
"Approvers": [
{
"ApproverRoleName": "典子谦示例企业",
"RecipientId": "yDwJ2UUckpk1rwrdUrWKfEcuxn5DMpeI",
"SignId": "yDCNsUUckpvsadteUEEw4Igush87GzOR"
},
{
"ApproverRoleName": "张三示例企业",
"RecipientId": "yDxZzUyKQDKuihUuO4zjEy09jfapyHjn",
"SignId": "yDCNsUUckpvsadtzUEEw4IgycXgrG82a"
}
],
"FlowId": "yDCNsUUckpvsadtiUEEw4Ig1G1ybk1QY"
}
],
"FlowIds": [
"yDCNsUUckpvsadtiUEEw4Ig1G1ybk1QY"
],
"PreviewUrls": [
""
],
"RequestId": "s1706111849162794392",
"TaskInfos": [
{
"TaskId": "",
"TaskStatus": ""
}
]
}
}

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请升级到对应版本后即可使用该接口。
购买咨询
4006-808-062
4006-808-062