跳轉到主要內容

​
核心概念

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

​
資源

API 管理三種相關資源，全部透過標籤 ID（UUID）連結：
資源端點說明
標籤POST /labels提交給物流業者的配送標籤請求
標籤文件GET /labels/{id}標籤的可列印提單（PDF 或 PNG）
追蹤GET /tracking/{id}標籤的即時配送追蹤資料
從 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 陣列。

​
狀態標籤

標籤含義
Pending標籤已建立但尚未被物流業者接收
InfoReceived物流業者已接收配送資訊
InTransit貨件運送中
Delivered貨件已送達
Exception運送期間發生問題（如：派送失敗、海關扣留）
Cancelled配送已取消
Unknown無法判定狀態
subtag 欄位提供更細緻的粒度（如 InTransit_001、Exception_002）。高階狀態邏輯使用 tag，詳細狀態顯示使用 subtag。

​
檢查點

每個檢查點代表一個追蹤事件： 
{
  "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。可用的物流業者和產品代碼在帳戶建置時設定。
物流業者代碼產品代碼說明
YunExpressyunexpressYEXP01標準跨境電商
serviceCode 欄位為可選，在可用時啟用特定的服務等級。如需了解您的物流路線可用的產品代碼和服務選項，請聯繫 Flex Forward 團隊。

​
地址參考資料

地址欄位需要標準化的代碼：
  • countryCode — ISO 3166-1 alpha-2 國家代碼（如 US、JP、CN、GB、DE）
  • state — 州或省代碼，對於需要州級地址的國家為必填（如美國的 CA、NY、TX）
支援的國家代碼和美國州代碼的完整參考將在未來版本中提供。

​
整合流程

典型的整合順序： 
1. 身份驗證      →  在所有請求中包含 Bearer 令牌
2. 建立標籤      →  POST /labels  →  接收標籤 ID + 追蹤號碼
3. 取得文件      →  GET /labels/{id}  →  下載 PDF/PNG
4. 追蹤貨件      →  GET /tracking/{id}  →  輪詢狀態更新
三個 GET 操作都使用從最初 POST /labels 呼叫回傳的相同標籤 id。不需要管理文件和追蹤的獨立識別碼。
追蹤資料從物流業者即時取得。對於尚未被物流業者掃描的貨件，追蹤回應可能會回傳無檢查點的 Pending 或 InfoReceived 狀態。