零基础上手机动车发票识别API：一份最小可运行示例

适用场景为什么需要结构化提取发票数据在二手车交易、财务报销、税务核算等业务中机动车销售发票是关键原始凭证。传统人工录入不仅耗时还容易因笔误导致数据差异。通过API将发票图片转化为结构化JSON可以直接对接OA、ERP或税务系统减少人工核对环节。典型的应用场景包括二手车交易核验自动读取车辆VIN码、车辆型号和查看文档方信息辅助真实性核验。企业财务报销自动化OCR结果直接填入报销单金额、税额、开票日期等字段。税务核对将价税合计、税率与申报系统比对提升抵扣效率。接口能力边界调用前需要明确当前API能做什么、不能做什么支持的图片格式jpg / png单张文件大小不超过10 MB。传输方式支持通过公网图片URL传输或使用Base64编码后的图片数据。返回字段最多可提取20个结构化字段包括发票代码、发票号码、开票日期、查看文档方/销售方名称及识别号、车辆类型、VIN码、价税合计、税率等。注意事项发票需要平整、拍摄清晰、无遮挡过长的连拍或严重倾斜的图片可能影响识别准确率。QPS限制每秒最多2次请求超出后可能会收到限流响应以实际返回码为准。参数与鉴权Header参数每个POST请求必须携带以下Header参数名是否必须类型说明Authorization是string格式为Bearer 你的API Key用于身份验证。Content-Type否string请求体格式通常为application/json不设置时默认也可能被接受。API Key 一般需要从服务商的管理后台获取请妥善保管避免泄露到公共代码仓库中。请求体参数请求体为一个JSON对象包含两个必填字段{ input_type: url, input_data: https://example.com/vehicle-invoice.jpg }字段名类型必填说明input_typestring是图片传输方式url表示公网图片地址base64表示图片的Base64编码。input_datastring是当input_typeurl时填写图片的 http/https 链接当input_typebase64时填写Base64字符串可含data:image/xxx;base64,前缀也可不含。注意如果使用base64方式建议将图片大小控制在8MB以内编码后约10.6MB避免请求体过大导致的超时或截断。最小可运行 curl 示例下面提供一个可直接复制的curl命令。请将YOUR_API_KEY替换为你自己的真实API Key并将图片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/vehicle-invoice.jpg } \ https://v1.apizero.cn/api/ocr-vehicle-invoice如果图片上传到公网不方便也可以使用Base64方式# 先对本地图片做Base64编码假设图片为 test.jpg # Linux/macOS: IMAGE_BASE64$(base64 -w0 test.jpg) # Windows (PowerShell): # $imageBase64 [Convert]::ToBase64String([IO.File]::ReadAllBytes(test.jpg)) curl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { \input_type\: \base64\, \input_data\: \$IMAGE_BASE64\ } \ https://v1.apizero.cn/api/ocr-vehicle-invoice建议首次测试尽量使用一张清晰、发票区域占比大的JPEG图片URL方式出错概率低待确认脚本流程正确后再切换到Base64方式以便集成到后端代码中。返回值逐字段解读成功时API返回如下结构的JSON已格式化{ code: 0, data: { buyer_id: , buyer_name: 张三, certificate_num: LSXXXXXXXXXXXXX, date: 2024年01月15日, invoice_code: 31100000000, invoice_num: 12345678, machine_num: 499098765432, price: 156055.05, print_code: , print_num: , product_model: 丰田/CAMRY, saler_addr: 上海市XX路XX号 021-XXXXXXXX, saler_id: 91310000XXXXXXXXXX, saler_name: XX汽车销售有限公司, tax: 13944.95, tax_rate: 9%, total_price: 壹拾柒万元整, total_price_little: 170000.00, vehicle_type: 小型轿车, vin: 4A123456 }, msg: 成功, request_id: req_abc123 }顶层字段说明字段名类型含义codenumber业务状态码0表示请求成功并识别完成非零值表示异常。msgstring业务提示信息通常为“成功”或错误描述。dataobject识别结果的核心数据对象。request_idstring本次请求的唯一标识可用于排查日志。data 对象各字段速览字段名类型对应发票区域说明invoice_codestring发票代码如果未能识别可能为空字符串。invoice_numstring发票号码——datestring开票日期示例格式2024年01月15日。buyer_namestring查看文档方名称——buyer_idstring查看文档方识别号企业为统一社会信用代码个人可能为空。saler_namestring销售方名称——saler_idstring销售方识别号——saler_addrstring销售方地址及电话包含地址电话部分发票可能只有地址。vehicle_typestring车辆类型如“小型轿车”。product_modelstring厂牌型号品牌/型号信息。vinstring车辆识别代号/车架号——certificate_numstring合格证号——machine_numstring机器编号——pricestring不含税价数值字符串如156055.05。taxstring增值税额——tax_ratestring增值税税率含百分号如9%。total_pricestring价税合计大写中文大写。total_price_littlestring价税合计小写数值字符串如170000.00。print_codestring打印在发票上的代码部分省份不呈现此字段可能返回空。print_numstring打印在发票上的号码同上。注意当code ! 0时data可能缺失或为null此时应以msg中的文字提示为准。常见错误排查1. 400 Bad Request可能原因请求体格式不正确如JSON语法错误、图片URL不是有效格式。检查方法使用jq .验证JSON是否合法确保URL可公网访问且以http://或https://开头。2. 401 Unauthorized可能原因AuthorizationHeader 格式错误或API Key无效。检查方法确认前缀为Bearer注意空格测试Key是否已过期检查是否误将Key放入请求体。3. 413 Request Entity Too Large可能原因Base64后的图片数据超过服务端限制。检查方法将图片压缩至8MB以内或改用URL方式传输。4. 非200状态码500服务端内部错误可重试或稍后调用。503服务暂不可用常见于QPS超限或临时维护。5. 返回code ! 0的常见情况识别失败图片不清晰、发票倾斜严重、背景杂乱等。建议重新拍照并保证发票占据画面60%以上。图片无法解析尝试使用base64方式代替URL排除网络下载故障。工程化注意事项并发控制QPS上限为2次/秒建议在代码中实现退避或本地队列避免触发限流。重试策略对5xx响应采用指数退避如第一次等待1秒第二次2秒第三次4秒对4xx响应不重试直接记录日志。图片预处理在调用前端做高宽比校正、旋转校正和降噪能显著提升识别率。数据校验返回的total_price_little应与price tax基本一致考虑浮点误差若发现偏差较大建议人工介入。隐私与合规发票中包含查看文档方、销售方及车辆信息传输和存储时应采用HTTPS加密并在数据库中做脱敏或加密存储。参考文档机动车发票识别API文档原始Markdown文档