TrackFlow API 接入文档

基本信息

API Base URL

https://tracking.rw2.cc/api

返回格式

JSON，UTF-8 编码

处理方式

提交接口异步返回批次，使用批次 ID 轮询结果

单次上限

最多 10000 个有效运单号，重复号码自动去重

生产环境建议显式传入自己的 apikey，不要把 API key 写入公开代码仓库或日志。

第一步：提交查询

curl -X POST 'https://tracking.rw2.cc/api/track' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "YOUR_API_KEY",
    "tracking_numbers": ["9400111899223856928498", "1Z999AA10123456784"],
    "carrier": "auto",
    "mode": "manual"
  }'

成功返回 HTTP 202，请保存返回的 batch.id。

{
  "batch": {
    "id": "BATCH_ID",
    "status": "processing",
    "total_count": 2,
    "completed_count": 0,
    "failed_count": 0
  }
}

第二步：轮询结果

curl 'https://tracking.rw2.cc/api/batches/BATCH_ID?include_items=1&items_limit=80&items_offset=0&category=all' \
  -H 'Accept: application/json'

当 batch.status 为 pending 或 processing 时继续轮询，建议间隔 1-3 秒；状态为 completed 或 failed 时停止。

提交接口

POST/api/track

提交一批物流查询任务。

字段	类型	必填	说明
`tracking_numbers`	array/string	是	运单号数组，或使用换行、逗号、分号分隔的字符串。只保留 8-40 位字母数字组合。
`apikey`	string	否	省略或为空时使用服务端默认 key。生产集成建议传入自己的 key。
`carrier`	string	否	`auto`、`usps`、`ups`、`fedex`、`dhl`、`auspost`，默认 `auto`。
`mode`	string	否	网页使用 `manual` 或 `realtime`。
`bypass_cache`	boolean	否	是否跳过缓存重新查询，实时查询使用 `true`。
`batch_id`	UUID	否	追加到仍在提交中的批次，必须与创建批次的 key 匹配。
`submission_complete`	boolean	否	是否完成当前批次提交，默认 `true`。

超过 10000 条：追加到同一批次

第一次提交最多 10000 条，传 submission_complete=false。
保存响应中的 batch.id。
后续请求传相同的 batch_id，每次最多 10000 条。
最后一次传 submission_complete=true。

curl -X POST 'https://tracking.rw2.cc/api/track' \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "YOUR_API_KEY",
    "batch_id": "BATCH_ID_FROM_FIRST_RESPONSE",
    "tracking_numbers": ["NUMBER_00000003", "NUMBER_00000004"],
    "carrier": "auto",
    "mode": "manual",
    "submission_complete": true
  }'

批次结果

GET/api/batches/{batch_id}

查询批次状态和结果。

参数	默认值	说明
`include_items`	true	是否返回结果明细。
`include_tracking_numbers`	false	是否返回完整运单号数组。历史批次回填查询框时使用 true。
`items_limit`	80	本次明细数量，最大 500。
`items_offset`	0	明细偏移量，用于分页。
`category`	all	`all`、`delivered`、`in_transit`、`label_created`、`exception`、`stale`、`no_tracking`。

batch.items[] 中包含 tracking_number、carrier、status、error 和 snapshot。快照包含英文状态、中文状态、最新位置、轨迹时间、签收标记、警告信息和轨迹事件。

如果需要一次返回完整运单号：

GET /api/batches/{batch_id}?include_items=0&include_tracking_numbers=1

其他接口

GET /api/health

健康检查，返回 {"status":"ok"}。

GET /api/auth/status

使用 ?apikey=YOUR_API_KEY 查询剩余额度。

GET /api/history

使用 ?apikey=YOUR_API_KEY 查询最近 100 个历史批次。

GET /api/export

使用 ?batch_id=BATCH_ID 或 batch_ids[]=ID 导出 Excel，可选 with_first_event=1 导出首条物理轨迹。

修改批次名称

PATCH/api/batches/{batch_id}/note

{"apikey":"YOUR_API_KEY","note":"供应商 A - 10 月 10 日"}

错误处理

状态码	含义
202	查询已接受，结果异步处理。
200	查询成功。
403	API key 无权访问该批次。
409	批次已经结束，不能继续追加。
422	请求参数错误，或没有有效运单号。
429	访客额度或请求频率限制。
502	上游承运商接口暂时失败。

{
  "message": "The given data was invalid.",
  "errors": {
    "tracking_numbers": ["The tracking numbers field is required."]
  }
}

AI Agent 接入

将以下地址作为 Markdown 文档源提供给 AI 或代码生成工具：

https://tracking.rw2.cc/api-integration.md

调用 POST /api/track 提交运单号。
记录响应中的 batch.id。
每隔 1-3 秒调用 GET /api/batches/{batch_id}。
读取 batch.items 和 batch.items_pagination。
当状态为 completed 或 failed 时结束轮询。

不要把 API key 写入日志、公开代码仓库或返回给不可信的客户端。