轮询跟踪更新
使用 GET /tracking/{id} 以统一格式获取实时发货跟踪数据。本指南涵盖轮询流程、如何解读跟踪状态，以及构建客户通知的模式。
获取跟踪数据
使用标签创建响应中的 id：
curl https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
-H "Authorization: Bearer YOUR_API_TOKEN"
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"trackingNumber": "YT2503010001CN",
"tag": "InTransit",
"subtag": "InTransit_001",
"subtagMessage": "In transit",
"slug": "yunexpress",
"checkpoints": [
{
"checkpointTime": "2026-03-17T08:15:00Z",
"city": "Los Angeles",
"state": "CA",
"countryRegion": "US",
"location": "LAX Distribution Center",
"message": "Arrived at destination country",
"tag": "InTransit",
"subtag": "InTransit_001",
"subtagMessage": "In transit",
"slug": "yunexpress"
},
{
"checkpointTime": "2026-03-16T02:30:00Z",
"city": "Shenzhen",
"state": "Guangdong",
"countryRegion": "CN",
"location": null,
"message": "Departed from sorting center",
"tag": "InTransit",
"subtag": "InTransit_001",
"subtagMessage": "In transit",
"slug": "yunexpress"
},
{
"checkpointTime": "2026-03-15T10:30:00Z",
"city": "Tokyo",
"state": "Tokyo",
"countryRegion": "JP",
"location": null,
"message": "Shipment information received",
"tag": "InfoReceived",
"subtag": "InfoReceived_001",
"subtagMessage": "Shipment information received",
"slug": "yunexpress"
}
]
}
了解跟踪状态
使用顶层的 tag 字段来实现高级别的状态逻辑：
| Tag | 面向客户的含义 | 处理方式 |
|---|
Pending | 订单处理中 | 无需通知 |
InfoReceived | 发货信息已向物流商登记 | 通知：“您的订单已发货” |
InTransit | 包裹运输中 | 通知：“您的包裹正在运输中” |
Delivered | 包裹已送达 | 通知：“您的包裹已送达” |
Exception | 配送发生问题 | 通知：“您的配送发生问题”并进行调查 |
Cancelled | 发货已取消 | 内部处理 |
Unknown | 无法获取状态 | 无需通知 — 稍后重试 |
轮询模式
由于目前尚未提供 Webhook，请以合理的间隔轮询 GET /tracking/{id} 来检测状态变更。
推荐做法
async function pollTracking(labelId, token) {
let lastTag = null;
const interval = setInterval(async () => {
const response = await fetch(
`https://api.flexforward.com/tracking/${labelId}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
const tracking = await response.json();
if (tracking.tag !== lastTag) {
lastTag = tracking.tag;
await notifyCustomer(tracking); // Your notification logic
}
// Stop polling when shipment reaches a terminal state
if (['Delivered', 'Cancelled'].includes(tracking.tag)) {
clearInterval(interval);
}
}, 30 * 60 * 1000); // Every 30 minutes
}
轮询指南
| 发货阶段 | 建议间隔 |
|---|
Pending / InfoReceived | 每 4-6 小时 |
InTransit | 每 30-60 分钟 |
Delivered / Cancelled | 停止轮询 |
Exception | 解决前每 15-30 分钟 |
跟踪数据从物流商近乎实时获取。以低于 15 分钟的间隔轮询不太可能获得新数据，且会计入建议的速率限制（每秒 10 个请求）。
错误处理
| 状态码 | 含义 | 处理方式 |
|---|
| 200 | 已获取跟踪数据 | 处理 tag 和 checkpoints |
| 403 | 访问被拒 | 该标签属于其他账户 |
| 404 | 找不到标签 | 请确认标签 ID 是否正确 |
| 502 | 上游服务错误 | 使用指数退避重试 |
后续步骤