此頁面由 AI 自動翻譯。如有任何疑問或不一致之處，請以英文版本為準。
Return Helper API
Return Helper 提供一套 API，用於端對端管理電子商務商品退貨流程，涵蓋退貨申請(Return Request)建立、退件運貨單(Return Shipment)追蹤、標籤生成及倉庫處理等各環節。
此 API 僅供伺服器對伺服器整合使用。請勿直接從客戶端程式碼呼叫這些端點。
可用 API
User API — 供商家及合作夥伴管理退貨申請(Return Request)、退件運貨單(Return Shipment)、標籤、庫存及帳戶設定的認證端點。
Public API — 提供參考資料查詢的端點，包含服務類型、倉庫列表、狀態代碼及支援國家等查詢值。
所有 API 請求均需在請求標頭中提供 API 金鑰和 Token：
x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json
- 登入 Return Helper 使用者入口網站。
- 前往 Settings → Signing Key and API Token。
- 您現有的金鑰與 Token 配對將顯示於此。您也可以在此生成新的配對。
您的 API Token 屬於私密資訊。請勿分享或在客戶端程式碼中暴露它。
基礎 URL
沙箱環境
| 端點 | 基礎 URL |
|---|
| User API | https://api.returnshelper.com/uat/user/api |
| Public API | https://api.returnshelper.com/uat/public/api |
正式環境
| 端點 | 基礎 URL |
|---|
| User API | https://api.returnhelpercentre.com/v1/user/api |
| User API（中國） | https://api.returnhelperchina.com/user/ |
| Public API | https://api.returnhelpercentre.com/v1/public/api |
冪等性(Idempotency)
對於改變狀態的請求（如建立退件運貨單(Return Shipment)、庫存等），請附上冪等性金鑰(Idempotency Key)，以防止在網路重試時產生重複操作。
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
User-Agent 標頭
請附上 User-Agent 標頭，以便 Return Helper 支援團隊在排查問題時識別您的整合方式：
User-Agent: {app name}/{app version} (Platform={os version}; Runtime={runtime version}; Language={language})
User-Agent: CompanyABCApi/2024.16.0 (Platform=Unix/13.4.0; Runtime=8.0.2; Language=CSharp12)
x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
User-Agent: YourApp/1.0.0 (Platform=Linux/5.15; Runtime=8.0.2; Language=CSharp12)
OpenAPI 規格
完整的 API 規格以 OpenAPI 3.1 文件格式提供。您可以下載並直接匯入 Postman 或 Insomnia 等 API 客戶端，或使用 OpenAPI Generator 等工具生成客戶端 SDK。
下載 OpenAPI 規格
openapi.json — OpenAPI 3.1
一般備註
- 所有
dateTime 參數必須使用 ISO 8601 格式，否則 API 無法解析。
- 日期字串參數（例如
createToStr、createFromStr）也必須使用 ISO 8601 格式；時間部分將被忽略。
- API 回傳的所有時間戳均為 UTC 時間。
Webhooks
標籤結果及倉庫事件（退件運貨單(Return Shipment)抵達、庫存建立、圖片上傳等）均透過 Webhook 通知以非同步方式傳遞。您必須註冊一個通知端點以接收這些事件。
請參閱 Webhooks 章節，了解完整的通知事件類型列表及其 Payload。
