众森企服票据识别API 开发文档

基于阿里云百炼平台，支持 JPG/PNG/PDF/OFD/XML，返回结构化发票数据。

基础信息

基础URLhttp://localhost:3000/api
认证方式API Key（表单字段 api_key）
支持格式JPG、PNG、PDF、OFD、XML
最大文件大小10MB
每日配额默认 1000 次/Key/日（超限返回 429）

一键导入集合

直接导入到 Postman 或 Insomnia，即可调试所有接口。

下载 Postman Collection 下载 Insomnia Collection

接口与示例

1) 票据识别 POST /api/v1/recognize

curl -X POST "http://localhost:3000/api/v1/recognize" \
-F "file=@invoice.pdf" \
-F "api_key=zs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2) 查询状态 GET /api/v1/status/{requestId}

curl -X GET "http://localhost:3000/api/v1/status/uuid-string?api_key=zs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

3) 支持格式 GET /api/v1/formats

curl -X GET "http://localhost:3000/api/v1/formats"

JavaScript 示例

const fd=new FormData();
fd.append('file',file);
fd.append('api_key','zs_xxx');
fetch('/api/v1/recognize',{method:'POST',body:fd}).then(r=>r.json()).then(console.log);

Python 示例

import requests
r=requests.post('http://localhost:3000/api/v1/recognize',files={'file':open('invoice.pdf','rb')},data={'api_key':'zs_xxx'})
print(r.json())

错误码与限流说明

错误码含义说明
400请求参数错误缺少 file 或 api_key
401API Key无效格式错误或不存在
413文件过大超过 10MB
415文件格式不支持仅支持 JPG/PNG/PDF/OFD/XML
429请求过于频繁超过每日配额（默认1000）
500服务器内部错误后端异常
502百炼服务异常上游识别失败

PDF/OFD 处理策略

系统先尝试直传到百炼；若直传失败，自动以 Puppeteer 渲染第一页转为 PNG 再识别，避免系统级依赖。

最佳实践