Return Helper API
Return Helper 提供一套 API，用於端對端管理電子商務商品退貨流程，涵蓋退貨申請(Return Request)建立、退件運貨單(Return Shipment)追蹤、標籤生成及倉庫處理等各環節。此 API 僅供伺服器對伺服器整合使用。請勿直接從客戶端程式碼呼叫這些端點。
可用 API
User API — 供商家及合作夥伴管理退貨申請(Return Request)、退件運貨單(Return Shipment)、標籤、庫存及帳戶設定的認證端點。 Public API — 提供參考資料查詢的端點，包含服務類型、倉庫列表、狀態代碼及支援國家等查詢值。認證
所有 API 請求均需在請求標頭中提供 API 金鑰和 Token：- 登入 Return Helper 使用者入口網站。
- 前往 Settings → Signing Key and API Token。
- 您現有的金鑰與 Token 配對將顯示於此。您也可以在此生成新的配對。
使用者入口網站中的簽名金鑰、API Token 和 API Key
基礎 URL
沙箱環境
正式環境
冪等性(Idempotency)
對於改變狀態的請求（如建立退件運貨單(Return Shipment)、庫存等），請附上冪等性金鑰(Idempotency Key)，以防止在網路重試時產生重複操作。User-Agent 標頭
請附上User-Agent 標頭，以便 Return Helper 支援團隊在排查問題時識別您的整合方式：
OpenAPI 規格
完整的 API 規格以 OpenAPI 3.1 文件格式提供。您可以下載並直接匯入 Postman 或 Insomnia 等 API 客戶端，或使用 OpenAPI Generator 等工具生成客戶端 SDK。下載 OpenAPI 規格
openapi.json — OpenAPI 3.1錯誤處理
每個回應（無論成功或失敗）都使用統一的信封格式：correlationId 和 meta 同層）一併回傳，例如 getAllCountries 回傳 { correlationId, meta, countries: [...] }。在讀取業務資料前，請務必檢查 meta.errorCode——本 API 採用「軟性錯誤」慣例，驗證失敗會以 HTTP 200 回傳，並於 meta.status 標記為 400，同時填入 meta.errorCode。
失敗類型
驗證失敗範例
correlationId。Return Helper 客服在排查問題時會使用該 ID 追溯請求。
一般備註
- 所有
dateTime參數必須使用 ISO 8601 格式，否則 API 無法解析。 - 日期字串參數（例如
createToStr、createFromStr）也必須使用 ISO 8601 格式；時間部分將被忽略。 - API 回傳的所有時間戳均為 UTC 時間。