上传电子发票文件
更新时间：2025.09.26||
调用【将电子发票插入微信用户卡包】接口之前，需要先调用本接口上传电子发票文件，获取文件ID。上传的发票文件会在三天后过期，因此上传后请尽快调用【将电子发票插入微信用户卡包】接口执行插入微信用户卡包的操作。
接口说明
请求方式：【POST】/v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file
请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ，指引点击查看
请求参数
折叠全部参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为multipart/form-data
Form 表单
file 必填 file
电子发票文件二进制数据流，只支持PDF和OFD格式，文件大小不能超过2M。需要在请求body中通过表单提交的方式上传此二进制内容。
meta 必填 object
电子发票文件元信息
| 属性 |
| file_type 必填 string 【文件类型】发票文件的类型 可选取值：：
digest_alogrithm 必填 string 【文件摘要算法】文件摘要算法 可选取值：：
digest 必填 string(64) 【文件摘要】根据文件摘要算法对电子发票文件二进制内容计算出的文件摘要，结果为16进制编码 |
POST
1curl -X POST \
2 https://api.mch.weixin.qq.com/v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file \
3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4 -H "Accept: application/json" \
5 -H "Content-Type: multipart/form-data" \
6 -F file=@"/path/to/file" \
7 -F meta="{
8 "file_type" : "PDF",
9 "digest_alogrithm" : "SM3",
10 "digest" : "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db"
11 }"
1POST
2/v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file
31566987169 //时间戳
412ced2db6f0193dda91ba86224ea1cd8 //随机数
5{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_alogrithm": "SM3" }
添加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
添加body
1// 以下为body的内容
2--boundary // boundary为商户自定义的一个字符串
3Content-Disposition: form-data; name="meta";
4Content-Type: application/json
5//此处必须有一个空行
6{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_alogrithm": "SM3" }
7--boundary
8Content-Disposition: form-data; name="file";
9Content-Type: pdf/plain
10//此处必须有一个空行
11--boundary--
说明：请求包体每行结尾都需要包含\r\n（空行也需要）。
整体结构
1POST /v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file 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--boundary
14Content-Disposition: form-data; name="meta";
15Content-Type: application/json
16{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_alogrithm": "SM3" }
17--boundary
18Content-Disposition: form-data; name="file";
19Content-Type: pdf/plain
20--boundary--应答参数
fapiao_media_id 必填 string(128)
应答示例
200 OK
1{
2 "fapiao_media_id" : "ASNFZ4mrze/+3LqYdlQyEA=="
3}文件上传步骤
1.创建一个POST的方法请求/upload URL:
例如： POST https://api.mch.weixin.qq.com/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file HTTP/1.1
2.将文件的数据添加到请求主体:
2.1 文本文件file参数的获取方式说明：
文本文件二进制内容，放在请求HTTP的body中。
2.2 电子发票文件元信息meta参数的获取方式说明：
电子发票文件元信息，使用json表示，包含四个对象：sub_mchid、file_type、digest_alogrithm、digest。
sub_mchid参数获取方式说明： 微信支付分配的子商户号，服务商模式下必传
file_type参数获取方式说明： 发票文件的类型为PDF - PDF文件类型，PDF文件类型
digest_alogrithm参数获取方式说明： 文件摘要算法，SM3 - 国密SM3算法，国密SM3摘要算法
digest参数获取方式说明： 根据文件摘要算法对电子发票文件二进制内容计算出的文件摘要，结果为16进制编码
2.3 签名计算说明：
签名生成
参与签名计算的请求主体为meta的json串：
1{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_alogrithm": "SM3" }错误码
公共错误码
|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常，请稍后重试 | 请稍后重试 |
业务错误码
|
429 | FREQUENCY_LIMITED | 频率超限 | 请降低请求接口频率 |
400 | PARAM_ERROR | 电子发票文件超过尺寸限制 | 请上传2M以内的电子发票文件 |
400 | INVALID_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 请使用正确的参数重新调用 |
400 | INVALID_REQUEST | 电子发票文件与元信息中的摘要不匹配 | 请使用匹配的电子发票文件和摘要 |
401 | SIGN_ERROR | 签名错误或签名信息不完整 | 请检查签名参数和方法是否都符合签名算法要求 |
403 | NO_AUTH | 商户无权限 | 请检查是否已经开通电子发票产品相关功能权限，若是服务商模式，还需确认子商户是否接受了服务商的邀请 |
