> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 環境

> 正式環境與開發環境的詳細資訊

<Note>
  此頁面由英文翻譯而成。[英文版](/introduction)為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。
</Note>

# 環境

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

## 可用環境

| 環境 | 基礎 URL                            | 物流業者連接   |
| -- | --------------------------------- | -------- |
| 正式 | `https://api.flexforward.com`     | 正式物流業者服務 |
| 開發 | `https://sandbox.flexforward.com` | 物流業者沙盒服務 |

所有請求必須使用 HTTPS。透過 HTTP 發送的請求將被拒絕。

## 開發環境

開發環境連接至物流業者的沙盒服務（如 YunExpress 沙盒）。適用於：

* 在不建立實際配送的情況下測試您的整合
* 驗證請求格式和回應處理
* 開發錯誤處理和重試邏輯

<Note>
  沙盒物流業者服務可能回傳模擬的追蹤資料和標籤文件。回應時間和可用的追蹤狀態可能與正式環境不同。
</Note>

### 沙盒測試資料

開發環境支援產生可預測追蹤回應的測試值。使用這些來驗證您的整合能正確處理不同的配送結果：

| 收件人郵遞區號 | 模擬追蹤結果                |
| ------- | --------------------- |
| `90001` | `Delivered` — 配送正常完成  |
| `90002` | `Exception` — 發生派送例外  |
| `90003` | `InTransit` — 貨件持續運送中 |
| `90004` | `Cancelled` — 配送已取消   |

<Note>
  測試值和模擬回應可能會變更。如需最新的沙盒測試資料，請聯繫 Flex Forward 團隊。
</Note>

## 認證資訊分離

每個環境請使用個別的 API 令牌。請勿在開發環境中使用正式認證資訊，反之亦然。

<Warning>
  正式令牌可存取正式的物流業者服務。發送請求前請務必確認您的目標環境。
</Warning>

## 令牌最佳實踐

* 將令牌存放在環境變數或密鑰管理器中
* 切勿在原始碼中寫死令牌或將其提交至版本控制
* 每個環境使用個別令牌，以防止開發期間意外發送正式請求
* 定期輪換令牌

令牌使用方式和錯誤回應的詳細資訊請參閱[身份驗證](/zh-Hant/authentication)。

## 速率限制

目前未強制實施速率限制。建議每個帳戶將請求量控制在 **每秒 10 個請求** 以下。速率限制標頭（`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`）目前不包含在回應中。

如果未來引入速率限制，將透過[變更記錄](/zh-Hant/changelog)提前通知。如需針對高吞吐量整合討論容量規劃，請聯繫 Flex Forward 團隊 [flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com)。

## 上線檢查清單

從開發環境切換至正式環境前：

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

## HTTPS 要求

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