Skip to main content
此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。

​
核心概念

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

​
資源

API 管理三種相關資源，全部透過標籤 ID（UUID）連結： 從 POST /labels 回傳的標籤 ID 是所有操作中使用的主鍵。沒有獨立的追蹤 ID — 追蹤始終透過標籤 ID 存取。

​
標籤生命週期

標籤會經歷以下狀態：
1

已建立

標籤請求已被物流業者接受。回應包含 courierOrderNumber、courierTrackingNumber 和標籤 id。標籤文件可供取得。
2

文件可用

可透過 GET /labels/{id} 下載提單的 PDF 或 PNG。列印並貼附在貨件上。文件 URL 為永久性，不會過期。支援的格式為 PDF 和 PNG。
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 欄位為可選，在可用時啟用特定的服務等級。

​
地址參考資料

地址欄位需要標準化的代碼：
  • countryCode — ISO 3166-1 alpha-2 國家代碼（如 US、JP、CN、GB、DE）
  • state — 州或省代碼，對於需要州級地址的國家為必填（如美國的 CA、NY、TX）
如需完整的美國州代碼列表，請參閱 州代碼參考。

​
整合流程

典型的整合順序：
三個 GET 操作都使用從最初 POST /labels 呼叫回傳的相同標籤 id。不需要管理文件和追蹤的獨立識別碼。
追蹤資料從物流業者即時取得。對於尚未被物流業者掃描的貨件，追蹤回應可能會回傳無檢查點的 Pending 或 InfoReceived 狀態。