---
url: "https://pay.weixin.qq.com/doc/v3/partner/4015792580.md"
title: "上传电子发票文件"
doc_id: 4015792580
---

>更新时间：2025.12.03

调用[【将电子发票插入微信用户卡包】](https://pay.weixin.qq.com/doc/v3/partner/4015792579.md)接口之前，需要先调用本接口上传电子发票文件，获取文件ID。上传的发票文件会在三天后过期，因此上传后请尽快调用[【将电子发票插入微信用户卡包】](https://pay.weixin.qq.com/doc/v3/partner/4015792579.md)接口执行插入微信用户卡包的操作。




## 接口说明

支持商户：【普通服务商】

请求方式：【POST】 `/v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file`

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引[点击查看](https://pay.weixin.qq.com/doc/v3/merchant/4012075113.md)

## 请求参数

### Header 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| Authorization | string | true | 请参考 [签名认证](https://pay.weixin.qq.com/doc/v3/merchant/4012365342.md#%E8%AF%B7%E6%B1%82%E6%8E%A5%E5%8F%A3%E5%90%8E%E7%AB%AF%E7%AD%BE%E5%90%8D) 生成认证信息 |
| Accept | string | true | 请设置为 `application/json` |
| Content-Type | string | true | 请设置为 `multipart/form-data` |
### Form 参数
| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| file | file | true | 【电子发票文件】 将电子发票文件转换为二进制数据流，在请求body中通过表单提交的方式上传此二进制内容。电子发票文件只支持PDF格式，文件大小不能超过2M |
| meta | object | true | 【电子发票文件元信息】 电子发票文件元信息 |
| meta.sub_mchid | string(32) | true | 【子商户号】 微信支付分配的子商户号，具体请参考 [服务商模式开发必要参数说明](https://pay.weixin.qq.com/doc/v3/partner/4013080340.md) |
| meta.file_type | string | true | 【文件类型】 发票文件的类型<br>可选取值<br><ul><li>`PDF`:  PDF文件类型</li></ul> |
| meta.digest_alogrithm | string | true | 【文件摘要算法】 文件摘要算法<br>可选取值<br><ul><li>`SM3`:  国密SM3摘要算法</li></ul> |
| meta.digest | string(64) | true | 【文件摘要】 根据文件摘要算法对电子发票文件二进制内容计算出的文件摘要，结果为16进制编码 |
## 应答参数

200 OK

| 参数名 | 类型 | 必填 | 描述 |
| --- |  --- | --- | --- |
| fapiao_media_id | string(128) | true | 【电子发票文件ID】 上传的电子发票文件对应的ID，三天内有效，用于【将电子发票插入微信用户卡包】接口 |
## 错误码

### 公共错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | PARAM\_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID\_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 [接口规则](https://pay.weixin.qq.com/doc/v3/merchant/4012081709.md) |
| 401 | SIGN\_ERROR | 验证不通过 | 请参阅 [签名常见问题](https://pay.weixin.qq.com/doc/v3/merchant/4012072670.md) |
| 500 | SYSTEM\_ERROR | 系统异常，请稍后重试 | 请稍后重试 |

### 业务错误码

| 状态码 | 错误码 | 描述 | 解决方案 |
| --- | --- | --- | --- |
| 400 | PARAM\_ERROR | 电子发票文件超过尺寸限制 | 请上传2M以内的电子发票文件 |
| 400 | INVALID\_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 请使用正确的参数重新调用 |
| 400 | INVALID\_REQUEST | 电子发票文件与元信息中的摘要不匹配 | 请使用匹配的电子发票文件和摘要 |
| 403 | NO\_AUTH | 商户无权限 | 请检查是否已经开通电子发票产品相关功能权限，并检查子商户是否接受了服务商的邀请 |
| 429 | FREQUENCY\_LIMITED | 频率超限 | 请降低请求接口频率 |

请求示例

- [curl 示例](https://pay.weixin.qq.com/doc/v3/partner/4015792580-curl.md)
- [Java 示例](https://pay.weixin.qq.com/doc/v3/partner/4015792580-java.md)
- [Go 示例](https://pay.weixin.qq.com/doc/v3/partner/4015792580-go.md)


应答示例

> 200 OK

```
{
  "fapiao_media_id" : "ASNFZ4mrze/+3LqYdlQyEA=="
}

```### 文件上传步骤

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

例如： POST https://api.mch.weixin.qq.com/new-tax-control-fapiao/fapiao-applications/upload-fapiao-fileHTTP/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 签名计算说明：

[签名生成](https://pay.weixin.qq.com/doc/v3/partner/4012365870.md#%E8%AF%B7%E6%B1%82%E6%8E%A5%E5%8F%A3%E5%90%8E%E7%AB%AF%E7%AD%BE%E5%90%8D)

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

```
{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_alogrithm": "SM3" }
```

待签名串示例：

```
POST
/v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file
1566987169           //时间戳
12ced2db6f0193dda91ba86224ea1cd8   //随机数
{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_alogrithm": "SM3" }
```

添加HTTP头：

```
Content-Type：multipart/form-data.设置为要上载的对象的MIME媒体类型。
Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900231671",
nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",timestamp="1567067659",
serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7SFR+BjDZh6
89hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPNQ7dBLO7ux6MoSuQp69
PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e7hwUbDwGln170ZXomoO1KpQSbw3f1u
WUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M7aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
Content-Type: multipart/form-data;boundary=boundary
```

添加body：

```
// 以下为body的内容
--boundary  // boundary为商户自定义的一个字符串
Content-Disposition: form-data; name="meta";
Content-Type: application/json
//此处必须有一个空行
{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_alogrithm": "SM3" }
--boundary
Content-Disposition: form-data; name="file";
Content-Type: pdf/plain
//此处必须有一个空行
--boundary--
```

说明：请求包体每行结尾都需要包含\\r\\n（空行也需要）。

发送请求：

```
POST /v3/new-tax-control-fapiao/fapiao-applications/upload-fapiao-file HTTP/1.1
Host: api.mch.weixin.qq.com
Authorization: WECHATPAY2-SHA256-RSA2048
mchid="1900231671",nonce_str="PCHK6HSOEDTACETP6P3AL7DWPHTBKIAT",
timestamp="1567067659",
serial_no="1FB89742D19F2BD30B69948D16DECA0FCB4481EB",
signature="PB6M7+3JL7TSCl5zqD1sdWVypOIEQsD4dgOU+vPiVM6GMRo2qYSWKf8u46i9ZJFhyZTBdZ7
SFR+BjDZh689hFgN8LZL+QWTvq3cse/FEUFYyOLN7L/2IZX4GA4cWInuJ2MpOhZRMpm+emrcn42gTMKAPN
Q7dBLO7ux6MoSuQp69PW+p1ogmkER68exTVUXYqA5P3vITlWNr++RDy2+ExvB7qVISOKW0vBkxUxN9e
7hwUbDwGln170ZXomoO1KpQSbw3f1uWUCx/IlWJhJIun7rUMtVT+kfijNUqcILtSfE4hWKKVaZn9j5CX8M
7aKbbDOFy3SvbSJ3WQgRnRbgog5w=="
Content-Type: multipart/form-data;boundary=boundary

--boundary
Content-Disposition: form-data; name="meta";
Content-Type: application/json

{ "file_type": "PDF","digest": "addca90a6a290b9642dbaccffdf01e8c22aa348940b2e96754169ba08c19e5db", "digest_alogrithm": "SM3" }
--boundary
Content-Disposition: form-data; name="file";
Content-Type: pdf/plain

--boundary--
```
