增值税发票识别

invoicePOST
POSThttps://v1.apizero.cn/api/invoice
获取 API Key工作台购买 / 调试

概述

增值税发票 OCR 识别，支持增值税专用发票、普通发票、电子普票，输出 22+ 个结构化字段。 • 双输入模式： - input_type=url：传入公网可访问的图片 URL（http/https） - input_type=base64：传入 base64 编码字符串（≤6MB，自动剥离 data:image/...;base64, 前缀） • 完整识别字段： - 发票基本：发票名称、代码、号码、开票日期、校验码、机器编号 - 金额：价税合计、税额、不含税金额、大写金额 - 购销方：名称、纳税人识别号、地址电话、开户行账号 - 经办人：收款人、复核人、开票人 - 商品明细：items 数组，含品名/规格/数量/单价/金额/税率/税额 - 备注与盖章信息 • OCR 结果缓存 1 小时（同图同结果），减少重复调用消耗。

调用约定

  • 网关 · https://v1.apizero.cn
  • 鉴权 · Authorization: Bearer <API Key>
  • 回包 · JSON {code, msg, data}。成功看 code === 0，不要只看 HTTP 200。
/aidocs/invoice/raw.md
打开 Markdown

鉴权

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

获取 API Key

请求头

Authorizationstring选填

推荐：Bearer <API Key>。兼容请求头 X-API-Key，以及 Query api_key / apikey / key（key 仅当值为 sk_live_/sk_test_/sk_stag_ 形态时生效）。匿名可不传，受每日免费额度限制。

Content-Typestring必填

POST 请求体类型，固定 application/x-www-form-urlencoded；如使用 base64 模式建议 POST

请求参数

POST · APPLICATION/JSON

input_typestring必填

输入类型：url=图片URL / base64=图片base64编码

例url

input_datastring必填

发票图片数据。input_type=url 时为 http/https 完整 URL；input_type=base64 时为 base64 字符串（最大 6MB，可选 data:image/jpeg;base64, 前缀）

例https://example.com/invoice.jpg

{
  "input_type": "url",
  "input_data": "https://example.com/invoice.jpg"
}

返回结果

顶层固定为 code / msg / data。下表一般是 data 内字段。 code · msg · data · tips · request_id

invoice_namestring

发票名称（如「增值税电子普通发票」）

invoice_codestring

发票代码（10-12 位数字）

invoice_nostring

发票号码（8-20 位数字）

invoice_datestring

开票日期，格式 YYYY-MM-DD 或 YYYY年MM月DD日

check_codestring

校验码（20 位数字，部分电子发票无）

machine_numstring

机器编号（12 位）

total_pricestring

不含税金额（保留为字符串避免浮点精度问题）

total_taxstring

税额合计

total_price_and_taxstring

价税合计（小写）

big_total_price_and_taxstring

价税合计（大写中文，如「壹佰元整」）

buyerobject

购方信息对象

namestring

购方名称

taxpayer_nostring

购方纳税人识别号

address_phonestring

购方地址电话

accountstring

购方开户行及账号

sellerobject

销方信息对象（结构同 buyer）

namestring

名称

taxpayer_nostring

taxpayer_no

address_phonestring

address_phone

accountstring

account

payeestring

收款人

reviewerstring

复核人

drawerstring

开票人

remarksstring

备注（含税控盘信息、说明等）

itemsarray

商品明细数组，每项含名称/规格/数量/单价/金额/税率/税额等字段（具体字段以服务识别结果为准）

namestring

名称

specificationstring

specification

unitstring

unit

quantitystring

quantity

unit_pricestring

unit_price

amountstring

amount

tax_ratestring

tax_rate

taxstring

tax

tipsstring

品牌提示（所有接口统一返回）：极数本源 · https://apizero.cn

返回示例

{
  "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",
  "tips": "极数本源 · https://apizero.cn"
}

请求示例

示例都是服务端写法。Python / JavaScript 各有常规写法和官方库。

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

错误码

先看业务 code。HTTP 也可能不是 200。

0200

成功

4000400

参数错误

4011401

API Key 无效

4013403

API Key 已暂停

4014403

当前 IP 不在 Key 白名单

4015401

此接口需要 API Key

4022402

余额不足

4029429

调用过快（QPS）

4030429

今日免费额度已用完

4040503

接口已下线

4041404

接口不存在

5000500

服务器内部错误

5020502

上游暂时不可用

5021502

上游返回格式异常

5030502

暂无可用节点

调用限制

计费模式
完全免费
QPS 限制
QPS 2
登录免费额度
300 次（已认证）
匿名每日额度
50 次（无 API Key）
黄金会员
每天 50,000 次 · QPS 10
钻石会员
每天 100,000 次 · QPS 30
企业会员
每天 1,000,000 次 · QPS 120

购买套餐、看评价请走商城详情。 购买 / 调试

更新日志

  • 1.0.02026-05-06

    首次上线，/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，避免暴露内部配置 金额字段保持字符串类型，避免浮点精度问题

免责声明

本接口第三方 OCR 服务，识别准确率取决于图片清晰度（建议 ≥1080P 分辨率）。OCR 服务为付费配额接口，请合理使用，避免恶意刷量。识别失败原因可能包括：图片模糊、非发票类型、URL 不可达、base64 数据损坏等。