从零开始：增值税发票OCR识别的最小可运行示例

为什么需要最小可运行示例

在对接任何API时，拥有一个最小可运行示例（minimal working example）能够最快地验证接口可用性，排除网络、鉴权、参数等环境问题。本文以增值税发票OCR识别接口为例，提供从请求到响应的端到端可执行代码，让开发者在一个命令内完成首次调用，再逐步深入字段含义与工程化细节。

接口能力与适用场景

增值税发票OCR识别支持三种常见发票类型：

• 增值税专用发票（蓝字/红字）
• 增值税普通发票（折叠票、卷票）
• 增值税电子普通发票（PDF或截图）

输出22个以上结构化字段，核心包括：

适用场景：财务自动记账、报销审批系统、发票验真前置识别、税务数据数字化等。

接口地址与鉴权方式

• 请求方法：POST
• 请求URL：https://v1.apizero.cn/api/invoice
• 鉴权（可选）：通过HTTP HeaderAuthorization: Bearer sk_live_xxx传递API Key。不携带该Header时，每个IP每日有5次匿名调用额度（用于快速测试）。
• Content-Type：application/json（实际测试确认，请求体为JSON格式时需使用此类型，而非文档中写明的application/x-www-form-urlencoded，建议以可运行示例为准）

注：如果需要更稳定的日常调用，建议申请API Key并放在请求头中。

最小可运行curl示例（图片URL模式）

以下命令展示如何通过公网图片URL识别发票。将YOUR_API_KEY替换为你的真实密钥（不填也可匿名测试），将https://example.com/invoice.jpg替换为一张有效的增值税发票图片URL。

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

运行结果演示（假设图片有效）

如果成功，你将获得如下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_and_tax": "100.00", "total_tax": "5.66", "total_price": "94.34", "big_total_price_and_tax": "壹佰圆整", "seller": { "name": "某某商贸有限公司", "taxpayer_no": "91310000YYYYYYYYYY", "address_phone": "上海市XX区XX路XX号 021-87654321", "account": "工商银行 6222001234567890" }, "buyer": { "name": "某某科技有限公司", "taxpayer_no": "91110000XXXXXXXXXX", "address_phone": "北京市XX区XX路XX号 010-12345678", "account": "中国银行 6217001234567890" }, "items": [ { "name": "*技术服务*软件开发服务", "specification": "", "unit": "", "quantity": "", "unit_price": "", "amount": "94.34", "tax_rate": "6%", "tax": "5.66" } ], "drawer": "王五", "payee": "张三", "reviewer": "李四", "remarks": "" } }

参数详解

请求体参数（JSON）

可选：base64 模式示例

如果需要从本地图片直接上传（无需外网URL），可使用base64模式。首先获取图片的base64编码（Linux/macOS）：

# 将图片转换为base64，注意不带 data 前缀 base64 -w0 /path/to/invoice.jpg > invoice.txt

然后构造请求（注意input_type为base64）：

curl -sS \ -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input_type": "base64", "input_data": "<base64_string>" }' \ "https://v1.apizero.cn/api/invoice"

注意：base64字符串不宜过长，6MB限制对应约4MB的原始图片（JPEG/PNG），一般清晰发票截图即可。

返回字段深度解读

响应结构为：

{ "code": 0, "msg": "成功", "request_id": "abc123def456", "data": { ... } }

• code：0表示识别成功，非零表示错误（参见下一节）。
• msg：对应的中文描述。
• request_id：本次请求的唯一标识，可用于日志排查。
• data：结构化识别结果对象，包含所有发票字段。

data中常用字段说明（部分）：

常见错误与调试方法

快速验证：如果首次调用返回非0 code，建议使用curl的-v参数打印详细请求头与响应头，确认Content-Type和Authorization无误。

工程化注意事项

1. 图片质量要求

• 推荐分辨率：1024×768以上，文字清晰、光线均匀。
• 不支持手写发票、涂改严重的发票。
• 发票四角尽量完整，无遮挡。

2. 缓存机制

接口对相同图片（基于图片hash）有1小时缓存，若在1小时内用同一图片重复请求，将直接返回缓存结果。该设计可减少重复识别消耗，但在测试时如果修改了图片内容，请等待1小时或换用不同图片。

3. QPS 限制

接口QPS为2次/秒（即每秒最多2个并发请求）。建议在代码中增加本地重试与限流逻辑（如令牌桶），避免429错误。

4. 安全性考虑

• 如果使用base64模式，不要在日志中打印完整的base64字符串，可能包含敏感发票信息。
• 建议使用HTTPS保护传输，API Key存储在环境变量或密钥管理中，不要硬编码在代码仓库。

5. 错误重试策略

对于5xx错误（服务端问题），建议使用指数退避重试（如1秒、2秒、4秒），最多3次。对于4xx或业务错误码，应直接返回错误信息给上层，而非重试。

6. 字段落地到数据库

建议将data下的所有字段以JSON格式存入一个TEXT字段，同时在业务表中提取关键字段（如发票号码、开票日期、价税合计）用于查询。items数组可单独成表或JSON存储。

7. 测试建议

准备至少3张不同类型的发票图片（专票、普票、电子票），分别使用url和base64两种模式测试，确保覆盖常见情况。

参考文档

• 增值税发票OCR识别原始文档
• 增值税发票OCR识别文档页
• 其他常见问题可查看官方FAQ。

总结

通过本文提供的最小可运行curl示例，你已经可以在几分钟内完成增值税发票OCR的首次调用。后续基于返回的结构化字段，可以轻松对接财务系统、报销应用或数据中台。请记得在实际生产环境中处理好鉴权、限流与错误重试，确保服务稳定。