业务场景为何需要结构化机动车发票数据机动车销售统一发票是车辆交易的核心凭证广泛存在于二手车交易核验、企业购车费用报销、增值税进项抵扣等业务流中。传统人工录入20余个字段不仅耗时还容易因手写模糊或抄写失误导致数据错误。通过OCR接口将发票图片直接解析为结构化JSON可无缝对接企业ERP、财务系统或税务平台提升数据流转效率。接口能力与识别字段本接口专为机动车销售发票设计可识别如下20个关键字段发票代码、发票号码、开票日期、查看文档方名称及证件号、销售方名称/纳税人识别号/地址电话、车辆类型、车辆识别代号VIN、厂牌型号、合格证号、机器编号、裸车用量说明、税额、税率、价税合计大写和小写、打印代码与打印号码。识别效果依赖图片质量建议使用平整、无反光、清晰无遮挡的发票照片文件大小不超过10MB支持jpg/png格式。若图片倾斜或模糊部分字段可能缺失业务系统需做好空值兼容处理。请求接入鉴权方式在HTTP请求头中传递Authorization字段格式为Authorization: Bearer 您的API Key。API Key需通过平台申请获得请妥善保管避免硬编码在公开代码仓库中。请求参数与地址接口地址POST https://v1.apizero.cn/api/ocr-vehicle-invoice请求体JSON对象参数名类型必填说明input_typestring是图片传输方式可选url公网图片URL或base64图片Base64编码input_datastring是图片内容url时填完整HTTP/HTTPS链接base64时填Base64字符串可含data:image/xxx;base64,前缀总大小不超过10MB请求示例curlURL方式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-invoicePythonBase64方式适合本地图片import requests import base64 with open(vehicle_invoice.jpg, rb) as f: img_base64 base64.b64encode(f.read()).decode(utf-8) url https://v1.apizero.cn/api/ocr-vehicle-invoice headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } payload { input_type: base64, input_data: img_base64 } response requests.post(url, headersheaders, jsonpayload) data response.json() print(data)Java使用OkHttp示例OkHttpClient client new OkHttpClient(); String base64 Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get(invoice.jpg))); String json {\input_type\:\base64\,\input_data\:\ base64 \}; Request request new Request.Builder() .url(https://v1.apizero.cn/api/ocr-vehicle-invoice) .addHeader(Authorization, Bearer YOUR_API_KEY) .addHeader(Content-Type, application/json) .post(RequestBody.create(json, MediaType.parse(application/json))) .build(); try (Response response client.newCall(request).execute()) { System.out.println(response.body().string()); }返回值解读成功响应HTTP 200返回如下JSON结构字段示例{ code: 0, msg: 成功, request_id: req_abc123, data: { invoice_code: 31100000000, invoice_num: 12345678, date: 2024年01月15日, buyer_name: 张三, buyer_id: , saler_name: XX汽车销售有限公司, saler_id: 91310000XXXXXXXXXX, saler_addr: 上海市XX路XX号 021-XXXXXXXX, vehicle_type: 小型轿车, vin: 4A123456, product_model: 丰田/CAMRY, certificate_num: LSXXXXXXXXXXXXX, machine_num: 499098765432, price: 156055.05, tax: 13944.95, tax_rate: 9%, total_price: 壹拾柒万元整, total_price_little: 170000.00, print_code: , print_num: } }重要字段说明字段说明业务用途invoice_code发票代码12位数字校验发票真伪配合发票号码invoice_num发票号码8位数字唯一标识一张发票date开票日期如2024年01月15日确认交易时间用于报销时校验buyer_name/buyer_id查看文档方名称与证件号企业报销需匹配员工身份二手车过户核验saler_name/saler_id销售方信息验证开票主体是否合法vin车辆识别代号17位车辆唯一身份二手车交易核心校验字段vehicle_type车辆类型如小型轿车用于车辆登记管理price/tax/total_price_little裸车价、税额、含税总价数字财务记账、增值税进项抵扣计算total_price大写价税合计与total_price_little一致性核对常见字段注意buyer_id、print_code、print_num等字段可能为空字符串业务系统在消费前应进行非空判断避免直接使用导致错误。常见错误与处理HTTP状态码code值可能原因处理建议401无API Key无效或未提供检查Authorization头格式确认Key未过期40010001请求体JSON格式错误或缺少必填参数确保input_type和input_data均存在且类型正确40010002图片读取失败格式不支持、大小超限使用jpg/png图片压缩至10MB以内检查Base64编码是否正确200!0图片识别失败非机动车发票、遮挡严重等更换清晰图片确认图片内容为机动车销售统一发票429无超出QPS限制2次/秒加入请求队列或休眠至少500ms再发起下一次请求建议在客户端实现重试逻辑当遇5xx或网络错误时指数退避重试如1s、2s、4s间隔最多3次对于4xx错误则应直接上报并停止重试。工程化注意事项图片预处理发票图片可能倾斜、反光或带有无关背景建议在上传前对图片进行自动旋转校正与裁剪只保留发票主体区域可显著提升字段识别率。Base64大小优化将图片转为Base64前先压缩至合适分辨率如2000px宽既保障识别效果又降低传输体积。QPS管理接口限制2次/秒若业务需要批量处理如每天几百张可使用消息队列RabbitMQ/Redis List控制消费速率避免被强制限流。字段校验返回的price、tax等数值字段均是字符串入库前需转换为数字类型并校验合法性total_price_little应与pricetax相等允许小数误差。数据安全API Key建议通过环境变量或密钥管理服务注入不要硬编码在代码中发票图片涉及个人/企业隐私传输过程务必使用HTTPS处理后图片应及时删除或脱敏保存。日志与监控记录每次请求的request_id以便后续追踪针对code非0的响应应保留原始图片与错误信息用于分析识别失败原因。异步模式如果对实时性要求不高可以设计为前端上传图片后端异步调用本接口将识别结果存入数据库通过轮询或Webhook通知前端获取结果。参考文档接口文档https://apizero.cn/aidocs/ocr-vehicle-invoice原始文档https://apizero.cn/aidocs/ocr-vehicle-invoice/raw.md