部分微信支付业务指定商户需要使用图片上传 API来上报图片信息,从而获得必传参数的值:图片MediaID 。
1. 接口说明
请求URL:https://apihk.mch.weixin.qq.com/v3/merchant/media/upload
请求主体类型:multipart/form-data
2. 请求参数
|
图片文件 | file | object | 是 | Body 将媒体图片进行二进制转换,得到的媒体图片二进制内容,在请求body中上传此二进制内容。媒体图片只支持JPG、BMP、PNG格式,文件大小不能超过2M。 示例值:pic1 |
媒体文件元信息 | meta | object | 是 | Body 媒体文件元信息,使用json表示,包含两个对象:filename、sha256。 |
 | 媒体文件元信息 | | |
文件名称 | filename | string[1, 128] | 是 | 商户上传的媒体图片的名称,商户自定义,必须以JPG、BMP、PNG为后缀。 示例值:ilea.jpg | 文件摘要 | sha256 | string[1, 64] | 是 | 图片文件的文件摘要,即对图片文件的二进制内容进行sha256计算得到的值。 示例值:ff3f4036a1164d1ddbad5b3edf9022addb3e1961a54a922708a6c1ffc49e5489 |
|
|
3. 各语言请求示例
JAVA

1String filePath = "/your/home/hellokitty.png";
2URI uri = new URI("https://apihk.mch.weixin.qq.com/v3/merchant/media/upload");
3File file = new File(filePath);
4
5try (FileInputStream ins1 = new FileInputStream(file)) {
6 String sha256 = DigestUtils.sha256Hex(ins1);
7 try (InputStream ins2 = new FileInputStream(file)) {
8 HttpPost request = new WechatPayUploadHttpPost.Builder(uri)
9 .withImage(file.getName(), sha256, ins2)
10 .build();
11 CloseableHttpResponse response1 = httpClient.execute(request);
12 }
13}
PHP

1
2use WechatPay\GuzzleMiddleware\Util\MediaUtil;
3
4$media = new MediaUtil('/your/file/path/with.extension');
5
6
7try {
8 $resp = $client->request('POST', 'https://apihk.mch.weixin.qq.com/v3/[merchant/media/video_upload|marketing/favor/media/image-upload]', [
9 'body' => $media->getStream(),
10 'headers' => [
11 'Accept' => 'application/json',
12 'content-type' => $media->getContentType(),
13 ]
14 ]);
15
16 $resp = $client->post('merchant/media/upload', [
17 'body' => $media->getStream(),
18 'headers' => [
19 'Accept' => 'application/json',
20 'content-type' => $media->getContentType(),
21 ]
22 ]);
23 echo $resp->getStatusCode().' '.$resp->getReasonPhrase()."\n";
24 echo $resp->getBody()."\n";
25} catch (Exception $e) {
26 echo $e->getMessage()."\n";
27 if ($e->hasResponse()) {
28 echo $e->getResponse()->getStatusCode().' '.$e->getResponse()->getReasonPhrase()."\n";
29 echo $e->getResponse()->getBody();
30 }
31 return;
32}
JAVA详细请求示例详见:wechatpay-apache-httpclient
PHP详细请求示例详见:wechatpay-guzzle-middleware
4. 返回参数
|
媒体文件标识 Id | media_id | string[1, 512] | 是 | 微信返回的媒体文件标识Id。 示例值:b6a17e2a-1dc4-4376-8630-e73d06490c0d |
返回示例
正常示例

1{
2"media_id": "H1ihR9JUtVj-J7CJqBUY5ZOrG_Je75H-rKhTG7FUmg9sxNTbRN54dFiUHnhgrBQ6EKeHoGcHTJMHn5TAuLVjHUQDBInSWXcIHYXOeRa2OHA"
3}
5. 请求步骤
5.1. 创建一个POST方法请求
HTTP

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

1POST
2/v3/merchant/media/upload
31566987169 //时间戳
412ced2db6f0193dda91ba86224ea1cd8 //随机数
5{"filename":" filea.jpg ","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=="
9Content-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": "filea.jpg", "sha256": " hjkahkjsjkfsjk78687dhjahdajhk " }
7--boundary
8Content-Disposition: form-data; name="file"; filename="filea.jpg";
9Content-Type: image/jpg
10//此处必须有一个空行
11pic1 //pic1即为媒体图片的二进制内容
12--boundary--
说明:请求包体每行结尾都需要包含\r\n(空行也需要)。
5.5.发送请求

1POST /v3/merchant/media/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": "filea.jpg", "sha256": " hjkahkjsjkfsjk78687dhjahdajhk " }
19--boundary
20Content-Disposition: form-data; name="file"; filename="filea.jpg";
21Content-Type: image/jpg
22
23pic1
24--boundary--
6. 错误码
|
500 | SYSTEMERROR | 系统错误 | 系统异常,请使用相同参数稍后重新调用 |
SYSTEMERROR | 文件系统错误,请稍后重试 | 文件系统异常,请使用相同参数稍后重新调用 |
400 | PARAM_ERROR | 图片文件名称不正确,请检查后重新提交 | 图片文件名称不正确,只支持jpg,jpeg,png,bmp,请使用正确图片文件重新调用 |
PARAM_ERROR | 文件二进制内容不是图片,请检查后重新提交 | 上传文件二进制内容头部不正确,只支持jpg,jpeg,png,bmp,请使用正确图片文件重新调用 |
PARAM_ERROR | 图片sha256值有误,请检查后重新提交 | 图片sha256值计算有误,请检查算法,重新计算后提交 |
PARAM_ERROR | 文件大小不能超过2M,请检查后重新提交 | 商户更换文件或者对图片进行压缩后,重新调用 |
PARAM_ERROR | 文件为空,请检查后重新提交 | 商户更换文件后,重新调用 |
429 | FREQUENCY_LIMIT_EXCEED | 操作过快,请稍后重试 | 请商户降低每秒调用频率 |
FREQUENCY_LIMIT_EXCEED | 当天上传文件数已达上限 | 请商户降低每天调用频率 |
403 | NO_AUTH | 商户权限异常 | 请确认是否已经开通相关权限 |