适用场景与接口能力边界机动车发票识别OCR-Vehicle-Invoice专用于结构化提取机动车销售发票上的关键字段包括发票代码、号码、开票日期、查看文档方/销售方信息、车辆识别代号VIN、型号、价税明细等20个字段。该接口适用于以下典型场景二手车交易核验自动提取发票中的车辆信息和用量说明辅助交易审核。购车报销录入财务系统对接OCR结果免去人工录入发票数据。增值税抵扣材料整理提取价税分离数据用于税务申报或发票归档。能力边界支持图片格式jpg/png不接受bmp、gif、tiff等格式最大文件大小10MB超过会返回400错误推荐图片要求发票平整、无遮挡、拍摄清晰倾斜角度不超过30度以避免识别率下降。QPS限制2次/秒超过此频率会返回429限流错误认证方式Bearer Token放在Authorization头接口本身不承诺100%识别率若图片模糊或发票严重破损部分字段可能为空。下面将重点分析调用过程中最常见的错误及其排查方法。鉴权与请求构造常见错误1. HTTP 401 Unauthorized – 认证失败现象服务端返回401状态码响应体类似{code: 401, msg: Unauthorized, request_id: req_xxx}原因未携带Authorization请求头。携带了但格式不正确例如缺少Bearer前缀。API Key无效已删除、过期或属于不同应用。排查步骤确认请求中包含了Authorization: Bearer Your API Key注意Bearer后有一个空格。API Key是字符串不要包含额外引号或换行。检查API Key是否已从服务商管理平台复制正确常见错误是复制时多复制了空格或漏字符。如果使用环境变量确认环境变量已正确设置且未被截断。curl测试替换你的Keycurl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY_HERE \ -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若返回200则鉴权通过若返回401请检查Key。2. HTTP 400 Bad Request – 参数错误现象收到400状态码响应体包含code非0如code: 1001msg提示具体错误。常见子错误a.input_type取值不合法仅支持url或base64不能写成URL或Url大小写敏感。示例错误{input_type: link, ...}→ 返回400。b.input_data格式与类型不匹配当input_typeurl时input_data必须是合法的http://或https://开头的图片链接。不能是本地路径如/tmp/invoice.jpg或空的字符串。当input_typebase64时input_data应为base64编码字符串可以包含前缀data:image/jpeg;base64,或data:image/png;base64,也可以不包含服务端会尝试自动检测。但字符串长度不能为0且必须是合法base64即只含A-Za-z0-9/字符。c. 图片大小超过10MB无论url还是base64服务端会检查图片文件大小下载后或解码后。超过10MB返回错误。对于base64字符串长度约等于文件大小的4/3因此base64字符串长度不应超过约13.33MB10M * 4/3。d. 图片格式不支持服务端会检查图片MIME类型或文件头。只接受jpg/jpeg和png。如果url指向gif或bmp会报错。建议发送前先检查文件扩展名或MIME。e. 图片无法下载url模式如果提供的url不可访问403禁止、404不存在、域名解析失败、超时等API会返回400msg类似“图片下载失败请检查图片链接是否可访问”。排查方法在开发环境先手动用curl测试一个已知可访问的发票图片url。检查图片大小curl -sI https://example.com/invoice.jpg | grep -i content-length返回字节数。检查base64字符串长度echo -n 你的base64 | wc -c确保不超过约13.4M。确保图片url返回HTTP 200且Content-Type为image/jpeg或image/png。业务返回码code详解与错误处理API响应体结构如下{ code: 0, msg: 成功, data: { ... }, request_id: req_xxx }当code为0时表示成功非0表示业务失败。常见非0值code可能原因处理建议1001参数校验失败如缺少必填字段、类型错误检查请求体JSON格式确保input_type和input_data都存在且正确类型1002图片文件无效下载失败、解码失败、文件损坏更换图片源若使用base64检查编码是否正确可用在线工具验证1003图片质量过低无法提取任何发票信息重新拍摄发票保证平整、清晰、光照均匀最好使用300DPI以上扫描件1004QPS超限超过2次/秒增加请求间隔或使用队列/限流机制参考Retry-After响应头1005系统内部错误临时性重试1-2次若持续出现请联系平台技术支持注意msg字段可能包含更详细的中文描述开发者应优先解析msg并在日志中记录方便人工排查。QPS限流与重试策略接口QPS为2次/秒即每秒最多处理2个请求。如果调用频率超过此限制服务端会返回HTTP 429 Too Many Requests且响应体中code可能为1004。处理方法在客户端做好限速可以使用令牌桶或固定窗口控制每秒不超过2次。对于瞬间并发场景建议使用队列缓冲。若收到429可解析Retry-After响应头单位秒等待该时间后再重试。示例Node.js中的简易队列伪代码const queue []; let lastRequestTime 0; const minInterval 500; // ms对应QPS2 async function callOCR(payload) { const now Date.now(); const wait Math.max(0, minInterval - (now - lastRequestTime)); await new Promise(resolve setTimeout(resolve, wait)); lastRequestTime Date.now(); // 发起请求... }返回值字段解读与空值处理成功响应data中的字段不一定全部有值。常见空值原因buyer_id查看文档方纳税人识别号、print_code打印代码发票上若未印刷或OCR识别失败会返回空字符串。certificate_num合格证号只有当发票包含合格证信息时才有值。product_model车辆型号若发票区域模糊可能识别为部分值或空。工程建议所有字段判空若buyer_id为空不要直接使用可提示用户手动补充。金额字段如price、total_price_little虽是字符串但可解析为数值注意total_price大写金额用于展示不应参与计算。使用request_id记录日志方便追踪单次请求。{ 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 }工程化注意事项1. 图片预处理在上传前建议在客户端校验图片格式和大小避免无效请求浪费API配额。若使用base64注意去除换行符某些SDK会带换行。对于扫描件可先做自动裁剪和矫正偏斜校正能明显提升识别率。2. 超时设置网络请求超时建议设为10秒以上因为图片下载和处理需要时间尤其是大图。若使用curl可加--max-time 15。3. 错误重试对于HTTP 429、5xx500/502/503等临时错误可实现指数退避重试最多3次。对于HTTP 401、400参数错误不要重试应修复参数。4. 安全性API Key 不应明文存储在代码或前端建议存储在后端环境变量或密钥管理服务中。对图片URL进行校验避免SSRF攻击虽然接口会检查但客户端最好也限制。5. 日志记录记录每次请求的request_id、code、msg、图片大小和耗时方便后续错误分析和计费审计。参考文档官方文档页https://apizero.cn/aidocs/ocr-vehicle-invoice原始接口定义https://apizero.cn/aidocs/ocr-vehicle-invoice/raw.md若有其他问题可查阅API平台的常见问题或联系技术支持。