合同文件签署服务API
点击展开收起
合同文件签署服务API对接指南
文件类API
合同模板类API
签署流程-发起类
签署流程-下载类
签署流程-变更类
签署流程-查询类
签署流程-审批类
签署区-变更类
待签文件及附属材料-变更类
抄送方-变更类
合同解约服务
回调通知服务
下载对接示例DEMO
附录

查询合同模板中控件详情

更新时间：2024-07-02 14:57:37

接口描述

通过合同模板 docTemplateId 来获取模板中设置的所有控件信息，后续可通过【填写模板生成文件】接口来填充模板。

接口地址&请求方法

接口地址：https://{host}/v3/doc-templates/{docTemplateId}

请求方法：GET

请求头格式

具体请求头参数，请查看公共请求头格式。

请求参数

参数名称

参数类型

必选

参数位置

参数说明

docTemplateId

string

是

path

合同模板ID（通过【获取制作文件模板页面链接】接口获取）

响应参数

展开全部参数参数名称

参数类型

必选

参数说明（左右拖动查看完整描述）

code

int32

是

业务码，0表示成功，非0表示异常。

message

string

否

业务信息

请根据 code 来判断错误情况，不应该依赖 message匹配，因为 message 可能会调整。

data（点击“+”展开详情）

object

否

业务数据

docTemplateId

string

否

合同模板ID

docTemplateName

string

否

合同模板名称

createTime

int64

否

合同模板创建时间（Unix时间戳格式，单位：毫秒）

updateTime

int64

否

合同模板更新时间（Unix时间戳格式，单位：毫秒）

fileDownloadUrl

string

否

合同模板的底稿PDF文件下载链接

  • 链接有效期为60分钟
  • 当模板类型为html模板时，默认会返回 null

components（点击“+”展开详情）

array

否

模板中的控件列表信息

componentId

string

否

控件ID（设置合同文件模板时由系统系统生成）

componentKey

string

否

控件Key（设置合同文件模板时由用户自定义）

componentName

string

否

控件名称

required

boolean

否

控件是否必填

true - 必填，false - 非必填

componentType

int32

否

控件类型

1 - 单行文本，2 - 数字，3 - 日期，6 - 签章区域，8 - 多行文本，9 - 复选，10 - 单选，11 - 图片，14 -下拉框，15 - 勾选框，16 - 身份证，17 - 备注区域，18 - 动态表格，19 - 手机号

componentPosition

object

否

控件位置信息

componentPositionX

float

否

控件位置X横坐标

componentPositionY

float

否

控件位置Y纵坐标

componentPageNum

int32

否

控件所在页码

componentSpecialAttribute

object

否

控件特有属性

dateFormat

string

否

日期格式（日期控件特有）

imageType

string

否

图片类型（图片控件特有）

IDCard_widthwise（身份证横向，等比缩放大小）

IDCard_longitudinal（身份证纵向，等比缩放大小）

other （其他，自由缩放大小）

options（点击“+”展开详情）

array

否

选项（下拉框控件、单选控件、多选控件特有）

optionContent

string

否

选项内容

optionOrder

int32

否

选项顺序

selected

boolean

否

选项是否默认选中

tableContent

array

否

表格行列内容（动态表格控件特有），格式：

[row{"column1":"value1","column2":"value2"}]

补充说明：

  • row 表示动态表格对应的行，row的个数依据模板动态表格控件中所添加的所添加的行数。
  • column1 表示当前行中单元格的Key值
  • value1 表示当前行中单元格的Value值，单元格未设置固定值时为""空字符串，否则为所设置的固定值。
  • 详见 tableContent 解释说明。

numberFormat

string

否

数字格式（数字控件特有），格式如下：

0 - 整数，0.0 - 保留一位小数，0.00 - 保留两位小数

componentMaxLength

string

否

可填充的长度上限，单位：中文字符

【注】1个中文字符=2个英文字符；

仅适用于制作PDF模板时，返回此参数；

signerRole

string

否

签署方角色标识（签署区控件）

componentSize

object

否

控件尺寸

componentWidth

float

否

控件宽度（矩形的左右距离，单位为px）

componentHeight

float

否

控件高度（矩形的上下距离，单位为px）

normalSignField

object

否

签章区属性

showSignDate

int32

否

是否显示签署日期

0 - 不显示，1 - 显示

dateFormat

string

否

日期格式，支持以下日期格式：

yyyy年MM月dd日

yyyy-MM-dd

yyyy/MM/dd

yyyy-MM-dd HH:mm:ss

signFieldStyle

int32

否

签章样式

1 - 单页签章，2 - 骑缝签章

sealSpecs

int32

否

落章规则

1 - 以实际印章规格加盖

2 - 自定义印章规格加盖（根据指定的签署区宽高适配）

remarkSignField

object

否

备注区属性

aiCheck

int32

否

是否开启手写抄录AI校验

0 - 不开启，1 - 开启 AI 校验，2 - 强制 AI 校验

inputType

int32

否

备注文字输入方式

1 - 手写抄录方式，2 - 自由输入方式

remarkContent

string

否

预设手写抄录信息

remarkFontSize

string

否

备注文字的字号，单位pt，默认值12pt

注：签署侧需要的字号单位是px，模板侧通用的都是pt，因此要做一次转换；pt与px间的换算关系是：0.75px=1pt

originCustomComponentId

string

否

自定义控件ID

（【获取制作文件模板页面链接】接口传入的自定义控件ID值）

请求示例

GET https://bestcert.net/v3/doc-templates/061778***701b7

响应示例

{
    "code":0,
    "message":"成功",
    "data":{
        "docTemplateId":"061778***701b7",
        "docTemplateName":"模板一",
        "createTime":1649750964000,
        "updateTime":1649750964000,
        "fileDownloadUrl":"https://esignoss.esign.cn/1111564182/267243f5-**-**-21d586e6a3d5/1.pdf?Expires=**&OSSAccessKeyId=***&Signature=***",
        "components":[
            {
                "componentId":"3526edf51***f4ecae8f",
                "componentKey":"2022esign",
                "componentName":"这是一个签署区",
                "componentType":6,
                "componentPosition":{
                    "componentPositionX":97.91,
                    "componentPositionY":673.8,
                    "componentPageNum":1
                },
                "componentSpecialAttribute": {
                    "dateFormat": null,
                    "imageType": null,
                    "options": null,
                    "tableContent": null,
                    "numberFormat": null,
                    "componentMaxLength": null,
                    "signerRole": "签署方角色：甲方"
                },
                "componentSize":{
                    "componentWidth":100,
                    "componentHeight":100
                },
                "remarkSignField":null,
                "normalSignField":{
                    "showSignDate":0,
                    "dateFormat":null,
                    "signFieldStyle":1,
                    "sealSpecs": 1
                },
                "originCustomComponentId": null
            },
            {
                "componentId":"59af7766***36ef41b",
                "componentKey":"2022signer",
                "componentName":"这是一个单行文本，例如签署人姓名",
                "componentType":1,
                "componentPosition":{
                    "componentPositionX":169.16,
                    "componentPositionY":704.42,
                    "componentPageNum":1
                },
                "componentSpecialAttribute":{
                    "dateFormat":null,
                    "imageType":null,
                    "options":null
                },
                "componentSize":{
                    "componentWidth":160,
                    "componentHeight":15
                },
                "remarkSignField":null,
                "normalSignField":null,
                "originCustomComponentId": "714a081***3538f8ba57"
            },
            {
                "componentId":"7315e9af***72d2dac40",
                "componentKey":"2022signtime",
                "componentName":"这是一个日期控件",
                "componentType":3,
                "componentPosition":{
                    "componentPositionX":163.03,
                    "componentPositionY":530.67,
                    "componentPageNum":1
                },
                "componentSpecialAttribute":{
                    "dateFormat":"yyyy-MM-dd",
                    "imageType":null,
                    "options":null
                },
                "componentSize":{
                    "componentWidth":71,
                    "componentHeight":15
                },
                "remarkSignField":null,
                "normalSignField":null,
                "originCustomComponentId": null
            },
            {
                "componentId":"b9e35ea**053333d",
                "componentKey":"2022signchoice",
                "componentName":"这是一个选择控件",
                "componentType":14,
                "componentPosition":{
                    "componentPositionX":270.41,
                    "componentPositionY":560.05,
                    "componentPageNum":1
                },
                "componentSpecialAttribute":{
                    "dateFormat":null,
                    "imageType":null,
                    "options":[
                        {
                            "optionOrder":0,
                            "optionContent":"选项一",
                            "selected":false
                        },
                        {
                            "optionOrder":1,
                            "optionContent":"选项二",
                            "selected":false
                        },
                        {
                            "optionOrder":2,
                            "optionContent":"选项三",
                            "selected":false
                        }
                    ]
                },
                "componentSize":{
                    "componentWidth":160,
                    "componentHeight":15
                },
                "remarkSignField":null,
                "normalSignField":null,
                "originCustomComponentId": null
            }
        ]
    }
}

错误码

点击查看错误码