泛识物流识别 · API 文档

面向货代与跨境物流场景的 AI 识别服务。覆盖 DHL / UPS / FedEx 等多渠道商业发票与运单图片的结构化识别。

所有调用走 HTTPS 协议；商用环境必须使用 HTTPS。开发期可通过 http://localhost:5102 测试。

认证

对外 API Key 只可调用识别主接口，必须携带 X-API-Key 请求头。浏览器端在线识别使用登录 Cookie 会话。

方式说明
X-API-Key: hinv_xxxxxAPI 密钥，仅创建时显示一次。请妥善保管。
Cookie hinv_session网页登录后由服务端设置；HttpOnly + SameSite=Lax。

计费与积分

主识别接口

POST /recognize-agent-channel-stream

上传发票或运单图片，返回 SSE 流式响应，包含处理阶段进度与最终结构化结果。

请求

Header必填说明
X-API-Key是API 密钥（hinv_ 前缀）
Content-Type是multipart/form-data; boundary=...
Query必填说明
channel否通道类型：DHL / UPS / FED，留空则自动判断
Form必填说明
file是二进制图片，PNG / JPEG / WebP，建议 < 8MB

响应（SSE）

event: data
data: {"stage":"preprocess","message":"方向纠正完成"}

data: {"stage":"crop","regions":["sender","recipient","items"]}

data: {"stage":"extract","progress":"sender ok"}

data: {"result":{
  "sender": {"name":"...","address":"..."},
  "recipient": {"name":"...","address":"..."},
  "items": [{"description":"...","quantity":1,"unitPrice":10,"subTotal":10}],
  "cargoValue": {"totalValue":10,"currency":"USD"},
  "logistics": {"trackingNumber":"...","weight":"..."}
}}

示例

curl -N -X POST "https://your-host/recognize-agent-channel-stream?channel=DHL" \
  -H "X-API-Key: hinv_xxxxxxxxxxxx" \
  -F "file=@invoice.jpg"

错误码

状态码说明
200成功（流中 result 即为最终结构化结果）
400请求体不合法，如缺少 file
401缺少或无效的 X-API-Key
402积分余额不足
500识别内部错误（流中以 error 事件返回）

账号接口

POST /api/saas/auth/register

用户自助注册。成功自动登录并设置会话 Cookie。

curl -X POST https://your-host/api/saas/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"至少8位密码","displayName":"可选"}'

POST /api/saas/auth/login

邮箱密码登录。

POST /api/saas/auth/logout

登出并清空会话。

GET /api/saas/auth/me

返回当前登录用户信息（id / email / role / creditBalance 等）。

API 密钥接口

GET /api/saas/keys

列出当前登录用户全部密钥（不含明文）。

POST /api/saas/keys

创建密钥。明文仅在响应里返回一次，务必保存。

curl -X POST https://your-host/api/saas/keys \
  -H "X-API-Key: hinv_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"生产环境"}'

POST /api/saas/keys/{id}/toggle

启用或停用密钥。请求体 {"enabled":true|false}。

PUT /api/saas/keys/{id}/name

重命名密钥。请求体 {"name":"新名称"}。

DELETE /api/saas/keys/{id}/hard

硬删除密钥（不可恢复）。

用量与兑换

GET /api/saas/keys/overview

数据看板：积分余额、累计调用、今日调用、有效密钥、7 天每日柱图。

GET /api/saas/keys/logs

使用日志分页。

Query默认说明
page1页码
pageSize20每页大小（最大 200）
status-按状态过滤：success / failed
endpoint-按接口路径包含子串过滤

POST /api/saas/keys/credits/redeem

兑换码兑换积分。请求体 {"code":"fsw_xxxx"}。返回 credits（本次获得）和 creditBalance（当前余额）。

错误码总览

状态码含义
200成功
400请求参数缺失或格式错误
401未登录或 API 密钥无效/已吊销/已停用
402积分余额不足
403需要管理员权限
404资源不存在
409资源冲突（如邮箱已被注册）
500服务器内部错误

SDK 示例

Python（requests）

import requests

API = "https://your-host"
KEY = "hinv_xxxxxxxxxxxx"

with open("invoice.jpg", "rb") as f:
    resp = requests.post(
        f"{API}/recognize-agent-channel-stream?channel=DHL",
        headers={"X-API-Key": KEY},
        files={"file": ("invoice.jpg", f, "image/jpeg")},
        stream=True,
    )

import json
for line in resp.iter_lines():
    if line.startswith(b"data:"):
        payload = json.loads(line[5:].strip())
        if "result" in payload:
            print(json.dumps(payload["result"], ensure_ascii=False, indent=2))

Node.js (axios)

const axios = require('axios');
const fs = require('fs');

const API = 'https://your-host';
const KEY = 'hinv_xxxxxxxxxxxx';

const form = new FormData();
form.append('file', fs.createReadStream('invoice.jpg'));

axios.post(`${API}/recognize-agent-channel-stream?channel=DHL`, form, {
  headers: { 'X-API-Key': KEY, ...form.getHeaders() },
  responseType: 'stream'
}).then(async resp => {
  for await (const chunk of resp.data) {
    const lines = chunk.toString().split('\n').filter(l => l.startsWith('data:'));
    for (const ln of lines) {
      const obj = JSON.parse(ln.slice(5).trim());
      if (obj.result) console.log(JSON.stringify(obj.result, null, 2));
    }
  }
});

限额与计费

最后更新于 2026-08 · 泛识物流识别