腾讯电子签模板发起合同-创建电子文档

1. 接口描述

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

创建签署流程电子文档

调用流程

该接口需要给对应的流程指定一个模板id，并且填充该模板中需要补充的信息。需要配置创建签署流程和发起签署流程接口使用。具体逻辑可以参考下图:

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

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

填充填写控件需要进行Pdf合成工作，文档合成完成后会收到合同文档合成完成回调,建议在收到此回调后再调用 StartFlow 接口。

填充的传参示例如下

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

合成后合同样子示例

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

推荐使用 API Explorer

点击调试

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

2. 输入参数

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

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：CreateDocument。
Version	是	String	公共参数，本接口取值：2020-11-11。
Region	否	String	公共参数，此参数为可选参数。
Operator	是	UserInfo	本合同的发起人，点击查看合同发起人展示的位置注：支持填入集团子公司经办人 userId代发合同。
TemplateId	是	String	用户配置的合同模板ID，会基于此模板创建合同文档，为32位字符串。点击查看模板Id在控制台上的位置示例值：yDCj7UUckp4b4ga6UCJQtCwIZllHtJ6B
FlowId	否	String	合同流程ID，为32位字符串。此接口的合同流程ID需要由创建签署流程接口创建得到。示例值：yDCVNUUckpw3nnnyUVScgTvSA1IaZgM7
FileNames.N	否	Array of String	文件名列表，单个文件名最大长度200个字符，暂时仅支持单文件发起。设置后流程对应的文件名称当前设置的值。示例值：["入职合同"]
FormFields.N	否	Array of FormField	电子文档的填写控件的填充内容。具体方式可以参考FormField结构体的定义。支持自动签传递印章，可通过指定自动签控件id，指定印章id来完成附件控件支持传入图片、文件资源id，并将内容合成到合同文件中。支持的文件类型有doc、docx、xls、xlsx、html、jpg、jpeg、png、bmp、txt、pdf。需要注意如果传入的资源类型都是图片类型，图片资源会放置在合同文件的末尾，如果传入的资源有非图片类型资源，会将资源放置在附件控件所在页面的下一页。注：只有在控制台编辑模板时，归属给发起方的填写控件（如下图）才能在创建文档的时候进行内容填充。
NeedPreview	否	Boolean	是否为预览模式，取值如下： false：非预览模式（默认），会产生合同流程并返回合同流程编号FlowId。 true：预览模式，不产生合同流程，不返回合同流程编号FlowId，而是返回预览链接PreviewUrl，有效期为300秒，用于查看真实发起后合同的样子。注意：以预览模式创建的合同仅供查看，因此参与方无法进行签署操作注: `当使用的模板中存在动态表格控件时，预览结果中没有动态表格的填写内容，动态表格合成完后会触发文档合成完成的回调通知` 示例值：false
PreviewType	否	Integer	预览模式下产生的预览链接类型 0 :(默认) 文件流 ,点开后下载预览的合同PDF文件 1 :H5链接 ,点开后在浏览器中展示合同的样子。注: `1.此参数在NeedPreview 为true时有效` `2.动态表格控件不支持H5链接方式预览` 示例值：0
Agent	否	Agent	代理企业和员工的信息。在集团企业代理子企业操作的场景中，需设置此参数。在此情境下，ProxyOrganizationId（子企业的组织ID）为必填项。
ClientToken	否	String	已废弃字段，客户端Token，保持接口幂等性,最大长度64个字符示例值：yDSLMUUckpotxh18UEnJP33SwMj5LRdW

3. 输出参数

参数名称	类型	描述
DocumentId	String	合同流程的底层电子文档ID，为32位字符串。注: 后续需用同样的FlowId再次调用发起签署流程，合同才能进入签署环节示例值：yDt1JUUckp77a2omUyEmko88eg49PTsN
PreviewFileUrl	String	合同预览链接URL。注: `1.如果是预览模式(即NeedPreview设置为true)时, 才会有此预览链接URL` `2.当使用的模板中存在动态表格控件时，预览结果中没有动态表格的填写内容,完整的预览链接需通过合同文档合成完成回调获取。示例值：https://qian.tencent.cn/4d0d6929-0b40
Approvers	Array of ApproverItem	签署方信息，如角色ID、角色名称等
RequestId	String	唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 创建电子文档并填充内容控件

1.设置流程合同ID为yDwFmUUckpst10i3UubBSat8PWOt2iQF
2.设置文档模板ID为yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR
3.设置模板内的图片填写控件值

输入示例

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

{
    "Operator": {
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FileNames": [
        "合同文件.pdf"
    ],
    "FlowId": "yDwFmUUckpst10i3UubBSat8PWOt2iQF",
    "TemplateId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
    "ClientToken": "",
    "NeedPreview": false,
    "FormFields": [
        {
            "ComponentValue": "张三的单行文本1",
            "ComponentId": "单行文本填写1"
        },
        {
            "ComponentValue": "张三的单行文本1",
            "ComponentId": "单行文本填写2"
        },
        {
            "ComponentValue": "张三的填写内容",
            "ComponentId": "多行填写1"
        },
        {
            "ComponentValue": "true",
            "ComponentId": "checkBox控件"
        }
    ]
}

输出示例

{
    "Response": {
        "Approvers": [
            {
                "ApproverRoleName": "****有限公司",
                "RecipientId": "yDRvoUUgygqoh024UuO4zjE8OBoGfRNr",
                "SignId": "yDw7hUUckpkmkwraUunP4DaSHZaRRhKP"
            },
            {
                "ApproverRoleName": "个人签署方1",
                "RecipientId": "yDRvoUUgygqoh02bUuO4zjE8VMs79RJy",
                "SignId": "yDw7hUUckpkmkwryUunP4Dau01y5xJRN"
            }
        ],
        "RequestId": "18b53278-xxxx-xxxx-xxxx-06aa59796573",
        "DocumentId": "yDxZ1UyKQDSIMfUuO4zjEw2TyqzKEs16",
        "PreviewFileUrl": ""
    }
}

示例2 创建电子文档并填充图片控件

1.设置流程合同ID为yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm
2.设置文档模板ID为yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc
3.设置模板内的图片填写控件值为yDxZ1UyKQDSIMXUuO4zjERbwQIfGw4TK
注：
若发起合同时不确定具体的签署人，即发起了含有动态签署人的合同，需保留对应的签署角色编号（即RecipientId），后续进行补充时需指定对应的RecipientId

输入示例

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

{
    "Operator": {
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FileNames": [
        "合同文件.pdf"
    ],
    "FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
    "TemplateId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
    "ClientToken": "",
    "NeedPreview": false,
    "FormFields": [
        {
            "ComponentValue": "yDxZ1UyKQDSIMXUuO4zjERbwQIfGw4TK",
            "ComponentId": "component_image"
        }
    ]
}

输出示例

{
    "Response": {
        "Approvers": [
            {
                "ApproverRoleName": "****有限公司",
                "RecipientId": "yDRvoUUgygqoh024UuO4zjE8OBoGfRNr",
                "SignId": "yDw7hUUckpkmkwraUunP4DaSHZaRRhKP"
            },
            {
                "ApproverRoleName": "个人签署方1",
                "RecipientId": "yDRvoUUgygqoh02bUuO4zjE8VMs79RJy",
                "SignId": "yDw7hUUckpkmkwryUunP4Dau01y5xJRN"
            }
        ],
        "RequestId": "956d7f8d-xxxx-xxxx-xxxx-4e48d923ecf0",
        "DocumentId": "yDxZ1UyKQDSIMaUuO5zjEypPWudeHbnG",
        "PreviewFileUrl": ""
    }
}

5. 开发者资源

腾讯云 API 平台

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

API Inspector

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

SDK

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

Tencent Cloud SDK 3.0 for Python: GitHub Gitee
Tencent Cloud SDK 3.0 for Java: GitHub Gitee
Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
Tencent Cloud SDK 3.0 for Go: GitHub Gitee
Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
Tencent Cloud SDK 3.0 for C++: GitHub Gitee
Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee

命令行工具

Tencent Cloud CLI 3.0

6. 错误码

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

错误码	描述
FailedOperation	操作失败。
FailedOperation.FlowHasDocument	签署流程已有关联文档，请检查参数修改后重试。
FailedOperation.FlowHasNoDocument	流程未找到关联的电子文件信息，请检查操作步骤，检查参数，并在修改后重试。
FailedOperation.PreViewUrlFail	创建签署流程预览链接失败，请稍后重试。
FailedOperation.TemplateHasNoResource	模板无资源信息。
InternalError	内部错误。
InternalError.Api	第三方接口失败。
InternalError.Db	数据库异常。
InternalError.DbConnection	数据库连接出错。
InternalError.DbInsert	数据库新增记录出错。
InternalError.JsonMarshal	Json序列化失败。
InternalError.System	系统错误，请稍后重试。
InvalidParameter	参数错误。
InvalidParameter.ApproverType	不合法的签署人类型，请检查后重试。
InvalidParameter.CardNumber	不合法的证件信息，请检查证件号证件类型是否正确。
InvalidParameter.CardType	不合法的证件信息，请检查证件号证件类型是否正确。
InvalidParameter.ClientToken	ClientToken不合法请检查。
InvalidParameter.ComponentPage	不合法的控件页码，请与文件资源检查，并在修改后重试。
InvalidParameter.ComponentTypeNoMatchValue	控件的类型与输入值不匹配，请检查参数修改后重试。
InvalidParameter.DataNotFound	数据不存在。
InvalidParameter.EmptyParams	参数为空，请检查参数修改后重试。
InvalidParameter.InvalidId	id类型参数不合法，请检查后重试。
InvalidParameter.ParamError	参数错误。
InvalidParameter.SealId	不合法的印章id，请检查印章id是否正确，并在修改后重试。
InvalidParameterValue	参数取值错误。
InvalidParameterValue.Mask	需要屏蔽的告警。
MissingParameter.ApproverSignComponent	缺少签署人签署控件配置，请联系客服了解控件传递规则，并在修改后重试。
MissingParameter.FileNames	文件名为空，请检查参数修改后重试。
MissingParameter.Recipient	缺少模板签署人信息，请检查后重试。
MissingParameter.ServerSignSealId	缺少静默签印章id，请检查修改后重试。
MissingParameter.SignComponents	缺少签署控件参数。
OperationDenied	操作被拒绝。
OperationDenied.ApproverNoMatchTemplate	签署人设置与模板中签署人配置信息不一致，请检查模板修改参数后重试。
OperationDenied.FileNoMatchResource	文件与资源不匹配，请检查文件名与资源id数量以及对应关系，并在修改后重试。
OperationDenied.Forbid	禁止此项操作。
OperationDenied.NoIdentityVerify	未通过个人实名认证。
OperationDenied.NoLogin	用户未登录,请先登录后再操作。
OperationDenied.ServerSignNoAllowComponent	静默签署方不允许有填写控件，请修改模板，修改参数后重试。
ResourceNotFound	资源不存在。
ResourceNotFound.Document	未找到电子文档信息，请检查后重试。
ResourceNotFound.Template	模板不存在，请检查模板参数，模板配置，并稍后重试。
ResourceNotFound.User	用户或者员工信息不存在，请检查参数后重试。
ResourceUnavailable	资源不可用。
UnauthorizedOperation	未授权操作。
UnauthorizedOperation.NoPermissionFeature	请升级到对应版本后即可使用该接口。

近期搜索热词

云服务器

云硬盘

容器服务

弹性伸缩

负载均衡

私有网络

云函数

API 网关

专线接入

批量计算

微服务平台 TSF

对象存储

文件存储

全站加速网络

消息队列 CKafka 版

日志服务

云数据库 MySQL

云数据库 MariaDB

云数据库 SQL Server

云数据库 PostgreSQL

内容分发网络 CDN

云数据库 Redis®

云数据库 Memcached

云数据库 MongoDB

TDSQL MySQL版

全球应用加速

数据传输服务

腾讯云可观测平台

腾讯云区块链服务平台 TBaaS

云拨测

访问管理

主机安全

DDoS 防护

标签

密钥管理系统

Web 应用防火墙

域名注册

操作审计

SSL 证书

短信

数据万象

NLP 技术

云点播

云市场

云加密机

云安全中心

云开发 CloudBase

集团账号管理

Elasticsearch Service

腾讯云数据仓库 TCHouse-P

图像识别

口语评测（基础版）

文字识别

人脸识别

流计算 Oceanus

媒体处理

云直播

云联络中心

机器翻译

物联网通信

人脸融合

游戏数据库 TcaplusDB

弹性 MapReduce

腾讯云 BI

游戏多媒体引擎

实时音视频

渠道合作伙伴

TI-ONE 训练平台

数据安全审计

数据安全治理中心

智能视图计算平台

计费相关

消息队列 RocketMQ 版

微瓴同业开放平台

数学作业批改

商场客留大数据

声音复刻

文旅客情大数据

实时互动-工业能源版