上传文件分块
更新时间:2025.09.29上传单个分块的文件数据,需指定上传ID和分块编号。
注:上传任务需归属于本请求的同一品牌商家,否则将无法通过权限校验。
接口说明
支持商户:【品牌商户】
请求方式:【PUT】/brand/marketing/user-package/uploads/{upload_id}/{part_number}
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为application/json
Wechatpay-Serial 必填 string
【微信支付公钥ID】 请传入brand_id对应的微信支付公钥ID,接口将会校验两者的关联关系,参考微信支付公钥产品简介及使用说明获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥: 1、接收到接口的返回内容,需要使用微信支付公钥进行验签; 2、调用含有敏感信息参数(如姓名、身份证号码)的接口时,需要使用微信支付公钥加密敏感信息后再传输参数,加密指引请参考微信支付公钥加密敏感信息指引。
path 路径参数
upload_id 必填 string(128)
【上传ID】 上传ID,调用初始化上传时返回的上传ID
part_number 必填 integer
【分块编号】 分块编号
body 包体参数
file 必填 file
【文件数据】 文件数据,人群号码包文件的二进制内容。
注:文件大小不能超过20MB,建议单个文件的行数不超过500,000。
请严格按初始化上传接口返回的文件分块大小和文件分块数量进行分块上传,最后一块文件数据大小可以小于文件分块大小。
file_meta 必填 object
【文件元信息】 当前上传的文件元信息
属性 | |
filename 必填 string(128) 【文件名】 当前上传的文件名。可包含英文字母,数字,_,.,-等内容,不允许出现其他不合法符号。 digest 必填 string(64) 【文件摘要】 当前上传的文件摘要,二进制内容进行sha256计算得到的值 |
请求示例
PUT
1curl -X PUT \ 2 https://api.mch.weixin.qq.com/brand/marketing/user-package/uploads/17587186700323d11ac17d8d3d4c8c4e5a250c3e804977e89af6a05ffa93751d0ec0179ca8/1 \ 3 -H "Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id=\"XXXX\",..." \ 4 -H "Accept: application/json" \ 5 -H "Wechatpay-Serial: PUB_KEY_ID_XXXX" \ 6 -H "Content-Type: application/json" \ 7 -d '{ 8 "file" : "example_file", 9 "file_meta" : { 10 "filename" : "1_active_user.csv", 11 "digest" : "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db" 12 } 13 }' 14
需配合微信支付工具库 WXPayUtility 使用,请参考Java
1package com.java.demo; 2 3import com.java.utils.WXPayBrandUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/brand/4015826861 4 5import com.google.gson.annotations.SerializedName; 6import com.google.gson.annotations.Expose; 7import okhttp3.MediaType; 8import okhttp3.OkHttpClient; 9import okhttp3.Request; 10import okhttp3.RequestBody; 11import okhttp3.Response; 12 13import java.io.IOException; 14import java.io.UncheckedIOException; 15import java.security.PrivateKey; 16import java.security.PublicKey; 17import java.util.ArrayList; 18import java.util.HashMap; 19import java.util.List; 20import java.util.Map; 21 22/** 23 * 上传文件分块 24 */ 25public class UploadPart { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "PUT"; 28 private static String PATH = "/brand/marketing/user-package/uploads/{upload_id}/{part_number}"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/brand/4015415289 32 UploadPart client = new UploadPart( 33 "xxxxxxxx", // 品牌ID,是由微信支付系统生成并分配给每个品牌方的唯一标识符,品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 34 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 35 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 UploadPartRequest request = new UploadPartRequest(); 41 request.uploadId = "17587186700323d11ac17d8d3d4c8c4e5a250c3e804977e89af6a05ffa93751d0ec0179ca8"; 42 request.partNumber = 1L; 43 request.file = "file_bytes".getBytes(); 44 request.fileMeta = new FileMeta(); 45 request.fileMeta.filename = "1_active_user.csv"; 46 request.fileMeta.digest = "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db"; 47 try { 48 UploadPartResponse response = client.run(request); 49 // TODO: 请求成功,继续业务逻辑 50 System.out.println(response); 51 } catch (WXPayBrandUtility.ApiException e) { 52 // TODO: 请求失败,根据状态码执行不同的逻辑 53 e.printStackTrace(); 54 } 55 } 56 57 public UploadPartResponse run(UploadPartRequest request) { 58 String uri = PATH; 59 uri = uri.replace("{upload_id}", WXPayBrandUtility.urlEncode(request.uploadId)); 60 uri = uri.replace("{part_number}", WXPayBrandUtility.urlEncode(request.partNumber.toString())); 61 String reqBody = WXPayBrandUtility.toJson(request); 62 63 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 64 reqBuilder.addHeader("Accept", "application/json"); 65 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 66 reqBuilder.addHeader("Authorization", WXPayBrandUtility.buildAuthorization(brand_id, certificateSerialNo,privateKey, METHOD, uri, reqBody)); 67 reqBuilder.addHeader("Content-Type", "application/json"); 68 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 69 reqBuilder.method(METHOD, requestBody); 70 Request httpRequest = reqBuilder.build(); 71 72 // 发送HTTP请求 73 OkHttpClient client = new OkHttpClient.Builder().build(); 74 try (Response httpResponse = client.newCall(httpRequest).execute()) { 75 String respBody = WXPayBrandUtility.extractBody(httpResponse); 76 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 77 // 2XX 成功,验证应答签名 78 WXPayBrandUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 79 httpResponse.headers(), respBody); 80 81 // 从HTTP应答报文构建返回数据 82 return WXPayBrandUtility.fromJson(respBody, UploadPartResponse.class); 83 } else { 84 throw new WXPayBrandUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 85 } 86 } catch (IOException e) { 87 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 88 } 89 } 90 91 private final String brand_id; 92 private final String certificateSerialNo; 93 private final PrivateKey privateKey; 94 private final String wechatPayPublicKeyId; 95 private final PublicKey wechatPayPublicKey; 96 97 public UploadPart(String brand_id, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 98 this.brand_id = brand_id; 99 this.certificateSerialNo = certificateSerialNo; 100 this.privateKey = WXPayBrandUtility.loadPrivateKeyFromPath(privateKeyFilePath); 101 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 102 this.wechatPayPublicKey = WXPayBrandUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 103 } 104 105 public static class UploadPartRequest { 106 @SerializedName("upload_id") 107 @Expose(serialize = false) 108 public String uploadId; 109 110 @SerializedName("part_number") 111 @Expose(serialize = false) 112 public Long partNumber; 113 114 @SerializedName("file") 115 public byte[] file; 116 117 @SerializedName("file_meta") 118 public FileMeta fileMeta; 119 } 120 121 public static class UploadPartResponse { 122 @SerializedName("return_message") 123 public String returnMessage; 124 125 @SerializedName("part_number") 126 public Long partNumber; 127 } 128 129 public static class FileMeta { 130 @SerializedName("filename") 131 public String filename; 132 133 @SerializedName("digest") 134 public String digest; 135 } 136 137} 138
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "bytes" 5 "demo/wxpay_brand_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/brand/4015826866 6 "encoding/json" 7 "fmt" 8 "net/http" 9 "net/url" 10 "strings" 11) 12 13func main() { 14 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/brand/4015415289 15 config, err := wxpay_brand_utility.CreateBrandConfig( 16 "xxxxxxxx", // 品牌ID,是由微信支付系统生成并分配给每个品牌方的唯一标识符,品牌ID获取方式参考 https://pay.weixin.qq.com/doc/brand/4015415289 17 "1DDE55AD98Exxxxxxxxxx", // 品牌API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015407570 18 "/path/to/apiclient_key.pem", // 品牌API证书私钥文件路径,本地文件路径 19 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/brand/4015453439 20 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 21 ) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26 27 request := &UploadPartRequest{ 28 UploadId: wxpay_brand_utility.String("17587186700323d11ac17d8d3d4c8c4e5a250c3e804977e89af6a05ffa93751d0ec0179ca8"), 29 PartNumber: wxpay_brand_utility.Int64(1), 30 File: wxpay_brand_utility.Bytes([]byte("file data")), 31 FileMeta: &FileMeta{ 32 Filename: wxpay_brand_utility.String("1_active_user.csv"), 33 Digest: wxpay_brand_utility.String("addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db"), 34 }, 35 } 36 37 response, err := UploadPart(config, request) 38 if err != nil { 39 fmt.Printf("请求失败: %+v\n", err) 40 // TODO: 请求失败,根据状态码执行不同的处理 41 return 42 } 43 44 // TODO: 请求成功,继续业务逻辑 45 fmt.Printf("请求成功: %+v\n", response) 46} 47 48func UploadPart(config *wxpay_brand_utility.BrandConfig, request *UploadPartRequest) (response *UploadPartResponse, err error) { 49 const ( 50 host = "https://api.mch.weixin.qq.com" 51 method = "PUT" 52 path = "/brand/marketing/user-package/uploads/{upload_id}/{part_number}" 53 ) 54 55 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 56 if err != nil { 57 return nil, err 58 } 59 reqUrl.Path = strings.Replace(reqUrl.Path, "{upload_id}", url.PathEscape(*request.UploadId), -1) 60 reqUrl.Path = strings.Replace(reqUrl.Path, "{part_number}", url.PathEscape(fmt.Sprintf("%v", *request.PartNumber)), -1) 61 reqBody, err := json.Marshal(request) 62 if err != nil { 63 return nil, err 64 } 65 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 66 if err != nil { 67 return nil, err 68 } 69 httpRequest.Header.Set("Accept", "application/json") 70 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 71 httpRequest.Header.Set("Content-Type", "application/json") 72 authorization, err := wxpay_brand_utility.BuildAuthorization(config.BrandId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 73 if err != nil { 74 return nil, err 75 } 76 httpRequest.Header.Set("Authorization", authorization) 77 78 client := &http.Client{} 79 httpResponse, err := client.Do(httpRequest) 80 if err != nil { 81 return nil, err 82 } 83 respBody, err := wxpay_brand_utility.ExtractResponseBody(httpResponse) 84 if err != nil { 85 return nil, err 86 } 87 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 88 // 2XX 成功,验证应答签名 89 err = wxpay_brand_utility.ValidateResponse( 90 config.WechatPayPublicKeyId(), 91 config.WechatPayPublicKey(), 92 &httpResponse.Header, 93 respBody, 94 ) 95 if err != nil { 96 return nil, err 97 } 98 response := &UploadPartResponse{} 99 if err := json.Unmarshal(respBody, response); err != nil { 100 return nil, err 101 } 102 103 return response, nil 104 } else { 105 return nil, wxpay_brand_utility.NewApiException( 106 httpResponse.StatusCode, 107 httpResponse.Header, 108 respBody, 109 ) 110 } 111} 112 113type UploadPartRequest struct { 114 UploadId *string `json:"upload_id,omitempty"` 115 PartNumber *int64 `json:"part_number,omitempty"` 116 File *[]byte `json:"file,omitempty"` 117 FileMeta *FileMeta `json:"file_meta,omitempty"` 118} 119 120func (o *UploadPartRequest) MarshalJSON() ([]byte, error) { 121 type Alias UploadPartRequest 122 a := &struct { 123 UploadId *string `json:"upload_id,omitempty"` 124 PartNumber *int64 `json:"part_number,omitempty"` 125 *Alias 126 }{ 127 // 序列化时移除非 Body 字段 128 UploadId: nil, 129 PartNumber: nil, 130 Alias: (*Alias)(o), 131 } 132 return json.Marshal(a) 133} 134 135type UploadPartResponse struct { 136 ReturnMessage *string `json:"return_message,omitempty"` 137 PartNumber *int64 `json:"part_number,omitempty"` 138} 139 140type FileMeta struct { 141 Filename *string `json:"filename,omitempty"` 142 Digest *string `json:"digest,omitempty"` 143} 144
应答参数
200 OK
return_message 必填 string(128)
【返回信息】 返回信息,上传分块成功后,返回成功信息;上传分块失败后,返回失败提示信息。
part_number 必填 integer
【分块编号】 人群包分块文件的分块编号
应答示例
200 OK
1{ 2 "return_message" : "success", 3 "part_number" : 1 4} 5
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
400 | INVALID_REQUEST | 传入参数不符合业务规则 | 请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足 |
403 | NO_AUTH | 缺少业务相关权限 | 请确认具备人群包操作权限 |
404 | NOT_FOUND | 未找到 upload_id 对应的上传任务 | 请确认 upload_id 存在且属于当前品牌商家 |
429 | RATELIMIT_EXCEEDED | 请求超过接口频率限制 | 请稍后使用原参数重试 |