文档变更说明

原接口的中文名称由“通过上传方式创建文件”变更为“获取文件上传地址”，其接口功能未做调整。

文件上传步骤概述

把一个文件上传到e签宝服务端时，开发者需要以下两个大步骤：

步骤1：获取文件上传地址

步骤2：上传文件流（二进制字节流）

详细交互时序图如下：

步骤1 获取文件上传地址

接口描述

获取文件上传Url地址和文件ID，开发者可以通过此Url把待签署文件上传到e签宝服务端。

如果上传非PDF格式文件时，可通过设置 convert2Pdf 参数值为true将文件转成PDF格式。

接口返回的文件ID需妥善保管以便后续发起签署流程时使用。

注意：

1. 上传的单个文件总大小不超过20MB，其中单页内容大小不超过9MB。（当文件包含图片时请关注单页大小）

2. 文件名 fileName 长度限制64（包含后缀名），且参数值不可包含特殊字符，例如：/ \ : * " < > | ？以及所有emoji表情等。

3. 支持上传的文件格式详见文末的支持的文件格式列表。

接口地址

/v1/files/getUploadUrl

请求方式

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

请求参数

参数名称	类型	必选	参数类型	参数说明
contentMd5	string	是	body	先获取文件MD5的二进制数组（128位），再对这个二进制进行base64编码。（1）获取代码示例：【请点击】（2）可使用E签宝官网工具进行计算【请点击】
contentType	string	是	body	目标文件的MIME类型，支持：（1）application/octet-stream （2）application/pdf 注意，后面文件流上传的Content-Type参数要和这里一致，不然就会有403的报错
fileName	string	是	body	文件名称（必须带上文件扩展名，不然会导致后续发起流程校验过不去示例：合同.pdf ）；注意：（1）该字段的文件后缀名称和真实的文件后缀需要一致。比如上传的文件类型是word文件，那该参数需要传“xxx.docx”，不能是“xxx.pdf”。（2）该字段建议直接传入pdf文件，其他类型文件建议本地自行转换成pdf，避免通过接口格式转换引起的格式错误、耗时久等问题。（3）文件名称不支持以下9个字符：/ \ : * " < > \| ？以及所有emoji表情。
fileSize	int64	是	body	文件大小，单位byte
convert2Pdf	boolean	否	body	是否转换成pdf文档，默认false，代表不做转换。转换是异步行为，如果指定要转换，需要调用查询文件信息接口查询状态，转换完成后才可使用。注意：如果本身就是PDF文件，该参数必须是false，可以直接默认不传。

响应参数

展开全部参数参数名称		类型	必选	参数说明
code		int	是	业务码，0表示成功
message		string	否	信息
data		object	否	业务信息
	fileId	string	否	文件ID
	uploadUrl	string	否	文件上传地址，链接有效期60分钟。

请求示例

POST https://openapi.esign.cn/v1/files/getUploadUrl

{
    "contentMd5":"eGMHwA4TWnbg6PYKMxreUQ==",
    "contentType":"application/octet-stream",
    "convert2Pdf":false,
    "fileName":"附件.zip",
    "fileSize":2542635
}

响应示例

{
    "code":0,
    "data":{
        "uploadUrl":"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=eyJjYWxsYmFja1VybCI6Imh0dHA6Ly80Ny45OS4yMjQuMjM1OjgwODAvZmlsZS1zeXN0ZW0vY2FsbGJhY2svYWxpb3NzIiwiY2FsbGJhY2tCb2R5IjogIntcIm1pbWVUeXBlXCI6JHttaW1lVHlwZX0sXCJzaXplXCI6ICR7c2l6ZX0sXCJidWNrZXRcIjogJHtidWNrZXR9LFwib2JqZWN0XCI6ICR7b2JqZWN0fSxcImV0YWdcIjogJHtldGFnfSxcImZpbGVfa2V5XCI6JHt4OmZpbGVfa2V5fX0iLCJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL2pzb24ifQ%3D%3D%0A&security-token=CAIS%2BAF1q6Ft5B2yfSjIr4ngLY/Q3px15I/TSUnI0k0XP9VeibHtqTz2IHtKdXRvBu8Xs/4wnmxX7f4YlqB6T55OSAmcNZEod3TTArDkMeT7oMWQweEurv/MQBqyaXPS2MvVfJ%2BOLrf0ceusbFbpjzJ6xaCAGxypQ12iN%2B/m6/Ngdc9FHHPPD1x8CcxROxFppeIDKHLVLozNCBPxhXfKB0ca0WgVy0EHsPnvm5DNs0uH1AKjkbRM9r6ceMb0M5NeW75kSMqw0eBMca7M7TVd8RAi9t0t1/IVpGiY4YDAWQYLv0rda7DOltFiMkpla7MmXqlft%2BhzcgeQY0pc/RqAAa5BvYa8R6jX7v50o5iWdTJceZ0qwFqoAqO6uWZSPyqJHem/FntqEkDjdVHbDlGxhLECwZhV03g2YYUPV8MUyukXQa3H3Ixai3Dx84NaTff63mHyJvpmMTUYiARXOpf8U5CCmifHTOWcW6uEdV8o3QIjKLSwb%2Bfd0vR%2B3X37LMPb",
        "fileId":"c64665aa4f1c45679e65b6fae33cd773"
    },
    "message":"成功"
}

步骤2 文件流上传

功能描述

通过已获取到的 uploadUrl（文件上传地址）使用 PUT 请求方法把文件流（二进制字节流）上传到e签宝服务端，文件流（二进制字节流）上传完毕后才可以在后续成功发起签署流程。

如果文件流上传时出现报错，请参考文件上传常见报错及解决方法尝试解决。

上传地址

步骤1 获取文件上传地址中所获取到的 uploadUrl。

注意：

文件流上传成功仅代表文件上传到OSS服务，OSS服务将异步通知e签宝变更文件状态。受网络等各类因素影响，异步通知可能存在一定时差，建议开发者先调用【查询文件上传状态】接口查询文件当前状态，如果文件状态是2或5时，再发起签署流程。

上传方式

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": "成功"
}

支持的文件格式列表

文件扩展名	文件扩展名说明	支持情况
.pdf	属于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格式时耗时较久，具体耗时与实际文件大小有关。