> ## 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.

# 核心概念

> Flex Forward API 的關鍵概念與心智模型

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

# 核心概念

本頁面說明 Flex Forward API 的關鍵概念 — 資源之間的關係、標籤的生命週期，以及追蹤資料如何在物流業者之間正規化。

## 資源

API 管理三種相關資源，全部透過**標籤 ID**（UUID）連結：

| 資源   | 端點                   | 說明                  |
| ---- | -------------------- | ------------------- |
| 標籤   | `POST /labels`       | 提交給物流業者的配送標籤請求      |
| 標籤文件 | `GET /labels/{id}`   | 標籤的可列印提單（PDF 或 PNG） |
| 追蹤   | `GET /tracking/{id}` | 標籤的即時配送追蹤資料         |

從 `POST /labels` 回傳的標籤 ID 是所有操作中使用的主鍵。沒有獨立的追蹤 ID — 追蹤始終透過標籤 ID 存取。

## 標籤生命週期

標籤會經歷以下狀態：

```mermaid theme={null}
stateDiagram-v2
    [*] --> Created : Courier accepts
    [*] --> Failed : Courier rejects
    Created --> DocumentAvailable : Label document ready
    DocumentAvailable --> TrackingActive : Courier scans package
    TrackingActive --> Delivered : Shipment delivered
    TrackingActive --> Exception : Issue during transit
```

<Steps>
  <Step title="已建立">
    標籤請求已被物流業者接受。回應包含 `courierOrderNumber`、`courierTrackingNumber` 和標籤 `id`。標籤文件可供取得。
  </Step>

  <Step title="文件可用">
    可透過 `GET /labels/{id}` 下載提單的 PDF 或 PNG。列印並貼附在貨件上。文件 URL 為永久性，不會過期。支援的格式為 PDF 和 PNG。
  </Step>

  <Step title="追蹤進行中">
    物流業者掃描包裹後，可透過 `GET /tracking/{id}` 取得追蹤資料。追蹤資料從物流業者近即時取得。追蹤狀態會經過 `InfoReceived`、`InTransit`、`Delivered` 等階段。正規化的狀態標籤可能會隨著額外物流業者資料的取得而演進。
  </Step>
</Steps>

如果物流業者拒絕請求，標籤會以 `status: failed` 保存，並包含物流業者的錯誤詳情。詳情請參閱[錯誤處理](/zh-Hant/error-handling#下游物流業者錯誤502)。

## 追蹤狀態模型

追蹤資料使用基於業界標準的統一狀態模型。每個追蹤回應包含頂層的 `tag` 和 `subtag`，以及代表個別追蹤事件的 `checkpoints` 陣列。

### 狀態標籤

| 標籤             | 含義                    |
| -------------- | --------------------- |
| `Pending`      | 標籤已建立但尚未被物流業者接收       |
| `InfoReceived` | 物流業者已接收配送資訊           |
| `InTransit`    | 貨件運送中                 |
| `Delivered`    | 貨件已送達                 |
| `Exception`    | 運送期間發生問題（如：派送失敗、海關扣留） |
| `Cancelled`    | 配送已取消                 |
| `Unknown`      | 無法判定狀態                |

`subtag` 欄位提供更細緻的粒度（如 `InTransit_001`、`Exception_002`）。高階狀態邏輯使用 `tag`，詳細狀態顯示使用 `subtag`。

### 檢查點

每個檢查點代表一個追蹤事件：

```json theme={null}
{
  "checkpointTime": "2026-03-15T14:30:00Z",
  "city": "Tokyo",
  "state": "Tokyo",
  "countryRegion": "JP",
  "location": null,
  "message": "Departed from sorting facility",
  "tag": "InTransit",
  "subtag": "InTransit_001",
  "subtagMessage": "In transit",
  "slug": "yunexpress"
}
```

檢查點以最新事件排在最前面（反向時間順序）。最早的事件出現在陣列的最後。

## 物流業者正規化

每個物流業者都有自己的 API 格式、狀態碼和錯誤慣例。Flex Forward 正規化了這些差異：

* **統一請求格式** — 無論物流業者如何，都提交相同的 JSON 結構。物流業者特定的細節在內部處理。
* **統一回應格式** — 接收包含 `id`、`status`、`courierOrderNumber`、`courierTrackingNumber` 和（失敗時）`error` 的一致標籤回應。
* **統一追蹤** — 不同物流業者的追蹤事件對映到相同的狀態標籤分類體系和檢查點格式。

這意味著您的整合程式碼不需要處理物流業者特定的邏輯。當新的物流業者啟用時，您現有的整合無需修改即可運作。

## 物流業者與產品代碼

每個標籤請求需要 `courier` 代碼和 `productCode`。呼叫 [`GET /couriers`](/zh-hant/api-reference/couriers/list-couriers) 以列出您帳戶可用的有效物流業者代碼，然後在建立標籤時將其中一個返回的 `code` 值作為 `courier` 傳入。

| 物流業者       | 代碼           | 產品代碼      | 說明     |
| ---------- | ------------ | --------- | ------ |
| YunExpress | `yunexpress` | `HKMUZXR` | 標準跨境電商 |

選擇物流業者後，使用該物流業者代碼呼叫 [`GET /products`](/zh-hant/api-reference/products/list-products)，以列出您的配送路線可用的產品代碼。`serviceCode` 欄位為可選，在可用時啟用特定的服務等級。

## 地址參考資料

地址欄位需要標準化的代碼：

* **`countryCode`** — ISO 3166-1 alpha-2 國家代碼（如 `US`、`JP`、`CN`、`GB`、`DE`）
* **`state`** — 州或省代碼，對於需要州級地址的國家為必填（如美國的 `CA`、`NY`、`TX`）

<Note>
  如需完整的美國州代碼列表，請參閱 [州代碼參考](https://apidocs.returnhelper.com/reference/supported-states)。
</Note>

## 整合流程

典型的整合順序：

```
1. 身份驗證      →  在所有請求中包含 Bearer 令牌
2. 建立標籤      →  POST /labels  →  接收標籤 ID + 追蹤號碼
3. 取得文件      →  GET /labels/{id}  →  下載 PDF/PNG
4. 追蹤貨件      →  GET /tracking/{id}  →  輪詢狀態更新
```

三個 GET 操作都使用從最初 `POST /labels` 呼叫回傳的相同標籤 `id`。不需要管理文件和追蹤的獨立識別碼。

<Note>
  追蹤資料從物流業者即時取得。對於尚未被物流業者掃描的貨件，追蹤回應可能會回傳無檢查點的 `Pending` 或 `InfoReceived` 狀態。
</Note>