輪詢追蹤更新
使用 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 | 上游服務錯誤 | 使用指數退避重試 |
後續步驟