查询模板信息列表

1. 接口描述

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

通过此接口（DescribeTemplates）查询该第三方平台子客企业在电子签拥有的有效模板，不包括第三方平台模板。

适用场景 该接口常用来配合用模板创建签署流程和通过多模板创建合同组签署流程接口，作为创建合同的前置接口使用。通过此接口查询到模板信息后，再通过调用创建合同的接口，指定模板ID，指定模板中需要的填写控件内容等，完成合同文档的创建。

模板的来源 子客企业的模板有两种途径获取

渠道方(平台方)配置完成后, 分发给同应用的各个子企业
子客企业通过CreateConsoleLoginUrl创建的链接登录子客控制台自己创建

一个模板通常会包含以下结构信息

模板ID, 模板名字等基本信息
发起方参与信息Promoter、签署参与方 Recipients，后者会在模板发起合同时用于指定参与方
发起方和签署方的填写控件 Components
签署方的签署控件 SignComponents

模板中各元素的层级关系, 所有的填写控件和签署控件都归属某一个角色(通过控件的ComponentRecipientId来关联)

注意

查询条件TemplateId、TemplateName与ChannelTemplateId可同时存在，即可查询同时满足这些条件的模板。
TemplateId 和TemplateIds互为独立，若两个参数都传入，则以TemplateId为准

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

推荐使用 API Explorer

点击调试

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

2. 输入参数

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

参数名称	必选	类型	描述
Action	是	String	公共参数，本接口取值：DescribeTemplates。
Version	是	String	公共参数，本接口取值：2021-05-26。
Region	否	String	公共参数，此参数为可选参数。
Agent	是	Agent	关于渠道应用的相关信息，包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容，您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。此接口下面信息必填。渠道应用标识: Agent.AppId 第三方平台子客企业标识: Agent.ProxyOrganizationOpenId 第三方平台子客企业中的员工标识: Agent. ProxyOperator.OpenId 第三方平台子客企业和员工必须已经经过实名认证
TemplateId	否	String	合同模板ID，为32位字符串。可以通过生成子客登录链接登录企业控制台, 在企业模板中得到合同模板ID。
ContentType	否	Integer	查询模板的内容 0：（默认）模板列表及详情 1：仅模板列表, 不会返回模板中的签署控件, 填写控件, 参与方角色列表等信息
TemplateIds.N	否	Array of String	合同模板ID数组，每一个合同模板ID为32位字符串, 最多支持200个模板的批量查询。注意: 1. `此参数TemplateIds与TemplateId互为独立，若两者均传入，以TemplateId为准。` 2. `请确保每个模板均正确且属于当前企业，若有任一模板不存在，则返回错误。` 4. `若传递此参数，分页参数(Limit,Offset)无效`
Limit	否	Integer	指定每页返回的数据条数，和Offset参数配合使用。注：`1.默认值为20，单页做大值为200。`
Offset	否	Integer	查询结果分页返回，指定从第几页返回数据，和Limit参数配合使用。注：`1.offset从0开始，即第一页为0。` `2.默认从第一页返回。`
TemplateName	否	String	模糊搜索的模板名称，注意是模板名的连续部分，长度不能超过200，可支持由中文、字母、数字和下划线组成字符串。
ChannelTemplateId	否	String	对应第三方应用平台企业的模板ID，通过此值可以搜索由第三方应用平台模板ID下发或领取得到的子客模板列表。
QueryAllComponents	否	Boolean	返回控件的范围, 是只返回发起方自己的还是所有参与方的 false：（默认）只返回发起方控件 true：返回所有参与方(包括发起方和签署方)控件
WithPreviewUrl	否	Boolean	是否获取模板预览链接。 false：不获取（默认） true：获取设置为true之后，返回参数PreviewUrl，为模板的H5预览链接, 有效期5分钟。可以通过浏览器打开此链接预览模板，或者嵌入到iframe中预览模板。注: `此功能为白名单功能，使用前请联系对接的客户经理沟通。`
WithPdfUrl	否	Boolean	是否获取模板的PDF文件链接。 false：不获取（默认） true：获取设置为true之后，返回参数PdfUrl，为模板PDF文件链接，有效期5分钟, 可以用于将PDF文件下载到本地注: `此功能为白名单功能，使用前请联系对接的客户经理沟通。`

3. 输出参数

参数名称	类型	描述
Templates	Array of TemplateInfo	模板详情列表数据
TotalCount	Integer	查询到的模板总数示例值：20
Limit	Integer	每页返回的数据条数示例值：10
Offset	Integer	查询结果分页返回，此处指定第几页。页码从0开始，即首页为0。示例值：0
RequestId	String	唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 模板查询接口-指定模板Id查询模板信息

指定查询条件为TemplateId, 只返回此模板的信息

输入示例

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

{
    "Agent": {
        "AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "ProxyAppId": ""
    },
    "TemplateIds": [
        "yDSLVUUckpo3pub6UE5dPdv8pkDsrbEn"
    ]
}

输出示例

{
    "Response": {
        "Templates": [
            {
                "TemplateId": "yDSLVUUckpo3pub6UE5dPdv8pkDsrbEn",
                "TemplateName": "西红柿买卖合同模板",
                "Description": "南山农批西红柿买卖合同模板",
                "Components": [],
                "Recipients": [
                    {
                        "RecipientId": "yDSLVUUckpo3nocjUEnf33ki7GtMQC2L",
                        "RecipientType": "INDIVIDUAL",
                        "Description": "",
                        "RoleName": "买房-自然人",
                        "RequireValidation": false,
                        "RequireSign": false,
                        "SignType": 0,
                        "RoutingOrder": -1,
                        "IsPromoter": false
                    },
                    {
                        "RecipientId": "yDSLVUUckpo3noc8UEnf33kxKp7Waeq1",
                        "RecipientType": "ENTERPRISE",
                        "Description": "",
                        "RoleName": "卖方-菜市场",
                        "RequireValidation": false,
                        "RequireSign": false,
                        "SignType": 0,
                        "RoutingOrder": -1,
                        "IsPromoter": false
                    }
                ],
                "SignComponents": [
                    {
                        "ComponentId": "ComponentId_2",
                        "ComponentType": "SIGN_SEAL",
                        "ComponentName": "企业印章",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3noc8UEnf33kxKp7Waeq1",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 119,
                        "ComponentHeight": 119,
                        "ComponentPage": 1,
                        "ComponentPosX": 32.640625,
                        "ComponentPosY": 0,
                        "ComponentExtra": "{\"Date\":true,\"isAfterCut\":false,\"PageRanges\":[]}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    },
                    {
                        "ComponentId": "ComponentId_5",
                        "ComponentType": "SIGN_SIGNATURE",
                        "ComponentName": "个人签名/印章",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3nocjUEnf33ki7GtMQC2L",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 119,
                        "ComponentHeight": 43,
                        "ComponentPage": 1,
                        "ComponentPosX": 397.640625,
                        "ComponentPosY": 14,
                        "ComponentExtra": "{\"Date\":true,\"isAfterCut\":false}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    },
                    {
                        "ComponentId": "ComponentId_6",
                        "ComponentType": "SIGN_DATE",
                        "ComponentName": "签署日期1",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3nocjUEnf33ki7GtMQC2L",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 119,
                        "ComponentHeight": 20,
                        "ComponentPage": 1,
                        "ComponentPosX": 397.640625,
                        "ComponentPosY": 57,
                        "ComponentExtra": "{\"Format\":\"yyyy年m月d日\",\"Gaps\":\"2,2\",\"FontSize\":12,\"FontAlign\":\"Center\",\"Font\":\"黑体\",\"isAfterCut\":false}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    },
                    {
                        "ComponentId": "ComponentId_3",
                        "ComponentType": "SIGN_DATE",
                        "ComponentName": "签署日期",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3noc8UEnf33kxKp7Waeq1",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 119,
                        "ComponentHeight": 20,
                        "ComponentPage": 1,
                        "ComponentPosX": 32.640625,
                        "ComponentPosY": 119,
                        "ComponentExtra": "{\"Format\":\"yyyy年m月d日\",\"Gaps\":\"2,2\",\"FontSize\":12,\"FontAlign\":\"Center\",\"Font\":\"黑体\",\"isAfterCut\":false}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    }
                ],
                "TemplateType": 3,
                "IsPromoter": false,
                "Creator": "张三",
                "CreatedOn": 1699259970,
                "PreviewUrl": "",
                "PdfUrl": "",
                "ChannelTemplateId": "",
                "ChannelTemplateName": "",
                "ChannelAutoSave": 0,
                "TemplateVersion": "20231106002",
                "Available": 1
            }
        ],
        "TotalCount": 1,
        "Limit": 0,
        "Offset": 0,
        "RequestId": "072c42c3-8ec2-43f3-b872-bc28594b0597"
    }
}

示例2 模板查询接口-模糊搜索模板名

1.指定查询条件为TemplateName 2.指定QueryAllComponents为true，返回所有参与方(创建方+签署方)的填写控件列表Components

输入示例

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

{
    "Agent": {
        "AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "ProxyAppId": ""
    },
    "TemplateName": "西红柿",
    "QueryAllComponents": true
}

输出示例

{
    "Response": {
        "Templates": [
            {
                "TemplateId": "yDSLVUUckpo3pub6UE5dPdv8pkDsrbEn",
                "TemplateName": "西红柿买卖合同模板",
                "Description": "南山农批西红柿买卖合同模板",
                "Components": [
                    {
                        "ComponentId": "ComponentId_11",
                        "ComponentType": "TEXT",
                        "ComponentName": "西红柿的价格",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3nwi1UEnf33kBMNXjdB2c",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 144,
                        "ComponentHeight": 20,
                        "ComponentPage": 1,
                        "ComponentPosX": 336.640625,
                        "ComponentPosY": 205,
                        "ComponentExtra": "{\"FontSize\":12,\"FontAlign\":\"Left\",\"Font\":\"黑体\",\"SubType\":\"TEXT\",\"MaxLength\":12}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    },
                    {
                        "ComponentId": "ComponentId_12",
                        "ComponentType": "TEXT",
                        "ComponentName": "西红柿的交接时间",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3nwi1UEnf33kBMNXjdB2c",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 144,
                        "ComponentHeight": 20,
                        "ComponentPage": 1,
                        "ComponentPosX": 341.640625,
                        "ComponentPosY": 270,
                        "ComponentExtra": "{\"FontSize\":12,\"FontAlign\":\"Left\",\"Font\":\"黑体\",\"SubType\":\"TEXT\",\"MaxLength\":12}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    }
                ],
                "Recipients": [
                    {
                        "RecipientId": "yDSLVUUckpo3nwi3UEnf33kxdJyaybFb",
                        "RecipientType": "INDIVIDUAL",
                        "Description": "",
                        "RoleName": "买房-自然人",
                        "RequireValidation": false,
                        "RequireSign": false,
                        "SignType": 0,
                        "RoutingOrder": -1,
                        "IsPromoter": false
                    },
                    {
                        "RecipientId": "yDSLVUUckpo3nwi1UEnf33kBMNXjdB2c",
                        "RecipientType": "ENTERPRISE",
                        "Description": "",
                        "RoleName": "卖方-菜市场",
                        "RequireValidation": false,
                        "RequireSign": false,
                        "SignType": 0,
                        "RoutingOrder": -1,
                        "IsPromoter": false
                    }
                ],
                "SignComponents": [
                    {
                        "ComponentId": "ComponentId_2",
                        "ComponentType": "SIGN_SEAL",
                        "ComponentName": "企业印章",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3nwi1UEnf33kBMNXjdB2c",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 119,
                        "ComponentHeight": 119,
                        "ComponentPage": 1,
                        "ComponentPosX": 32.640625,
                        "ComponentPosY": 0,
                        "ComponentExtra": "{\"Date\":true,\"isAfterCut\":false,\"PageRanges\":[]}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    },
                    {
                        "ComponentId": "ComponentId_5",
                        "ComponentType": "SIGN_SIGNATURE",
                        "ComponentName": "个人签名/印章",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3nwi3UEnf33kxdJyaybFb",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 119,
                        "ComponentHeight": 43,
                        "ComponentPage": 1,
                        "ComponentPosX": 397.640625,
                        "ComponentPosY": 14,
                        "ComponentExtra": "{\"Date\":true,\"isAfterCut\":false}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    },
                    {
                        "ComponentId": "ComponentId_6",
                        "ComponentType": "SIGN_DATE",
                        "ComponentName": "签署日期1",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3nwi3UEnf33kxdJyaybFb",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 119,
                        "ComponentHeight": 20,
                        "ComponentPage": 1,
                        "ComponentPosX": 397.640625,
                        "ComponentPosY": 57,
                        "ComponentExtra": "{\"Format\":\"yyyy年m月d日\",\"Gaps\":\"2,2\",\"FontSize\":12,\"FontAlign\":\"Center\",\"Font\":\"黑体\",\"isAfterCut\":false,\"PageRanges\":[]}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    },
                    {
                        "ComponentId": "ComponentId_3",
                        "ComponentType": "SIGN_DATE",
                        "ComponentName": "签署日期",
                        "ComponentRequired": true,
                        "ComponentRecipientId": "yDSLVUUckpo3nwi1UEnf33kBMNXjdB2c",
                        "FileIndex": 0,
                        "GenerateMode": "",
                        "ComponentWidth": 119,
                        "ComponentHeight": 20,
                        "ComponentPage": 1,
                        "ComponentPosX": 32.640625,
                        "ComponentPosY": 119,
                        "ComponentExtra": "{\"Format\":\"yyyy年m月d日\",\"Gaps\":\"2,2\",\"FontSize\":12,\"FontAlign\":\"Center\",\"Font\":\"黑体\",\"isAfterCut\":false,\"PageRanges\":[]}",
                        "ComponentValue": "",
                        "ComponentDateFontSize": 0,
                        "DocumentId": "",
                        "ComponentDescription": "",
                        "OffsetX": 0,
                        "OffsetY": 0,
                        "ChannelComponentId": "",
                        "KeywordOrder": "",
                        "KeywordPage": 0,
                        "RelativeLocation": "",
                        "KeywordIndexes": [],
                        "Placeholder": ""
                    }
                ],
                "TemplateType": 3,
                "IsPromoter": false,
                "Creator": "张三",
                "CreatedOn": 1699259970,
                "PreviewUrl": "",
                "PdfUrl": "",
                "ChannelTemplateId": "",
                "ChannelTemplateName": "",
                "ChannelAutoSave": 0,
                "TemplateVersion": "20231106004",
                "Available": 1
            }
        ],
        "TotalCount": 1,
        "Limit": 20,
        "Offset": 0,
        "RequestId": "8fb09e62-9642-44c8-992b-ddd6e5086293"
    }
}

示例3 模板查询接口-通过不存在的模板Id查询模板信息

1.指定一个不存在的模板ID进行查询

输入示例

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

{
    "Agent": {
        "AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "ProxyAppId": ""
    },
    "TemplateIds": [
        "yDRSRUUgygj6qnwfUuO4zjEwc193c2hH"
    ]
}

输出示例

{
    "Response": {
        "RequestId": "8fb09e62-9642-44c8-992b-ddd6e5086293",
        "Templates": [],
        "Offset": 0,
        "Limit": 20,
        "TotalCount": 0
    }
}

5. 错误码

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

错误码	描述
FailedOperation	操作失败。
InternalError	内部错误。
InternalError.System	系统错误。
InvalidParameter	参数错误。
InvalidParameter.Application	应用号不存在。
InvalidParameter.ContentType	查询内容参数有误。
InvalidParameter.DataNotFound	数据不存在。
InvalidParameter.ParamError	参数错误。
InvalidParameterValue	参数取值错误。
MissingParameter	缺少参数错误。
OperationDenied	操作被拒绝。
OperationDenied.NoIdentityVerify	未通过个人实名。
OperationDenied.UserNotInOrganization	用户不归属于当前企业，无法操作，请检查后重试。
ResourceNotFound	资源不存在。
ResourceNotFound.Application	应用号不存在。
ResourceNotFound.Resource	资源不存在。
ResourceNotFound.Template	模板不存在。
ResourceNotFound.User	用户信息不存在。
ResourceUnavailable	资源不可用。
UnauthorizedOperation	未授权操作。
UnauthorizedOperation.NoPermissionFeature	请升级到对应版本后即可使用该接口。

1. 接口描述​

2. 输入参数​

3. 输出参数​

4. 示例​

示例1 模板查询接口-指定模板Id查询模板信息​

输入示例​

输出示例​

示例2 模板查询接口-模糊搜索模板名​

输入示例​

输出示例​

示例3 模板查询接口-通过不存在的模板Id查询模板信息​

输入示例​

输出示例​

5. 错误码​

1. 接口描述

2. 输入参数

3. 输出参数

4. 示例

示例1 模板查询接口-指定模板Id查询模板信息

输入示例

输出示例

示例2 模板查询接口-模糊搜索模板名

输入示例

输出示例

示例3 模板查询接口-通过不存在的模板Id查询模板信息

输入示例

输出示例

5. 错误码