增值税发票识别invoice
增值税发票 OCR 识别，支持增值税专用发票、普通发票、电子普票，输出 22+ 个结构化字段。 • 双输入模式： - input_type=url：传入公网可访问的图片 URL（http/https） - input_type=base64：传入 base64 编码字符串（≤6MB，自动剥离 data:image/...;base64, 前缀） • 完整识别字段： - 发票基本：发票名称、代码、号码、开票日期、校验码、机器编号 - 金额：价税合计、税额、不含税金额、大写金额 - 购销方：名称、纳税人识别号、地址电话、开户行账号 - 经办人：收款人、复核人、开票人 - 商品明细：items 数组，含品名/规格/数量/单价/金额/税率/税额 - 备注与盖章信息 • OCR 结果缓存 1 小时（同图同结果），减少重复调用消耗。
1. 基本信息
| 接口地址 | https://v1.apizero.cn/api/invoice |
|---|---|
| 请求方法 | POST |
| 分类 | dev |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 2 req/s |
| 每日免费额度 | 30 次（已认证用户） |
| 匿名每日额度 | 5 次（无 API Key） |
| VIP 免费 | 否 |
| 调用次数 |
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)
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. 响应示例
{
"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，避免暴露内部配置
- 金额字段保持字符串类型，避免浮点精度问题