将本地文件上传至e签宝服务端，可用于制作模板、发起合同签署等。
【注意】成功上传文件共分为两步操作：
1. 先获取到服务端的上传地址fileUploadUrl和文件fileId;
2. 再将文件流上传至fileUploadUrl。
上传本地文件概述
上传本地文件到e签宝服务端请按以下步骤顺序操作：
步骤一：获取文件上传地址（点击直接跳转下方 步骤一）
步骤二：上传文件流（点击直接跳转下方 步骤二）
全流程交互时序图如下：
步骤一 获取文件上传地址
接口描述
本接口用于获取上传文件的服务端地址fileUploadUrl和文件fileId，请注意此时获取到的文件fileId为“未上传状态”。
注意事项：
（1）上传的文件总大小要求不超过 50MB，其中单页内容大小要求不超过 20MB。
（2）文件名fileName参数值不可包含特殊字符，例如：/ \ : * " < > | ？以及所有emoji表情等。
（3）支持上传的文件格式参考文末的支持的文件格式列表。
（4）如需获得一个PDF格式的文件，上传非PDF格式文件时，请将convertToPDF参数值设置为true。
（5）如需将上传的doc/docx格式文件转换成HTML格式，请将convertToHTML参数值设置为true。
接口地址&请求方法
点击下述蓝色字体{host}可跳转至API请求域名说明文档
接口地址：https://{host}/v3/files/file-upload-url
请求方法：POST
请求头格式
具体请求头参数，请查看公共请求头格式。
请求参数
参数名称 | 参数类型 | 必选 | 参数位置 | 参数说明 |
contentMd5 | string | 是 | body | 文件的Content-MD5值。 先获取文件MD5的128位二进制数组，再对此二进制进行Base64编码。 （1）可参考Content-MD5计算说明及代码示例计算。 （2）开发调试时可通过【获取文件哈希值小工具】计算。 |
contentType | string | 是 | body | 目标文件的MIME类型 可填写 application/octet-stream 或 application/pdf 补充说明：步骤二 上传文件流时请求头中的Content-Type参数值要与此参数值一致，否则上传文件流时会出现403报错。 |
fileName | string | 是 | body | 文件名称（必须带上文件扩展名，不然会导致后续发起流程校验过不去。示例：合同名1.pdf 、合同名2.docx） 补充说明： （1）该字段的文件后缀名称和真实的文件后缀需要一致。比如上传的文件类型是word文件，那该参数需要传“xxx.docx”，不能是“xxx.pdf”。 （2）该字段建议直接传入pdf文件，其他类型文件建议本地自行转换成pdf，避免通过接口格式转换引起的格式错误、耗时久等问题。 （3）文件名称不可含有以下9个特殊字符：/ \ : * " < > | ？以及所有emoji表情 |
fileSize | int64 | 是 | body | 文件大小，单位: byte字节 |
convertToPDF | boolean | 否 | body | 是否需要转换成PDF文档，默认值 false。 true - 需要转换成PDF false - 无需转换成PDF 补充说明： （1）若文件已是PDF格式，此参数可不传或传 false 。 （2）若文件非PDF格式，要用于签署或者制作PDF模板，此参数值必须传 true。 （3）当文件用于制作HTML模板，此参数可不传或参数值必须传 false。 |
convertToHTML | boolean | 否 | body | 是否需要转换成HTML文档，默认值 false。 true - 需要转换成HTML false - 无需转换成HTML 补充说明： （1）上传 .doc 和 .docx 格式文件时才支持转成HTML。（建议用Office制作文件，WPS可能会导致格式错乱） （2）若上传的文件用于制作HTML模板，此参数值必须传 true。（不支持直接上传HTML格式的文件） （3）当文件用于制作PDF模板，此参数可不传或参数值必须传 false。 |
dedicatedCloudId | string | 否 | body | 专属云项目ID 补充说明： （1）专属云：文件需要存储在开发者本地系统，购买了专属云服务时使用； （2）专属云项目ID获取方式：请先联系对接群内技术获取； （3）专属云文件暂不支持模板相关功能；如使用模板功能，模板填充后生成的文件会存储到e签宝云端服务器，变成公有云文件。 |
响应参数
展开全部参数参数名称 | 参数类型 | 必选 | 参数说明 | |
code | int32 | 是 | 业务码，0表示成功，非0表示异常。 | |
message | string | 否 | 业务信息 请根据 code 来判断错误情况，不应该依赖 message 匹配，因为 message 可能会调整。 | |
data（点击“+”展开详情） | object | 否 | 业务数据 | |
fileId | string | 否 | 文件ID（请注意保管好文件ID，可用于后续制作模板、签署相关操作） | |
fileUploadUrl | string | 否 | 文件上传地址，链接有效期60分钟。（请继续按下方的步骤二，将文件流上传到该地址中） | |
请求示例
{
"contentMd5":"eGMHwA4TW***KMxreUQ==",
"contentType":"application/octet-stream",
"convertToPDF":true,
"fileName":"房屋租赁协议.docx",
"fileSize":25426
}响应示例
{
"code":0,
"data":{
"fileUploadUrl":"http://esignoss.esign.cn/1111564182/bcc7b1d0-6a2b-45bc-a6b0-68097a99ce08/%E8%8A%9C%E6%B5%A3%E4%B8%8A%E4%BC%A0%E6%96%87%E4%BB%B61?Expires=1570674805&OSSAccessKeyId=STS.NJUf5d3CTSM8Koy6MB3ZrftFK&Signature=xB%2B62bPNlPhE3ZDP8lZ4TbBYk0I%3D&callback-var=eyJ4OmZpbGVfa2V5IjoiJDZkM2E1NWIxLWM2Y2YtNDAyNi04NDI5LTViMDBiNWIxY2JlZSQyMTY3NzAwNjM0In0%3D%0A&callback=eyJjYWxsYmFja1VybCI6Imh0dHA6LylVHlwZX0sXCJzaXplXCI6ICR7c2l6ZX0sXCJidWNrZXRcIjogJHtidWNrZXR9LFwib2JqZWN0XCI6ICR7b2JqZWN0fSxcImV0YWdcIjogJHtldGFnfSxcImZpbGVfa2V5XCI6JHt4OmZpbGVfa2V5fX0iLCJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL2pzb24ifQ%3D%3D%0A&security-token=CAIS%2BAF1q6Ft5B2yfSjIr4ngLY/Q3px15I/TSUnI0k0XP9VeibHtqTz2IHtKdXRvBu8Xs/4wnmxX7f4YlqB6T55OSAmcNZEod3TTArDkMeT7oMWQweEurv/MQBqyaXPS2MvVfJ%2BOLrf0ceusbFbpjzJ6xaCAGxypQ12iN%2B/m6/Ngdc9FHHPPD1x8Ccx***xxx",
"fileId":"c64665aa4f***33cd773"
},
"message":"成功"
}错误码
步骤二 上传文件流
功能描述
通过已获取到的fileUploadUrl（文件上传地址），使用 PUT 请求方法把文件流（二进制字节流）上传到服务端，确保文件流上传完毕后，文件fileId才会变更为“文件上传已完成”或“文件已转换pdf”的状态。
如果文件流上传时出现报错，请参考文件上传常见报错及解决方法尝试解决。
【注意事项】
文件流上传接口返回“成功”，仅代表文件上传到oss服务，oss服务会异步通知e签宝变更文件状态。
受网络等各类因素影响，异步通知有概率存在一定时差，e签宝建议开发者调用【查询文件上传状态】 接口查询的文件当前状态，若状态是 2 或 5 时，再将文件ID应用于签署流程。
上传地址
步骤一【获取文件上传地址】的响应参数fileUploadUrl
上传方式
PUT
请求头格式
参数名称 | 参数类型 | 必选 | 参数说明 |
Content-MD5 | string | 是 | 与【步骤一 获取文件上传地址】Body体中contentMd5值一致 补充说明：必须跟上述说明接口的contentMd5参数一致，否则会报403错误 |
Content-Type | string | 是 | 与【步骤一 获取文件上传地址】Body体中contentType值一致 固定值：application/octet-stream 或 application/pdf 补充说明：必须跟上述说明接口的MIME类型参数一致，否则会报403错误 |
请求参数
HTTP 请求的 BODY 体是待上传文件的二进制字节流。
注意：
- 传入的文件二进制字节流必须与之前计算 contentMd5 值时使用的文件二进制字节流一致。
- 若上传印章图片时，请不要传图片的 Base64 编码字符串，应该传图片的二进制字节流。
响应参数
参数名称 | 参数类型 | 必选 | 参数说明 |
errCode | int32 | 是 | 业务码，0表示成功，非0表示异常。 |
msg | string | 否 | 业务信息 |
响应示例
{
"errCode": 0,
"msg": "成功"
}错误码
附：支持的文件格式列表
文件扩展名 | 文件扩展名说明 | 支持情况 |
属于Portable Document Format 的简称 | 支持上传，无需格式转换 | |
.docx | Microsoft Office Word 2007 及以后版本 | 支持上传和转成PDF/HTML格式 |
.doc | Microsoft Office Word 97-2003 版本 | 支持上传和转成PDF/HTML格式 |
.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格式 |
【提示】
如果文件中含有大量图片，在转换格式时耗时较久，具体耗时与实际文件大小有关。
我要纠错