此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。
輪詢追蹤更新
使用GET /tracking/{id} 以統一格式取得即時出貨追蹤資料。本指南涵蓋輪詢流程、如何解讀追蹤狀態，以及建立客戶通知的模式。
取得追蹤資料
使用標籤建立回應中的id：
curl https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
-H "x-rr-apikey: YOUR_API_KEY" \
-H "x-rr-apitoken: YOUR_API_TOKEN"
const response = await fetch(
'https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
{ headers: { 'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN' } }
);
const tracking = await response.json();
console.log(tracking.tag); // High-level status: InTransit, Delivered, etc.
import requests
response = requests.get(
'https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
headers={'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN'}
)
tracking = response.json()
print(tracking['tag']) # High-level status: InTransit, Delivered, etc.
回應
200 OK
{
"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, apiKey, apiToken) {
let lastTag = null;
const interval = setInterval(async () => {
const response = await fetch(
`https://api.flexforward.com/tracking/${labelId}`,
{ headers: { 'x-rr-apikey': apiKey, 'x-rr-apitoken': apiToken } }
);
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 | 上游服務錯誤 | 使用指數退避重試 |
後續步驟
核心概念
追蹤狀態標籤和檢查點結構的完整參考。
冪等性與重試
處理暫時性故障的安全重試模式。