添加填写控件

更新时间：2023-03-08 11:33:56

文档变更说明

原接口的中文名称由“添加输入项组件”变更为“添加填写控件”，其接口功能未做调整。

接口描述

通过 templateId 模板ID向PDF模板文件中添加填写控件，以便后续通过这些填写控件来填充内容。

接口

/v1/docTemplates/{templateId}/components

请求方式

POST

请求头

提供两种安全接入方式，开发者可选择其中一种方式进行对接，对应参数如何获取，参考文档【请点击】。

方式一：请求签名鉴权（优先推荐）

请求头入参示例如下：

参数名称	类型	必选	参数说明
X-Tsign-Open-App-Id	string	是	应用ID
Content-Type	string	是	application/json;charset=UTF-8
X-Tsign-Open-Ca-Timestamp	string	是	API 调用者传递时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟，为了防重放攻击
Accept	string	是	建议统一填写 /
X-Tsign-Open-Ca-Signature	string	是	签名字符串
Content-MD5	string	否	当请求 Body 非 Form 表单时，可以计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验。建议当请求 Body 非 Form 表单时，加上此请求头。
X-Tsign-Open-Auth-Mode	string	是	选择请求方式进行鉴权，固定值，Signature

方式二：OAuth2.0鉴权（不推荐使用）

当安全接入选择OAuth2.0鉴权方式，请点击查阅详情，请求头入参示例如下：

参数名称	类型	必选	参数说明
X-Tsign-Open-App-Id	string	是	应用ID
X-Tsign-Open-Token	string	是	通过获取鉴权Token接口返回
Content-Type	string	是	application/json; charset=UTF-8

请求参数

展开全部参数参数名称				类型	必选	参数类型	参数说明
templateId				string	是	path	模板ID
structComponent				array	是	body	控件信息
	id			string	否	body	输入项组件id，使用时可用id填充，为空时表示添加，不为空时表示修改
	key			string	否	body	模板下输入项组件唯一标识，使用模板时也可用根据key值填充
	type			int	是	body	输入项组件类型（不支持修改） 1-单行文本， 2-数字， 3-日期， 8-多行文本， 11-图片
	context			object	是	body	输入项组件上下文信息，包含了名称，填充格式，样式以及坐标
	label		string	是	body	输入项组件显示名称
	required		boolean	否	body	是否必填，默认true
	limit		string	否	body	输入项组件type=2，type=3时填充格式校验规则数字格式：整数：0（默认值，可不传）保留一位小数：0.0 保留两位小数：0.00 日期格式： yyyy-MM-dd（默认值，可不传） yyyy/MM/dd yyyy年MM月dd日
	style		object	是	body	输入项组件样式
		width	float	是	body	输入项组件宽度
height		float	是	body	输入项组件高度
font		int	否	body	填充字体,默认1， 1-宋体，2-新宋体，4-黑体，5-楷体
fontSize		float	否	body	填充字体大小,默认12
textColor		string	否	body	字体颜色，默认#000000黑色
pos		object	是	body	输入项组件坐标
	page	int	是	body	页码
	x	float	是	body	x轴坐标，左下角为原点
	y	float	是	body	y轴坐标，左下角为原点

响应参数

参数名称	类型	必选	参数说明
code	int	是	业务码，0表示成功
message	string	否	信息
data	array	否	添加/编辑的输入项组件id列表

请求示例

POST https://openapi.esign.cn/v1/docTemplates/{templateId}/components
{
    "structComponent":[
        {
            "id":"45dd9420690b460c9e5ed55b40d7d0f8",
            "key":"key001",
            "type":1,
            "context":{
                "label":"身份证号码",
                "limit":"yyyy-MM-dd",
                "required":true,
                "style":{
                    "font":1,
                    "fontSize":11,
                    "textColor":"#000000",
                    "width":11.11,
                    "height":11.11
                },
                "pos":{
                    "x":11.11,
                    "y":11.11,
                    "page":1
                }
            }
        }
    ]
}

响应示例

{
	"code": 0,
	"data": ["dfadfasdadasdfasdfsadfsadf"],
	"message": "成功"
}