上传电子发票文件

更新时间：2024.12.10

调用【将电子发票插入微信用户卡包】接口之前，需要先调用本接口上传电子发票文件，获取文件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

【文件类型】发票文件的类型

可选取值：：

PDF: PDF文件类型

digest_alogrithm 　必填 string

【文件摘要算法】文件摘要算法

可选取值：：

SM3: 国密SM3摘要算法

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--

应答参数

200 OK

fapiao_media_id 　必填 string(128)

【电子发票文件ID】上传的电子发票文件对应的ID，该文件ID三天内有效。用于【将电子发票插入微信用户卡包】接口。

应答示例

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	商户无权限	请检查是否已经开通电子发票产品相关功能权限，若是服务商模式，还需确认子商户是否接受了服务商的邀请

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服