文档变更
2022年时，模板文件上传变为上传模板文件，以便开发者更容易理解，仅中文名称变更，其功能保持不变。
2021年时，通过上传方式创建模板变为获取模板文件上传地址，其接口功能未做调整。
上传模板文件步骤概述
开发者必须完成以下两个步骤才可以成功将模板文件上传到e签宝服务端。
模板文件上传到e签宝服务端的必要步骤：
步骤1：获取模板文件上传地址
步骤2：上传文件流（二进制字节流）
PDF模板文件可参考线上制作模板方法、线下制作模板方法和接口制作模板方法三种方法进行制作。
详细交互时序图如下：
步骤1 获取模板文件上传地址
接口描述
获取模板文件上传Url地址和模板ID，开发者可以通过此Url把待签署文件上传到e签宝服务端。
接口返回的模板ID需妥善保管以便后续进行模板内容填充时使用。
注意：
（1）上传的文件总大小要求<=40MB，其中单页内容大小要求<=9MB。
（2）文件名 fileName 参数值不可以含有以下特殊字符：
/ \ : * " < > | ？以及所有emoji表情
（3）支持上传的文件格式详见文末的支持的文件格式列表。
接口地址&请求方式
接口地址：/v1/docTemplates/createByUploadUrl
请求方式：POST
请求头格式
具体请求头格式结构，请点击查看公共参数说明。
请求参数
参数名称 | 类型 | 必选 | 参数说明 | 参数说明 （左右拖动查看完整描述） |
contentMd5 | string | 是 | body | 模板文件md5值， 先计算文件md5值，在对该md5值进行base64编码 （1）点击查看示例代码。 （2）通过【获取文件哈希值小工具】计算。 |
contentType | string | 是 | body | 目标文件的MIME类型，支持： （1）application/octet-stream （2）application/pdf 注意： 步骤2中的Content-Type参数要和这里一致，否则会出现403报错。 |
fileName | string | 是 | body | 文件名称，必须带扩展名如:.pdf,.doc,.docx 注意： （1）该字段的文件后缀名称和真实的文件后缀需要一致。比如上传的文件类型是word文件，那该参数需要传“xxx.docx”，不能是“xxx.pdf” （2）该字段建议直接传入pdf文件，其他类型文件建议本地自行转换成pdf，避免通过接口格式转换引起的格式错误、耗时久等问题。 （3）文件名称不支持以下9个字符：/ \ : * " < > | ？以及所有emoji表情 |
convert2Pdf | boolean | 否 | body | 是否需要转换成PDF文档，默认false。 true - 需要转换成PDF false - 不需转换成PDF 注意： （1）如果本身就是PDF文件，该参数必须是false。 （2）如果模板文件为.doc/.docx等格式需要传true。 （3）转换是异步行为，如果指定要转换，需要调用查询文件信息接口查询状态，转换完成后才可使用。 |
响应参数
展开全部参数参数名称 | 类型 | 必选 | 参数说明 （左右拖动查看完整描述） | |
code | int | 是 | 业务码，0表示成功 | |
message | string | 否 | 业务信息 | |
data | object | 否 | 业务数据 | |
templateId | string | 否 | 模板ID | |
uploadUrl | string | 否 | 文件上传地址，链接有效期60分钟。 | |
请求示例
POST https://openapi.esign.cn/v1/docTemplates/createByUploadUrl
{
"contentMd5":"cTNpB5QZ8fAP9jScrV8teA==",
"contentType":"application/octet-stream",
"fileName":"测试模板.docx",
"convert2Pdf":true
}响应示例
{
"code": 0,
"data": {
"templateId": "adfadfadfweweafadfadfa",
"uploadUrl": "https://esignoss.oss-cn-hangzhou.aliyuncs.com/1111563786/5d45dc91-470b-41dd-8e6f-9663ee9641db/%E6%89%B9%E9%87%8F%E5%AF%BC%E5%85%A5-%E9%94%99%E8%AF%AF%E6%95%B0%E6%8D%AE.xls?Expires=1559294245&OSSAccessKeyId=LTAIdvHfiVrzDKbE&Signature=hBEuUHAC7TVxzRIr/BihG1m3QEQ%3D"
},
"message": "成功"
}错误码
错误码 | 错误描述 | 排查方法 （左右拖动查看完整描述） |
1430011 | 模板文件未转换完成 | 如果模板是PDF的话，convert2Pdf 必须传false， 如果是传true就会报这个错 |
步骤2 文件流上传
功能描述
通过已获取到的 uploadUrl（文件上传地址）使用 PUT 请求方法把文件流（二进制字节流）上传到e签宝服务端，文件流（二进制字节流）上传完毕后才可以在后续成功进行模板内容填充。
如果文件流上传时出现报错，请参考文件上传常见报错及解决方法尝试解决。
上传地址
步骤1 获取模板文件上传地址 中所获取到的 uploadUrl。
上传方式
HTTP的PUT请求方法。
请求头
请求头入参如下：
参数名称 | 类型 | 必选 | 参数说明 （左右拖动查看完整描述） |
Content-MD5 | string | 是 | 与【步骤1 获取文件上传地址】Body体中contentMd5值一致 注意：必须跟上述说明接口的contentMd5参数一致，否则会报403错误 |
Content-Type | string | 是 | 与【步骤1 获取文件上传地址】Body体中contentType值一致 如：application/octet-stream 或 application/pdf 注意：必须跟上述说明接口的MIME类型参数一致，否则会报403错误 |
请求参数
HTTP BODY：待上传文件的二进制字节流。
注意：此文件必须与contentMd5值对应的文件一致
响应参数
参数名称 | 类型 | 必选 | 参数说明 （左右拖动查看完整描述） |
errCode | int | 是 | 业务码，0表示成功 |
msg | string | 否 | 成功 |
Postman请求示例
响应示例
{
"errCode": 0,
"msg": "成功"
}支持的文件格式列表
文件扩展名 | 文件扩展名说明 | 支持情况 |
属于Portable Document Format 的简称 | 支持上传，无需格式转换 | |
.docx | Microsoft Office Word 2007 及以后版本 | 支持上传和转成PDF格式 |
.doc | Microsoft Office Word 97-2003 版本 | 支持上传和转成PDF格式 |
.rtf | Microsoft 富文本格式(Rich Text Format） | 支持上传和转成PDF格式 |
.xlsx | Microsoft Office Excel 2007 及以后版本 | 支持上传和转成PDF格式 |
.xls | Microsoft Office Excel 97-2003 版本 | 支持上传和转成PDF格式 |
.pptx | Microsoft Office PowerPoint 2007 及以后版本 | 支持上传和转成PDF格式 |
.ppt | Microsoft Office PowerPoint 97-2003 版本 | 支持上传和转成PDF格式 |
.wps | WPS Office 文字文稿 | 支持上传和转成PDF格式 |
.et | WPS Office 表格文件 | 支持上传和转成PDF格式 |
.dps | WPS Office 演示文稿 | 支持上传和转成PDF格式 |
.jpeg | JPEG图像格式文件 | 支持上传和转成PDF格式 |
.jpg | 属于.JPEG图像格式文件扩展名的简写 | 支持上传和转成PDF格式 |
.png | PNG图像格式文件 | 支持上传和转成PDF格式 |
.bmp | BMP图像格式文件 | 支持上传和转成PDF格式 |
.tiff | TIFF图像格式文件 | 支持上传和转成PDF格式 |
.tif | 属于.TIFF图像格式文件扩展名的简写 | 支持上传和转成PDF格式 |
.gif | GIF图像格式文件 | 支持上传和转成PDF格式 |
.html | 超文本标记语言格式文件 | 支持上传和转成PDF格式 |
.htm | 属于.html超文本标记语言格式文件扩展名的简写 | 支持上传和转成PDF格式 |
说明：
如果文件中含有大量图片，在转换成PDF格式时耗时较久，具体耗时与实际文件大小有关。
我要纠错