出租车发票识别 API 参数详解与工程化实践

适用场景结构化提取发票字段对接差旅与财务系统出租车发票出租车机打发票在日常差旅报销、行程费用核对、财务审计等场景中广泛存在。传统人工录入方式耗时易错通过 OCR 接口自动识别并结构化输出车号、上下车时间、里程、金额、发票代码/号码、单价、附加费、印章信息等 16 个字段可极大提升处理效率。典型落地场景包括企业差旅系統员工上传出租车发票图片系统自动识别关键字段并填入报销单。财务审计批量核对发票金额、发票号与行程是否匹配辅助合规审计。出行平台对账司机端发票与平台订单数据自动比对。接口能力边界支持的字段与输入限制出租车发票识别接口slug:ocr-taxi-invoice主要识别全国出租车机打发票非手撕票或电子发票。支持两种图片传输方式url公网可访问的图片链接和base64图片文件的 base64 编码字符串。接口QPS 上限为 2 次/秒超过该速率会返回频率限制错误。识别字段覆盖车辆信息车号car_number、里程distance时间信息上车时间start_time格式 HH:mm、下车时间end_time格式 HH:mm、日期start_date格式 yyyy-MM-dd金额信息总金额total_amount、单价price、附加费additional_fee、调度费dispatch_fee发票信息发票代码invoice_code、发票号码invoice_no印章信息发票专用章内容invoice_special_seal、印章中公司名称seller_name_in_seal、印章中纳税人识别号seller_taxpayer_no_in_seal其他发票标题title_trial、是否加盖印章is_sealed接口不承诺识别所有发票变种如部分城市格式差异建议图片平整、清晰、无遮挡。请求参数与鉴权详解基础 URLPOST https://v1.apizero.cn/api/ocr-taxi-invoiceHeader 参数参数名必填类型说明Authorization是stringBearer 你的 API Key从控制台获取Content-Type否string请求体格式推荐application/json注意素材中 curl 示例使用的X-API-KeyHeader 与Authorization可能为等效鉴权方式实际使用时请以最新文档为准。建议优先使用Authorization: Bearer your_api_key。请求体JSON Object字段必填类型说明input_type是string图片传输方式取值url或base64input_data是string图片内容。input_typeurl时为完整 http/https 图片链接input_typebase64时为图片的 base64 编码字符串可含data:image/xxx;base64,前缀请求体示例URL 模式{ input_type: url, input_data: https://example.com/taxi-invoice.jpg }请求体示例base64 模式{ input_type: base64, input_data: data:image/jpeg;base64,/9j/4AAQ... (实际 base64 字符串) }QPS 限制接口每秒最多处理 2 个请求。如果并发超过此限制将返回 HTTP 429 错误或由业务层返回频率限制提示。建议在批量场景下使用节流控制如每 500ms 发送一次请求或引入队列。可复制的 curl 接入示例以下示例使用Authorization头请将$YOUR_API_KEY替换为真实 API Keycurl -sS -X POST \ -H Authorization: Bearer $YOUR_API_KEY \ -H Content-Type: application/json \ -d { input_type: url, input_data: https://example.com/taxi-invoice.jpg } \ https://v1.apizero.cn/api/ocr-taxi-invoice若需使用 base64 方式将input_data中的 URL 替换为 base64 编码字符串即可。注意base64 字符串可能很长请确保 HTTP 客户端不截断。返回值字段详解成功响应HTTP 200格式如下{ code: 0, msg: 成功, request_id: req_abc123, data: { additional_fee: 1.00, car_number: 沪A12345, dispatch_fee: , distance: 12.3, end_time: 10:05, invoice_code: 31100000000, invoice_no: 87654321, invoice_special_seal: XX出租汽车发票专用章, is_sealed: true, price: 3.00, seller_name_in_seal: XX出租汽车有限公司, seller_taxpayer_no_in_seal: 91310000XXXXXXXXXX, start_date: 2024-01-15, start_time: 09:30, title_trial: 出租汽车发票, total_amount: 38.50 } }字段说明data 内字段类型说明car_numberstring车牌号如 沪A12345start_datestring发票日期格式 yyyy-MM-ddstart_timestring上车时间格式 HH:mmend_timestring下车时间格式 HH:mmdistancestring里程单位公里如 12.3total_amountstring总金额单位元如 38.50pricestring单价每公里用量说明单位元如 3.00additional_feestring附加费单位元dispatch_feestring调度费单位元可能为空字符串invoice_codestring发票代码invoice_nostring发票号码invoice_special_sealstring发票专用章上印刷的文字is_sealedstring是否加盖印章true或falseseller_name_in_sealstring印章中的企业名称seller_taxpayer_no_in_sealstring印章中的纳税人识别号title_trialstring发票标题文字如 出租汽车发票注意所有字段均为字符串即使数值型也是字符串形式。空字段返回空字符串。未识别到的字段也返回空字符串但不会缺少字段。请求 IDrequest_id字段可用于追踪单次请求结合服务端日志排查问题。常见错误与排查错误表现可能原因排查建议HTTP 401Authorization 头缺失或无效检查 API Key 是否正确是否包含Bearer前缀HTTP 400请求参数格式错误确认 JSON 结构input_type只能为url或base64input_data非空HTTP 429超过 QPS 限制降低请求频率每请求间隔至少 500mscode ! 0图片质量差或非出租车发票检查图片是否包含完整发票区域是否倾斜/模糊/过曝返回字段全部为空未识别到任何内容尝试更换图片确保发票为机打发票而非手撕票或电子发票图片质量最佳实践分辨率建议宽度不低于 1000 像素。拍摄平铺拍摄避免透视畸变光线均匀无阴影遮挡。格式支持 jpg、png文件大小建议小于 10MB。背景发票主体占图片面积 70% 以上避免背景杂乱。工程化注意事项1. 批量处理与重试策略由于 QPS 为 2批量处理时建议使用队列控制并发。例如 Python 中使用asyncioaiohttp限制同时请求数为 1 或 2并加入指数退避重试遇到 HTTP 429 或 5xx 错误。Python 伪代码示例import requests import time from typing import List def recognize_taxi_invoice(api_key: str, image_url: str) - dict: headers { Authorization: fBearer {api_key}, Content-Type: application/json } body { input_type: url, input_data: image_url } try: resp requests.post(https://v1.apizero.cn/api/ocr-taxi-invoice, headersheaders, jsonbody, timeout30) resp.raise_for_status() return resp.json() except requests.exceptions.HTTPError as e: if resp.status_code 429: time.sleep(1.0) # 简单等待后重试 # 实际应使用循环退避 else: raise e2. 字段校验与空值处理识别结果中部分字段如dispatch_fee可能为空字符串。在对接财务系统时建议对空字段设置默认值如0.00或进行空值判断。3. 多租户场景下的鉴权安全API Key 应存储在服务端环境变量或密钥管理服务中切勿硬编码在客户端代码或前端页面中。建议通过后端转发请求外部用户不直接暴露 API Key。4. 发票图片隐私合规发票图片包含车号、金额等敏感信息。系统应在识别完成后及时删除原始图片或进行脱敏处理避免数据泄漏。5. 响应解析时的字段类型注意事项所有字段均为字符串如果需要进行数值运算需要手动转换为float或Decimal并处理空字符串转换异常。参考文档原始 API 文档Markdownhttps://apizero.cn/aidocs/ocr-taxi-invoice/raw.md文档页面https://apizero.cn/aidocs/ocr-taxi-invoice