跳轉到主要內容

​
環境

Flex Forward API 提供兩個環境，分別用於正式營運和開發測試。

​
可用環境

環境基礎 URL物流業者連接
正式https://api.flexforward.com正式物流業者服務
開發https://sandbox.flexforward.com物流業者沙盒服務
所有請求必須使用 HTTPS。透過 HTTP 發送的請求將被拒絕。

​
開發環境

開發環境連接至物流業者的沙盒服務（如 YunExpress 沙盒）。適用於：
  • 在不建立實際配送的情況下測試您的整合
  • 驗證請求格式和回應處理
  • 開發錯誤處理和重試邏輯
沙盒物流業者服務可能回傳模擬的追蹤資料和標籤文件。回應時間和可用的追蹤狀態可能與正式環境不同。

​
沙盒測試資料

開發環境支援產生可預測追蹤回應的測試值。使用這些來驗證您的整合能正確處理不同的配送結果：
收件人郵遞區號模擬追蹤結果
90001Delivered — 配送正常完成
90002Exception — 發生派送例外
90003InTransit — 貨件持續運送中
90004Cancelled — 配送已取消
測試值和模擬回應可能會變更。如需最新的沙盒測試資料，請聯繫 Flex Forward 團隊。

​
認證資訊分離

每個環境請使用個別的 API 令牌。請勿在開發環境中使用正式認證資訊，反之亦然。
正式令牌可存取正式的物流業者服務。發送請求前請務必確認您的目標環境。

​
令牌最佳實踐

  • 將令牌存放在環境變數或密鑰管理器中
  • 切勿在原始碼中寫死令牌或將其提交至版本控制
  • 每個環境使用個別令牌，以防止開發期間意外發送正式請求
  • 定期輪換令牌
令牌使用方式和錯誤回應的詳細資訊請參閱身份驗證。

​
速率限制

目前未強制實施速率限制。建議每個帳戶將請求量控制在 每秒 10 個請求 以下。速率限制標頭（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset）目前不包含在回應中。 如果未來引入速率限制，將透過變更記錄提前通知。如需針對高吞吐量整合討論容量規劃，請聯繫 Flex Forward 團隊 [email protected]。

​
上線檢查清單

從開發環境切換至正式環境前：
  • 開發令牌已發放並測試完成
  • 正式令牌已獲 Flex Forward 團隊核准
  • 配送帳戶已設定正式物流業者
  • 在開發環境中標籤建立測試成功
  • 標籤文件取得已測試
  • 追蹤取得已測試
  • 冪等性行為已驗證（重複金鑰回傳相同結果）
  • 已實作所有狀態碼的錯誤處理
  • 所需物流業者和物流路線設定已確認

​
HTTPS 要求

所有 API 端點需要 TLS 1.2 或更高版本的 HTTPS。透過 HTTP 發送的請求將收到連線錯誤。