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

1. 接口描述

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

创建签署流程电子文档

调用流程

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

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

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

填充的传参示例如下

    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 必填。支持填入集团子公司经办人 userId代发合同。
TemplateId	是	String	用户配置的合同模板ID，会基于此模板创建合同文档，为32位字符串。点击查看模板Id在控制台上的位置
FlowId	否	String	合同流程ID，为32位字符串。此接口的合同流程ID需要由创建签署流程接口创建得到。
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秒，用于查看真实发起后合同的样子。注意：以预览模式创建的合同仅供查看，因此参与方无法进行签署操作注: `当使用的模板中存在动态表格控件时，预览结果中没有动态表格的填写内容，动态表格合成完后会触发文档合成完成的回调通知`
PreviewType	否	Integer	预览模式下产生的预览链接类型 0 :(默认) 文件流 ,点开后下载预览的合同PDF文件 1 :H5链接 ,点开后在浏览器中展示合同的样子。注: `1.此参数在NeedPreview 为true时有效` `2.动态表格控件不支持H5链接方式预览`
Agent	否	Agent	代理企业和员工的信息。在集团企业代理子企业操作的场景中，需设置此参数。在此情境下，ProxyOrganizationId（子企业的组织ID）为必填项。
ClientToken	否	String	已废弃字段，客户端Token，保持接口幂等性,最大长度64个字符

3. 输出参数

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

4. 示例

示例1 创建电子文档-缺少填写控件

1.通过模板创建电子文档 2.未对模板内的必填控件【单行文本2】控件进行赋值

输入示例

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

{
    "Operator": {
        "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
    },
    "FileNames": [
        "合同文件.pdf"
    ],
    "FlowId": "yDwFdUUckpsvet4jUEn0aFRxtu5TdalM",
    "TemplateId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
    "ClientToken": "",
    "NeedPreview": false,
    "FormFields": [
        {
            "ComponentValue": "123456",
            "ComponentId": "单行文本"
        }
    ]
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "InvalidParameter.ParamError",
            "Message": "控件[单行文本1]值未提交"
        },
        "RequestId": "28a7347b-xxxx-xxxx-xxxx-162c4bc230d6"
    }
}

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

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": ""
    }
}

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

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. 错误码

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

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

1. 接口描述​

调用流程​

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

2. 输入参数​

3. 输出参数​

4. 示例​

示例1 创建电子文档-缺少填写控件​

输入示例​

输出示例​

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

输入示例​

输出示例​

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

输入示例​

输出示例​

5. 错误码​

1. 接口描述

调用流程

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

2. 输入参数

3. 输出参数

4. 示例

示例1 创建电子文档-缺少填写控件

输入示例

输出示例

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

输入示例

输出示例

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

输入示例

输出示例

5. 错误码