<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 增值税发票识别

> 增值税发票 OCR 识别，支持增值税专用发票、普通发票、电子普票，输出 22+ 个结构化字段。

• 双输入模式：
  - input_type=url：传入公网可访问的图片 URL（http/https）
  - input_type=base64：传入 base64 编码字符串（≤6MB，自动剥离 data:image/...;base64, 前缀）

• 完整识别字段：
  - 发票基本：发票名称、代码、号码、开票日期、校验码、机器编号
  - 金额：价税合计、税额、不含税金额、大写金额
  - 购销方：名称、纳税人识别号、地址电话、开户行账号
  - 经办人：收款人、复核人、开票人
  - 商品明细：items 数组，含品名/规格/数量/单价/金额/税率/税额
  - 备注与盖章信息

• OCR 结果缓存 1 小时（同图同结果），减少重复调用消耗。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `invoice` |
| 接口名称 | 增值税发票识别 |
| 接口地址 | `https://v1.apizero.cn/api/invoice` |
| 请求方法 | `POST` |
| 分类 | dev |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 2 req/s |
| 每日免费额度 | 30 次（已认证用户） |
| 匿名每日额度 | 5 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 5 次、QPS 1；登录用户每日 30 次、QPS 2（全部免费）。OCR 结果缓存 1 小时，相同图片只实际调用上游一次。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `input_type` | `string` | 是 | 输入类型：url=图片URL / base64=图片base64编码 | `url` |
| `input_data` | `string` | 是 | 发票图片数据。input_type=url 时为 http/https 完整 URL；input_type=base64 时为 base64 字符串（最大 6MB，可选 data:image/jpeg;base64, 前缀） | `https://example.com/invoice.jpg` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 5 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |
| `Content-Type` | `string` | 是 | POST 请求体类型，固定 application/x-www-form-urlencoded；如使用 base64 模式建议 POST | `application/x-www-form-urlencoded` |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/invoice" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_type": "url",
  "input_data": "https://example.com/invoice.jpg"
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `invoice_name` | `string` | 发票名称（如「增值税电子普通发票」） | — |
| `invoice_code` | `string` | 发票代码（10-12 位数字） | — |
| `invoice_no` | `string` | 发票号码（8-20 位数字） | — |
| `invoice_date` | `string` | 开票日期，格式 YYYY-MM-DD 或 YYYY年MM月DD日 | — |
| `check_code` | `string` | 校验码（20 位数字，部分电子发票无） | — |
| `machine_num` | `string` | 机器编号（12 位） | — |
| `total_price` | `string` | 不含税金额（保留为字符串避免浮点精度问题） | — |
| `total_tax` | `string` | 税额合计 | — |
| `total_price_and_tax` | `string` | 价税合计（小写） | — |
| `big_total_price_and_tax` | `string` | 价税合计（大写中文，如「壹佰元整」） | — |
| `buyer` | `object` | 购方信息对象 | — |
| `buyer.name` | `string` | 购方名称 | — |
| `buyer.taxpayer_no` | `string` | 购方纳税人识别号 | — |
| `buyer.address_phone` | `string` | 购方地址电话 | — |
| `buyer.account` | `string` | 购方开户行及账号 | — |
| `seller` | `object` | 销方信息对象（结构同 buyer） | — |
| `payee` | `string` | 收款人 | — |
| `reviewer` | `string` | 复核人 | — |
| `drawer` | `string` | 开票人 | — |
| `remarks` | `string` | 备注（含税控盘信息、说明等） | — |
| `items` | `array` | 商品明细数组，每项含名称/规格/数量/单价/金额/税率/税额等字段（具体字段以上游识别结果为准） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "invoice_name": "增值税电子普通发票",
        "invoice_code": "011002000311",
        "invoice_no": "12345678",
        "invoice_date": "2024-08-15",
        "check_code": "12345 67890 12345 67890",
        "machine_num": "499099111111",
        "total_price": "94.34",
        "total_tax": "5.66",
        "total_price_and_tax": "100.00",
        "big_total_price_and_tax": "壹佰圆整",
        "buyer": {
            "name": "某某科技有限公司",
            "taxpayer_no": "91110000XXXXXXXXXX",
            "address_phone": "北京市XX区XX路XX号 010-12345678",
            "account": "中国银行 6217001234567890"
        },
        "seller": {
            "name": "某某商贸有限公司",
            "taxpayer_no": "91310000YYYYYYYYYY",
            "address_phone": "上海市XX区XX路XX号 021-87654321",
            "account": "工商银行 6222001234567890"
        },
        "payee": "张三",
        "reviewer": "李四",
        "drawer": "王五",
        "remarks": "",
        "items": [
            {
                "name": "*技术服务*软件开发服务",
                "specification": "",
                "unit": "",
                "quantity": "",
                "unit_price": "",
                "amount": "94.34",
                "tax_rate": "6%",
                "tax": "5.66"
            }
        ]
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：input_type/input_data 缺失或非法 / URL 格式错 / base64 含非法字符 / base64 超过 6MB |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游 HTTP 失败 |
| `5021` | `—` | 识别失败：图片模糊 / 非发票 / URL 不可达 / 上游服务异常 |

## 9. 变更日志

- **1.0.0** (2026-05-06)
  - 首次上线，对接 alapi.cn /api/ocr/vat-invoice OCR 服务
  - 双输入模式：URL 直接抓取 / base64 直传
  - base64 模式自动剥离 data:image/...;base64, 前缀
  - base64 上限 6MB（约对应 4.5MB 原图），防止 OOM
  - URL 模式严格 http/https 校验，防止 SSRF / 内网探测
  - OCR 结果缓存 1h（按 input_data sha256 哈希），相同图片不重复调用付费上游
  - token 异常（10001/10002）转为通用 5021，避免暴露内部配置
  - 金额字段保持字符串类型，避免浮点精度问题

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/invoice`

Source: `https://apizero.cn/aidocs/invoice/raw.md`
Last updated: 2026-05-11T16:16:07+08:00