跳轉到主要內容
此頁面由 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
取得您的憑證：
  1. 登入 Return Helper 使用者入口網站。
  2. 前往 Settings → Signing Key and API Token。
  3. 您現有的金鑰與 Token 配對將顯示於此。您也可以在此生成新的配對。
使用者入口網站中的簽名金鑰、API Token 和 API Key
您的 API Token 屬於私密資訊。請勿分享或在客戶端程式碼中暴露它。

​
基礎 URL

​
沙箱環境

端點基礎 URL
User APIhttps://api.returnshelper.com/uat/user/api
Public APIhttps://api.returnshelper.com/uat/public/api

​
正式環境

端點基礎 URL
User APIhttps://api.returnhelpercentre.com/v1/user/api
User API（中國）https://api.returnhelperchina.com/user/
Public APIhttps://api.returnhelpercentre.com/v1/public/api

​
冪等性(Idempotency)

對於改變狀態的請求（如建立退件運貨單(Return Shipment)、庫存等），請附上冪等性金鑰(Idempotency Key)，以防止在網路重試時產生重複操作。 
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
請為每個不同的交易請求生成全新的 UUID（或類似的唯一字串）。伺服器會識別相同金鑰的重複提交，並只執行一次操作，確保資料完整性。

​
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

​
錯誤處理

每個回應（無論成功或失敗）都使用統一的信封格式： 
{
  "correlationId": "0HNL9S3BA31VM:00000001",
  "meta": {
    "status": 200,
    "data": {},
    "errorCode": null,
    "error": {}
  }
}
成功回應會將業務資料以頂層欄位（與 correlationId 和 meta 同層）一併回傳，例如 getAllCountries 回傳 { correlationId, meta, countries: [...] }。在讀取業務資料前，請務必檢查 meta.errorCode——本 API 採用「軟性錯誤」慣例，驗證失敗會以 HTTP 200 回傳，並於 meta.status 標記為 400，同時填入 meta.errorCode。

​
失敗類型

失敗實際 HTTP回應內容
缺少或無效的 x-rr-apikey / x-rr-apitoken401meta.status: 401，meta.error.message 描述驗證失敗原因
驗證失敗（缺少欄位、型別錯誤、業務規則違規）200meta.status: 400，meta.errorCode: "VALIDATION_FAILED"，meta.error 以請求欄位為鍵
成功200meta.status: 200，meta.errorCode: null，業務資料位於頂層

​
驗證失敗範例

{
  "correlationId": "0HNLB2U6T1QG1:00000001",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "returnInventoryId": "'return Inventory Id' must not be empty."
    }
  }
}
請勿僅依據實際 HTTP 狀態碼判斷成功與否。200 OK 仍可能代表邏輯失敗——務必檢查 meta.status 與 meta.errorCode。
整合時，請記錄每個回應的 correlationId。Return Helper 客服在排查問題時會使用該 ID 追溯請求。

​
一般備註

  • 所有 dateTime 參數必須使用 ISO 8601 格式，否則 API 無法解析。
  • 日期字串參數（例如 createToStr、createFromStr）也必須使用 ISO 8601 格式；時間部分將被忽略。
  • API 回傳的所有時間戳均為 UTC 時間。

​
Webhooks

標籤結果及倉庫事件（退件運貨單(Return Shipment)抵達、庫存建立、圖片上傳等）均透過 Webhook 通知以非同步方式傳遞。您必須註冊一個通知端點以接收這些事件。 請參閱 Webhooks 章節，了解完整的通知事件類型列表及其 Payload。