用模板创建签署流程

1. 接口描述

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

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

一. 整体的逻辑如下

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

场景编号	发起方	签署方	补充
场景一	子企业A的员工	子企业A的员工	子企业是通过CreateConsoleLoginUrl生成子客登录链接注册的企业
场景二	子企业A的员工	子企业B(不指定经办人走领取逻辑)	领取的逻辑可以参考文档动态签署方
场景三	子企业A的员工	子企业B的员工	-
场景四	子企业A的员工	个人	就是自然人，不是企业员工
场景五	子企业A的员工	SaaS平台企业员工	SaaS平台企业是通过https://qian.tencent.cn/console/company-register链接注册的企业

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

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

填充的传参示例如下

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

合成后合同样子示例

四. 注意

发起合同时候, 作为发起方的第三方子企业A员工的企业和员工必须经过实名, 而作为签署方的第三方子企业A员工/个人/自然人/SaaS平台企业员工/第三方子企业B员工企业中的企业和个人/员工可以未实名
不同类型的签署方传参不同, 可以参考开发者中心的FlowApproverInfo结构体说明
调用接口发起合同成功就会扣减合同的额度, 只有撤销没有参与方签署过或只有自动签署签署过的合同，才会返还合同额度。（过期，拒签，签署完成，解除完成等状态不会返还额度）
静默（自动）签署不支持合同签署方存在填写
在下一步创建签署链接前，建议等待DocumentFill PDF合成完成的回调或者睡眠几秒，尤其是当模板中存在动态表格等复杂填写控件时，因为合成过程可能会耗费秒级别的时间。

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

推荐使用 API Explorer

点击调试

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

2. 输入参数

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

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateFlowsByTemplates。
Version	是	String	公共参数，本接口取值：2021-05-26。
Region	否	String	公共参数，此参数为可选参数。
Agent	是	Agent	关于渠道应用的相关信息，包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容，您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。此接口下面信息必填。渠道应用标识: Agent.AppId 第三方平台子客企业标识: Agent.ProxyOrganizationOpenId 第三方平台子客企业中的员工标识: Agent.ProxyOperator.OpenId
FlowInfos.N	是	Array of FlowInfo	要创建的合同信息列表，最多支持一次创建20个合同
NeedPreview	否	Boolean	是否为预览模式，取值如下： false：非预览模式（默认），会产生合同流程并返回合同流程编号FlowId。 true：预览模式，不产生合同流程，不返回合同流程编号FlowId，而是返回预览链接PreviewUrl，有效期为300秒，用于查看真实发起后合同的样子。注意：以预览模式创建的合同仅供查看，因此参与方无法进行签署操作注: `如果预览的文件中指定了动态表格控件，此时此接口返回的是合成前的文档预览链接，合成完成后的文档预览链接需要通过回调通知的方式或使用返回的TaskInfo中的TaskId通过ChannelGetTaskResultApi接口查询得到` 示例值：false
PreviewType	否	Integer	预览模式下产生的预览链接类型 0 :(默认) 文件流 ,点开后下载预览的合同PDF文件 1 :H5链接 ,点开后在浏览器中展示合同的样子注: `此参数在NeedPreview 为true时有效` 示例值：0

3. 输出参数

参数名称	类型	描述
FlowIds	Array of String	生成的合同流程ID数组，合同流程ID为32位字符串。建议开发者妥善保存此流程ID数组，以便于顺利进行后续操作。点击产看FlowId在控制台上的位置示例值：["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）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 发起一份 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": ""
            }
        ]
    }
}

示例2 带填写控件的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": ""
            }
        ]
    }
}

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

使用模板批量创建两个签署流程第一个签署流程是一个单 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": "测试签署流程二的描述信息",
            "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": ""
            }
        ]
    }
}

示例4 创建含有动态签署人流程，签署方不指定具体的签署人

创建一个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,
            "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	请升级到对应版本后即可使用该接口。

1. 接口描述​

一. 整体的逻辑如下​

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

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

四. 注意​

2. 输入参数​

3. 输出参数​

4. 示例​

示例1 发起一份 BBC 流程​

输入示例​

输出示例​

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

输入示例​

输出示例​

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

输入示例​

输出示例​

示例4 创建含有动态签署人流程，签署方不指定具体的签署人​

输入示例​

输出示例​

5. 错误码​

1. 接口描述

一. 整体的逻辑如下

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

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

四. 注意

2. 输入参数

3. 输出参数

4. 示例

示例1 发起一份 BBC 流程

输入示例

输出示例

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

输入示例

输出示例

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

输入示例

输出示例

示例4 创建含有动态签署人流程，签署方不指定具体的签署人

输入示例

输出示例

5. 错误码