此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。
核心概念
本頁面說明 Flex Forward API 的關鍵概念 — 資源之間的關係、標籤的生命週期，以及追蹤資料如何在物流業者之間正規化。資源
API 管理四種相關資源，全部透過標籤 ID（UUID）連結：
從
POST /labels 回傳的標籤 ID 是所有操作中使用的主鍵。GET /labels/{id} 和 GET /tracking/{id} 都接受標籤 UUID 或您的 customerOrderNumber 作為路徑參數。沒有獨立的追蹤 ID。GET /orders/{orderId} 僅接受標籤 UUID；訂單與標籤共用同一個 id。
物流業者的識別碼（
courierOrderNumber、courierTrackingNumber）不能作為 {id} 使用。傳入物流業者追蹤號碼會回傳 404 Label not found。請保存標籤 UUID，或使用您自己的 customerOrderNumber。客戶訂單編號
order.customerOrderNumber 在建立標籤時為選填。若提供，必須在帳戶內唯一，長度為 1–40 個字元，且只能使用 ASCII 英文字母（A–Z、a–z）、數字、-、_。此值區分大小寫。空格、逗號及其他字元會遭拒絕。
若省略此欄位，API 會產生訂單編號。請保存回傳的 customerOrderNumber 或標籤 id；請勿假設產生的訂單編號會等於標籤 UUID。兩者皆可用於取得文件與追蹤資料。
FlexForward 會將 {clientCode}-{customerOrderNumber} 作為客戶參考傳送給物流業者。物流業者會在支援的情況下將該參考列印於標籤上。查詢時請使用 API 回傳、未加前綴的 customerOrderNumber。
標籤生命週期
標籤會經歷以下狀態：1
已建立
標籤請求已被物流業者接受。回應包含標籤
id 和 courierOrderNumber。courierTrackingNumber 此時通常為 null，由末端配送業者稍後分配。標籤文件可供取得。2
文件可用
可透過
GET /labels/{id} 下載文件。建立時可將 label.format 設為 PDF 或 PNG，省略時使用 PDF。回應中的 labelFormat 會是 pdf 或 png。文件 URL 為短期連結，需要時請重新取得。3
追蹤進行中
物流業者掃描包裹後，可透過
GET /tracking/{id} 取得追蹤資料。追蹤資料從物流業者近即時取得。追蹤狀態會經過 InfoReceived、InTransit、Delivered 等階段。正規化的狀態標籤可能會隨著額外物流業者資料的取得而演進。status: failed 保存，並包含物流業者的錯誤詳情。詳情請參閱錯誤處理。
追蹤狀態模型
追蹤資料使用基於業界標準的統一狀態模型。每個追蹤回應包含頂層的tag 和 subtag，以及代表個別追蹤事件的 checkpoints 陣列。
狀態標籤
subtag 欄位提供更細緻的粒度（如 InTransit_001、Exception_002）。高階狀態邏輯使用 tag，詳細狀態顯示使用 subtag。
檢查點
每個檢查點代表一個追蹤事件：物流業者正規化
每個物流業者都有自己的 API 格式、狀態碼和錯誤慣例。Flex Forward 正規化了這些差異：- 統一請求格式 — 無論物流業者如何，都提交相同的 JSON 結構。物流業者特定的細節在內部處理。
- 統一回應格式 — 接收包含
id、status、courierOrderNumber、courierTrackingNumber和（失敗時）error的一致標籤回應。 - 統一追蹤 — 不同物流業者的追蹤事件對映到相同的狀態標籤分類體系和檢查點格式。
物流業者與產品代碼
每個標籤請求需要courier 代碼和 productCode。呼叫 GET /couriers 以列出有效的物流業者目錄，然後在建立標籤時將其中一個返回的 code 值作為 courier 傳入。
選擇物流業者後，使用該物流業者代碼呼叫
GET /products，以列出該物流業者的有效產品代碼。serviceCode 欄位為可選，在可用時啟用特定的服務等級。
此目錄為全域性質。代碼列示於目錄中，並不代表您的帳戶已針對該物流業者或路線啟用；若您的帳戶尚未設定該物流業者的配送帳戶，POST /labels 將回傳 404（Shipping account not found）。
地址參考資料
地址欄位需要標準化的代碼：countryCode— ISO 3166-1 alpha-2 國家代碼（如US、JP、CN、GB、DE）state— 州或省代碼，對於需要州級地址的國家為必填（如美國的CA、NY、TX）
如需完整的美國州代碼列表，請參閱 州代碼參考。
整合流程
典型的整合順序：POST /labels 呼叫回傳的相同標籤 id。不需要管理文件、追蹤和訂單的獨立識別碼。
追蹤資料從物流業者即時取得。對於尚未被物流業者掃描的貨件，追蹤回應可能會回傳無檢查點的
Pending 或 InfoReceived 狀態。