适用场景增值税发票识别的核心价值在于将纸质或电子发票图像转化为结构化数据。典型应用场景包括企业财务报销系统员工拍照上传发票自动提取金额、税号、日期等信息减少人工录入。发票核查与验真OCR提取的发票代码、号码可作为查验平台的输入参数。供应链对账自动归档进项发票比对购销双方信息匹配订单金额。电子档案管理批量扫描历史发票建立可搜索的电子档案库。这些场景的共同需求是高识别精度与标准化输出本文介绍的 API 可输出 22 结构化字段并针对增值税专用/普通/电子发票做了专项优化。接口能力与限制端点POST https://v1.apizero.cn/api/invoiceQPS2 请求/秒超限将返回 429 状态码图片处理支持 URL 或 Base64 输入单张图片 Base64 最大 6MB建议 1MB 以内以获得最佳性能输出字段22 个包括发票基本信息、购销方详情、商品明细items 数组、金额大小写等结果缓存同一张图片按文件哈希1 小时内重复请求返回相同结果避免浪费调用次数注意接口不直接验真仅作 OCR 识别。发票真伪核验需配合税务官方系统。鉴权方式该 API 支持两种鉴权策略匿名调用每日 5 次无需任何 HTTP 头直接 POST。API Key 鉴权在请求头中添加Authorization: Bearer sk_live_xxxxxxxx或X-API-Key: sk_live_xxxxxxxx两种方式等效推荐使用更标准的Authorization头部。实际生产中请使用生产 Key避免匿名调用额度不足导致报错。请求参数详解请求体为 JSON 格式必须包含以下两个字段字段名类型必填说明input_typestring是url或base64指定输入形式input_datastring是当input_typeurl时公网可访问的图片 HTTP/HTTPS 链接当input_typebase64时图片的 Base64 编码字符串最大 6MB可包含data:image/jpeg;base64,前缀SDK 会自动剥离请求头要求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_KEYsk_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字段获取错误原因。常见错误与排查错误表现可能原因解决方案400 Bad Requestmsg: input_data is empty图片参数为空或失真检查input_data值是否是有效 URL 或 Base64 字符串401 UnauthorizedAPI Key 无效或未带鉴权头确认 Key 前缀为sk_live_并放入正确请求头413 Payload Too LargeBase64 图片体积超过 6MB压缩图片至 1MB 内JPEG 质量 80%或改用 URL 模式429 Too Many RequestsQPS 超限2/s加入重试退避逻辑或降低请求频率502 Bad Gateway/ 超时图片不可达URL 模式或服务器内部处理异常确认 URL 公网可访问且图片格式为 jpg/png/bmp若持续出现请联系技术支持200 OK但data中关键字段为空图片质量差、文字模糊、发票种类不在支持范围内提升图片分辨率建议800px宽确保发票区域完整且无遮挡工程化最佳实践图片预处理建议上传前统一转为 JPEG质量 90%宽度至少 1024px可有效提升识别率。PDF 发票需先转换为单张图片。输入模式选择若前端直连 APIBase64 模式简单若通过后端中转URL 模式可避免多次转码。对于生产环境建议将图片上传到 OSS 再传 URL后端只需管理一次鉴权。结果缓存利用同一个请求参数同一张图片在一小时内返回相同结果因此业务端无需额外去重但注意图片修改即使微小变化会导致新哈希。错误重试策略遇到 429 或 5xx 错误时采用指数退避如 1s、2s、4s最多重试 3 次。对 4xx 错误如 401、413不应重试应直接记录并通知开发。字段校验返回的金额字段为字符串建议解析为Decimal避免浮点精度损失。商品明细数组items长度可能为 0部分简易发票不展示明细业务代码需兼容空数组。幂等性每次调用均生成新的request_id可用于日志追踪和计费核对建议在日志中保留该 ID。参考文档增值税发票识别 API 文档原始接口 Markdown