> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 輪詢追蹤更新

> 如何取得並使用正規化追蹤資料進行客戶通知

<Note>
  此頁面由英文翻譯而成。[英文版](/introduction)為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。
</Note>

# 輪詢追蹤更新

使用 `GET /tracking/{id}` 以統一格式取得即時出貨追蹤資料。本指南涵蓋輪詢流程、如何解讀追蹤狀態，以及建立客戶通知的模式。

## 取得追蹤資料

使用標籤建立回應中的 `id`：

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
    { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
  );
  const tracking = await response.json();
  console.log(tracking.tag); // High-level status: InTransit, Delivered, etc.
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.flexforward.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
  )
  tracking = response.json()
  print(tracking['tag'])  # High-level status: InTransit, Delivered, etc.
  ```
</CodeGroup>

### 回應

```json 200 OK theme={null}
{
  "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}` 來偵測狀態變更。

### 建議做法

```javascript theme={null}
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 分鐘 |

<Note>
  追蹤資料從物流業者近乎即時取得。以低於 15 分鐘的間隔輪詢不太可能獲得新資料，且會計入建議的速率限制（每秒 10 個請求）。
</Note>

## 錯誤處理

| 狀態碼 | 意義      | 處理方式                     |
| --- | ------- | ------------------------ |
| 200 | 已取得追蹤資料 | 處理 `tag` 和 `checkpoints` |
| 403 | 存取被拒    | 該標籤屬於其他帳戶                |
| 404 | 找不到標籤   | 請確認標籤 ID 是否正確            |
| 502 | 上游服務錯誤  | 使用指數退避重試                 |

## 後續步驟

<CardGroup cols={2}>
  <Card title="核心概念" icon="book" href="/zh-Hant/core-concepts#追蹤狀態模型">
    追蹤狀態標籤和檢查點結構的完整參考。
  </Card>

  <Card title="冪等性與重試" icon="rotate" href="/zh-Hant/idempotency-and-retries">
    處理暫時性故障的安全重試模式。
  </Card>
</CardGroup>