部分微信支付境外业务指定商户需要上传文件资料,可使用本API来提交资料,获取其他业务API所需的FileID值。
1. 接口说明
请求URL:https://apihk.mch.weixin.qq.com/v3/global/merchant-storage/file/upload
请求主体类型:multipart/form-data
2. 请求参数
|
文件信息 | file | object | 是 | Body 将文件进行二进制转换,得到的二进制内容,在请求body中上传此二进制内容。文件支持PDF、JPG、BMP、PNG格式,文件大小不能超过5M。 |
 | 文件信息 | | |
文件名 | filename | string | 否 | 由表单上传的文件部分的文件名 | 文件类型 | content_type | string | 否 | 表示上传文件的 Content-Type | 文件内容 | content | string | 否 | 一个二进制串表示上传文件的整体内容 |
|
|
文件元信息 | meta | object | 是 | Body 文件元信息,使用json表示,包含两个对象:filename、digest |
 | 文件元信息 | | |
文件名称 | filename | string[1, 256] | 是 | 商户上传文件的名称,商户自定义,必须以PDF、JPG、BMP、PNG为后缀。 示例值:verify.pdf | 文件摘要 | digest | string[64, 64] | 是 | 文件摘要,即对上传文件的二进制内容进行sha256计算得到的值。 示例值:ff3f4036a1164d1ddbad5b3edf9022addb3e1961a54a922708a6c1ffc49e5489 |
|
|
3. 各语言请求示例
4. 返回参数
|
文件标识ID | file_id | string[16, 64] | 是 | 微信返回的文件标识ID 示例值:b6a17e2a-1dc4-4376-8630-e73d06490c0d |
返回示例
正常示例

1{
2 "file_id": "b6a17e2a-1dc4-4376-8630-e73d06490c0d"
3}
5. 请求步骤
5.1. 创建一个POST方法请求
HTTP

1POST https://apihk.mch.weixin.qq.com/v3/global/merchant-storage/file/upload HTTP/1.1
5.2.将文件的数据添加到请求主体
5.2.1 文件信息file参数的获取方式说明:
将文件进行二进制转换,得到的二进制内容, 放在请求http的body中。
5.2.2 文件元信息meta参数的获取方式说明:
文件元信息,使用json表示,包含两个对象:filename、digest。
● filename参数获取方式说明:
商户上传文件的名称,商户自定义,必须以PDF、JPG、BMP、PNG为后缀。
● digest参数获取方式说明:
文件摘要,即对上传文件的二进制内容进行sha256计算得到的值。
5.2.3 签名计算说明:签名生成
参与签名计算的请求主体为meta的json串:
{"filename": "file1.pdf", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"}
Example of a string to be signed:

1POST
2/v3/global/merchant-storage/file/upload
31566987169 // 时间戳
412ced2db6f0193dda91ba86224ea1cd8 // 随机数
5{"filename": "file1.pdf", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"}
5.3.添加HTTP头:

1Content-Type:multipart/form-data.设置为要上载的对象的MIME媒体类型。
2Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900231671",
3nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",timestamp="1567067659",
4serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
5signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7SFR+BjDZh6
689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPNQ7dBLO7ux6MoSuQp69
7PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e7hwUbDwGln170ZXomoO1KpQSbw3f1u
8WUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M7aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
9
10Content-Type: multipart/form-data;boundary=boundary
5.4.添加body:

1// 以下为body的内容
2--boundary // boundary为商户自定义的一个字符串
3Content-Disposition: form-data; name="meta";
4Content-Type: application/json
5//此处必须有一个空行
6{"filename": "file1.pdf", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"}
7--boundary
8Content-Disposition: form-data; name="file"; filename="file1.pdf";
9Content-Type: application/pdf
10//此处必须有一个空行
11context123 //context123即为所要上传文件的二进制内容
12--boundary--
说明:请求包体每行结尾都需要包含\r\n(空行也需要)。
5.5.发送请求

1POST /v3/global/merchant-storage/file/upload HTTP/1.1
2Host: api.mch.weixin.qq.com
3Authorization: WECHATPAY2-SHA256-RSA2048
4mchid="1900231671",nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",
5timestamp="1567067659",
6serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
7signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7
8SFR+BjDZh689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPN
9Q7dBLO7ux6MoSuQp69PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e
107hwUbDwGln170ZXomoO1KpQSbw3f1uWUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M
117aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
12Content-Type: multipart/form-data;boundary=boundary
13
14--boundary
15Content-Disposition: form-data; name="meta";
16Content-Type: application/json
17
18{"filename": "file1.pdf", "sha256": "hjkahkjsjkfsjk78687dhjahdajhk"}
19--boundary
20Content-Disposition: form-data; name="file"; filename="file1.pdf";
21Content-Type: application/pdf
22
23context123
24--boundary--
6. 错误码
|
400 | INVALID_REQUEST | 上传文件的文件大小不能超过5M,请检查所传字段(content)的大小 | 请更换文件或者对文件进行压缩后,重新调用 |
400 | INVALID_REQUEST | 上传文件的内容经过sha256加密算法计算后的值和所传字段(digest)的值不一致,请检查所传字段(digest)的计算方式 | 请参考指引,检查所传字段(digest)的计算方式 |
400 | INVALID_REQUEST | 上传文件的文件类型暂时不支持 | 请检查所传字段(content_type)是否在pdf, jpg, bmp, png中 |