​

變更記錄

Flex Forward API 與文件的重要變更按時間倒序列出。

---

​

2026 年 10 月

​

API 變更

• EU 商品識別碼： shipment.parcels[].items[].attributes.productIdentifiers 說明報關申報所需的商品識別碼。寄往 EU、摩納哥、法國海外地區或北愛爾蘭（郵遞區號以 BT 開頭）的每件商品，都必須提供 mpid、nspid 和 spid，且每個欄位均為代碼清單。寄往其他地區時，這些欄位皆為選填。說明也列出代碼限制，包括 spid 不得留白，且只有商品沒有條碼時才可使用 Y081。

---

​

2026 年 9 月

​

API 變更

• 端點： GET /orders/{orderId} — 取得一筆訂單及其建立標籤時提供的物流業者詳細資料。回應包含訂單的運輸階段（status）、商業 exceptionState、物流業者識別碼、申報的包裹重量與尺寸，以及向物流業者送出時的 error；另包含您送出的訂單編號、報關識別碼、服務選項與物流業者選項。請將 POST /labels 回傳的標籤 id 作為 {orderId}；此端點僅接受 UUID，不接受 customerOrderNumber。它與僅回傳標籤文件的 GET /labels/{id} 互為補充。
• 冪等性： 以不同請求本文重複使用 idempotencyKey 會回傳 409 IDEMPOTENCY_CONFLICT。使用相同金鑰與本文的請求會重放已儲存的結果。沒有儲存請求指紋的舊記錄，會維持原有的重放行為。
• 標籤格式： label.format 支援 PDF 和 PNG，省略時預設為 PDF。文件回應會以小寫 pdf 或 png 回報所選格式。
• 客戶訂單編號： 指定值必須包含 1–40 個 ASCII 英文字母、數字、- 或 _，區分大小寫，且在帳戶內唯一。省略時由系統自動產生。FlexForward 會將 {clientCode}-{customerOrderNumber} 傳給物流業者，作為其客戶參考，並在支援的情況下列印於標籤上。
• 商品價值： unitPrice.amount 必須至少為 0.01。免費贈品、樣品與促銷贈品也必須以 0.01 或以上的名目價值申報，不可為 0。unitPrice.currency 僅接受 USD。省略幣別值也視為 USD。
• IOSS 處理： customs.taxIds.ioss 現在明確說明，若提供非空白值，系統會先去除前後空白後再使用。若此欄位省略或為空白，且目的地為 EU 課稅國家，則會自動套用 FlexForward 的預設 IOSS 代碼。您在 IOSS registrations 下註冊的代碼，除非在請求中送出，否則不會自動套用。套用 FlexForward 的預設代碼會產生費用，因為系統會連同運費一併入帳 VAT 預付款與服務費；若您在此提供自己的代碼，則不會收費。

​

文件修正

• 在核心概念的資源表與整合流程中新增訂單資源與 GET /orders/{orderId}。
• 更新國際出貨指南，以反映 unitPrice.amount 的最小值為 0.01，並說明不接受價值為 0 的報關申報。
• 釐清 IOSS 判定與計費方式：若提供 customs.taxIds.ioss 值則會保留該值；若此欄位省略或為空白，且目的地為 EU 課稅國家，則會自動套用 FlexForward 的預設 IOSS 代碼；此外，預設代碼路徑會收費，而提供自己的代碼則不會收費。

​

文件維護

• 新增檢查，確保生成的 API 文件與來源保持一致，並審查相關指南更新。

---

​

2026 年 7 月

​

變更

• 文件 / OpenAPI： 更正公開身份驗證說明。客戶整合必須同時傳送 x-rr-apikey 與 x-rr-apitoken。已移除 Bearer 令牌範例與公開 OpenAPI 的 bearerAuth 方案作為客戶端身份驗證方式。
• 身份驗證： API 認證資訊改為從 Return Helper User Portal 的 Settings → Signing Key and API Token 取得，取代以往以電子郵件申請令牌的流程。

---

​

2026 年 6 月

​

Added

• 端點： GET /couriers — 列出您帳戶可用的物流業者代碼。使用返回的 code 值作為建立標籤或列出物流業者產品時的 courier。

---

​

2026 年 5 月

​

Added

• 端點： GET /products — 列出物流業者可用的配送產品。使用返回的產品代碼建立標籤。
• 認證： 記載 Flex Forward 請求使用 API 金鑰 + 令牌標頭認證（x-rr-apikey / x-rr-apitoken）。
• 端點： GET /labels/{id} — 現在支援以逗號分隔的識別碼（標籤 UUID 或客戶訂單編號）進行批次取得。找不到或失敗的標籤會從回應中省略。
• 回應： GET /labels/{id} 回應現在包含 customerOrderNumber 欄位。

​

Changed

• service.shipperAccountId 現在為選填欄位。省略時，系統會使用您帳戶針對該物流業者的預設配送帳戶來建立標籤。仍然傳送此欄位的請求可繼續正常運作。
• API 規格： 為所有端點新增詳細描述、範例和操作 ID。
• 文件： 改善快速入門指南、請求範例及其他修正。

---

​

v1.0.0

Flex Forward API 與開發者文件的首次公開發佈。

​

Added

• 端點： POST /labels（建立配送標籤）、GET /labels/{id}（取得標籤文件 URL）、GET /tracking/{id}（取得配送追蹤）
• 正式物流業者： YunExpress（全球跨境電商配送路線）
• 冪等性： 透過 idempotencyKey 內建標籤建立重複防止功能
• 統一追蹤： 正規化狀態標籤（Pending、InfoReceived、InTransit、Delivered、Exception、Cancelled、Unknown）以及跨所有物流業者的結構化檢查點格式
• 認證： API 金鑰 + 令牌標頭認證（x-rr-apikey / x-rr-apitoken），正式與開發環境使用獨立認證資訊
• 文件： 快速入門指南、認證參考、錯誤處理指南、冪等性與重試模式、環境詳情、核心概念、版本管理政策、常見問題