上传电子发票文件

更新时间：2024.08.14

调用【将电子发票插入微信用户卡包】接口之前，需要先调用本接口上传电子发票文件，获取文件ID。上传的发票文件会在三天后过期，因此上传后请尽快调用【将电子发票插入微信用户卡包】接口执行插入微信用户卡包的操作。

# 接口说明

支持商户：

【普通商户】

请求方式：

【POST】/v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file

请求域名：

【主域名】

https://api.mch.weixin.qq.com

使用该域名将访问就近的接入点

【备域名】

https://api2.mch.weixin.qq.com

使用该域名将访问异地的接入点，指引点击查看

# 字段说明

# 请求参数

Body 包体参数

file 必填 object

电子发票文件二进制数据流，只支持PDF和OFD格式，文件大小不能超过2M。需要在请求body中通过表单提交的方式上传此二进制内容。

meta 必填 object

电子发票文件元信息

属性

# 应答字段

fapiao_media_id 必填 string(128)

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

# 文件上传步骤

1.创建一个POST的方法请求/upload URI:

例如： POST https://api.mch.weixin.qq.com/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file (opens new window) HTTP/1.1

2.将文件的数据添加到请求主体:

2.1 文本文件file参数的获取方式说明：

文本文件二进制内容，放在请求HTTP的body中。

2.2 电子发票文件元信息meta参数的获取方式说明：
电子发票文件元信息，使用json表示，包含四个对象：sub_mchid、file_type、digest_algorithm、digest。

sub_mchid参数获取方式说明：微信支付分配的子商户号，服务商模式下必传
file_type参数获取方式说明：发票文件的类型为PDF - PDF文件类型，PDF文件类型
digest_algorithm参数获取方式说明：文件摘要算法，SM3 - 国密SM3算法，国密SM3摘要算法
digest参数获取方式说明：根据文件摘要算法对电子发票文件二进制内容计算出的文件摘要，结果为16进制编码

2.3 签名计算说明：

签名生成

参与签名计算的请求主体为meta的json串：

1{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_algorithm": "SM3" }

# 请求示例

1{   
2 "file": {          
3 },   
4 "meta": {      
5   "digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db",      
6   "digest_algorithm": "SM3",      
7   "file_type": "PDF"
8  }  
9}

# 应答示例

1{
2  "fapiao_media_id": "ASNFZ4mrze/+3LqYdlQyEA=="
3}

待签名串示例：

1POST
2/v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file
31566987169           //时间戳
412ced2db6f0193dda91ba86224ea1cd8   //随机数
5{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_algorithm": "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_algorithm": "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
14--boundary  
15Content-Disposition: form-data; name="meta";
16Content-Type: application/json
17
18{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_algorithm": "SM3" }
19--boundary
20Content-Disposition: form-data; name="file"; 
21Content-Type: pdf/plain
22
23--boundary--

# 错误码

# 公共错误码

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

文档是否有帮助

服务商文档

电子发票参考文档

更多支持

开发者社区微信开放平台微信公众平台腾讯客服