腾讯电子签集成版
有奖捉虫：行业应用 & 管理与支持文档专题 HOT
文档中心 > 腾讯电子签集成版 > API 文档 > 流程发起相关接口 > 用模板创建签署流程

用模板创建签署流程

最近更新时间：2024-05-15 01:20:44

我的收藏

本页目录：

1. 接口描述

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

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

一. 整体的逻辑如下

image

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

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

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

模板中配置的发起人填充控件可以通过本接口的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. 输入参数

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

参数名称 必选 类型 描述
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": "测试签署流程二的描述信息",
            "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": ""
            }
        ]
    }
}

示例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,
            "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. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。

错误码 描述
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 请升级到对应版本后即可使用该接口。
中国站


http://www.vxiaotou.com