企业官网建设流程全解析

适用场景

增值税发票识别的核心价值在于将纸质或电子发票图像转化为结构化数据。典型应用场景包括：

• 企业财务报销系统：员工拍照上传发票，自动提取金额、税号、日期等信息，减少人工录入。
• 发票核查与验真：OCR提取的发票代码、号码可作为查验平台的输入参数。
• 供应链对账：自动归档进项发票，比对购销双方信息，匹配订单金额。
• 电子档案管理：批量扫描历史发票，建立可搜索的电子档案库。

这些场景的共同需求是高识别精度与标准化输出，本文介绍的 API 可输出 22+ 结构化字段，并针对增值税专用/普通/电子发票做了专项优化。

接口能力与限制

• 端点：POST https://v1.apizero.cn/api/invoice
• QPS：2 请求/秒（超限将返回 429 状态码）
• 图片处理：支持 URL 或 Base64 输入；单张图片 Base64 最大 6MB（建议 1MB 以内以获得最佳性能）
• 输出字段：22+ 个，包括发票基本信息、购销方详情、商品明细（items 数组）、金额大小写等
• 结果缓存：同一张图片（按文件哈希）1 小时内重复请求返回相同结果，避免浪费调用次数

注意：接口不直接验真，仅作 OCR 识别。发票真伪核验需配合税务官方系统。

鉴权方式

该 API 支持两种鉴权策略：

1. 匿名调用（每日 5 次）：无需任何 HTTP 头，直接 POST。
2. API Key 鉴权：在请求头中添加Authorization: Bearer sk_live_xxxxxxxx或X-API-Key: sk_live_xxxxxxxx（两种方式等效，推荐使用更标准的Authorization头部）。

实际生产中请使用生产 Key，避免匿名调用额度不足导致报错。

请求参数详解

请求体为 JSON 格式，必须包含以下两个字段：

请求头要求：

• Content-Type：必须为application/json（注意：部分旧版文档可能写application/x-www-form-urlencoded，但实际 JSON 标准请求体使用application/json兼容性更好）

参数选择建议

• 如果图片已存储在对象存储（OSS）或 CDN，优先使用url模式，减少客户端编码开销。
• 如果图片来自本地文件、相机拍照，建议用base64模式，直接在前端或后端转为 Base64 传入，避免上传依赖。

curl 请求示例

以下示例使用 API Key 鉴权，并采用 URL 模式发送图片：

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

若使用 Base64 模式，先获取图片的 Base64 字符串（可通过base64 invoice.jpg | tr -d '\n'生成），然后构造请求体：

#!/bin/bash # 注意：实际使用时替换 API Key 和图片路径 API_KEY="sk_live_您的密钥" IMAGE_B64=$(base64 -w0 invoice.jpg) curl -sS -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d "{\"input_type\": \"base64\", \"input_data\": \"$IMAGE_B64\"}" \ "https://v1.apizero.cn/api/invoice"

返回字段详解

成功响应的状态码为200，返回 JSON 结构如下：

{ "code": 0, "msg": "成功", "request_id": "abc123def456", "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": "壹佰圆整", "drawer": "王五", "payee": "张三", "reviewer": "李四", "remarks": "", "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" }, "items": [ { "name": "*技术服务*软件开发服务", "specification": "", "unit": "", "quantity": "", "unit_price": "", "amount": "94.34", "tax_rate": "6%", "tax": "5.66" } ] } }

关键字段说明

• 基础信息：invoice_name为《增值税专用发票》《增值税普通发票》《电子普通发票》等；check_code仅在专票/普票中常见，电子普票可能为空。
• 金额字段：total_price（不含税金额）、total_tax（税额）、total_price_and_tax（价税合计）。三个字段均为字符串，返回时保留两位小数。
• 购销方对象：buyer和seller均包含name、taxpayer_no、address_phone、account四个字段，若无则返回空字符串。
• items数组：每一条商品明细包含 8 个字段，其中name为票据上的名称（可能包含*分隔符）。amount为该条金额（不含税），tax为该条税额，tax_rate含百分号。
• big_total_price_and_tax：大写金额，仅部分发票支持。

注意：code为0表示识别成功；非0时请查看msg字段获取错误原因。

常见错误与排查

工程化最佳实践

1. 图片预处理：建议上传前统一转为 JPEG（质量 90%），宽度至少 1024px，可有效提升识别率。PDF 发票需先转换为单张图片。
2. 输入模式选择：若前端直连 API，Base64 模式简单；若通过后端中转，URL 模式可避免多次转码。对于生产环境，建议将图片上传到 OSS 再传 URL，后端只需管理一次鉴权。
3. 结果缓存利用：同一个请求参数（同一张图片）在一小时内返回相同结果，因此业务端无需额外去重，但注意图片修改（即使微小变化）会导致新哈希。
4. 错误重试策略：遇到 429 或 5xx 错误时，采用指数退避（如 1s、2s、4s），最多重试 3 次。对 4xx 错误（如 401、413）不应重试，应直接记录并通知开发。
5. 字段校验：返回的金额字段为字符串，建议解析为Decimal避免浮点精度损失。商品明细数组items长度可能为 0（部分简易发票不展示明细），业务代码需兼容空数组。
6. 幂等性：每次调用均生成新的request_id，可用于日志追踪和计费核对，建议在日志中保留该 ID。

参考文档

• 增值税发票识别 API 文档
• 原始接口 Markdown