此頁面由 AI 自動翻譯。如有任何疑問或不一致之處，請以英文版本為準。

Return Helper API

Return Helper 提供一套 API，用於端對端管理電子商務商品退貨流程，涵蓋退貨申請(Return Request)建立、退件運貨單(Return Shipment)追蹤、標籤生成及倉庫處理等各環節。

此 API 僅供伺服器對伺服器整合使用。請勿直接從客戶端程式碼呼叫這些端點。

公告

速率限制：每秒 1 個請求

2026 年 11 月 1 日起API 每秒最多接受一個請求。請在旺季前檢查您的呼叫頻率。

建立 Resend Order 支援 Seller Reference Number

若您有設定 resendNumber，須採取行動所有帳戶皆可搜尋 Resend。resendNumber 將改為唯讀。

新 Webhook 事件：交易已新增

2026 年 10 月 5 日起每筆扣款、退款及儲值都會傳送至您的 Webhook 端點。

API 速率限制：每秒 1 個請求

自 2026 年 11 月 1 日起，Return Helper 將對 API 實施每秒 1 個請求的速率限制，以在旺季期間提升所有整合的服務穩定性。

請控制呼叫頻率，每秒不超過一個請求。
請使用 Webhooks 接收運貨單、庫存及補寄的更新，而非輪詢列表端點。

建立 Resend Order 支援 Seller Reference Number

建立 Resend Order（User API）將與以 SKU 建立 Resend 一樣，接受選填的 sellerReferenceNumber。屆時所有帳戶（不限 Enterprise）都能使用以 Seller Reference Number 搜尋 Resend 尋找補寄。 sellerReferenceNumber 為選填，現有整合可照常運作。但有一項破壞性變更：resendNumber 將改為由 Return Helper 產生的唯讀值。

若您的整合在建立 Resend Order 時設定 resendNumber（例如填入您的發票或訂單 ID），須採取行動：請在里程碑 2 之前，將該值改為設定於 sellerReferenceNumber。若您從未設定 resendNumber，則無須任何動作。

里程碑	日期	變更內容
里程碑 1	待公布	建立 Resend Order 接受 `sellerReferenceNumber`。您仍可設定 `resendNumber`。若您設定了 `resendNumber` 但未設定 `sellerReferenceNumber`，Return Helper 會將您的 `resendNumber` 複製到 `sellerReferenceNumber`，因此您無須任何修改即可搜尋該補寄。
里程碑 2	里程碑 1 之後 3 個月	設定 `resendNumber` 的請求將被拒絕。`resendNumber` 一律由 Return Helper 產生。

請在里程碑 1 與里程碑 2 之間完成遷移：

將您自己的參考編號改為透過 sellerReferenceNumber 傳送，而非 resendNumber。
若您以 resendNumber 比對重寄狀態更新 webhook 或您自己的紀錄，請改為以 sellerReferenceNumber 比對。

與 resendNumber 不同，sellerReferenceNumber 並非唯一值——Return Helper 不會拒絕重複的值。為避免重試時重複建立補寄，請傳送 x-returnhelper-idempotency-key 標頭。我們將在此處及更新紀錄公布里程碑 1 的日期。

新 Webhook 事件：交易已新增

自 2026 年 10 月 5 日起，每當有交易記入您的帳戶，Return Helper 都會向每個已註冊的 Webhook 端點發送交易已新增事件。您無須另外註冊。2026 年 10 月 5 日之前記入的交易不會發送。

若您的端點對無法識別的事件回傳非 2xx 狀態碼，須採取行動。傳遞失敗會重試；連續失敗 10 次後，對您端點的傳遞將暫停 24 小時，其他所有事件亦包括在內。請對您未處理的事件回傳 2xx。

更新紀錄

公告

交易已新增 Webhook

公告：交易已新增 Webhook 事件，自 2026 年 10 月 5 日起發送。詳見公告。

新功能

取消退貨面單

您現在可以透過取消退貨面單取消退貨面單。如需修正運貨單，請先取消其面單，再建立新的 Return Shipment。

公告

速率限制與建立 Resend 功能升級

公告：API 速率限制為每秒 1 個請求，自 2026 年 11 月 1 日起生效。
公告：建立 Resend Order 支援 sellerReferenceNumber；resendNumber 將改為唯讀。

新功能

自助管理 Webhook 端點

您現在可以透過新增 Notification Endpoint、列出 Notification Endpoints 及刪除 Notification Endpoint 自行管理 webhook 通知端點。

可用 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 配對將顯示於此。您也可以在此生成新的配對。

同一畫面也會顯示您的簽署金鑰（上圖中已標示）。這是一組獨立的 Base64 編碼密鑰——它不用於驗證 API 請求，而是用來驗證傳入的 webhook 通知確實來自 Return Helper。您也可以使用取得 Signing Key以程式方式讀取。使用方式請參閱 Webhooks → 簽章驗證。

您的 API Token 與簽署金鑰皆屬私密資訊。請勿分享或在客戶端程式碼中暴露它們。

基礎 URL

沙箱環境

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

正式環境

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

冪等性(Idempotency)

以下端點接受 x-returnhelper-idempotency-key 標頭，確保重試的請求只處理一次。

x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY

請為每個不同的請求產生全新的 UUID（或類似的唯一字串），並僅在重試同一請求時傳送相同的金鑰。此標頭為選填。未帶此標頭的請求會正常處理，但不具備防重複的保護。重複使用已完成請求之金鑰的請求會被拒絕，而不會再次處理——請參閱等冪金鑰失敗。

端點	路由
建立 Return Shipment	`POST /api/ReturnShipment/createReturnShipment`
取消退貨面單	`POST /api/Label/CancelLabel`
建立 Resend Order	`POST /api/Resend/createResend`
以 SKU 建立 Resend	`POST /api/Resend/createResendBySku`
取消 Resend Order	`POST /api/Resend/cancelResend`
為 Return Inventory 指定 SKU	`POST /api/ReturnInventory/assignReturnInventorySku`
新增 Notification Endpoint	`POST /api/Notification/Add`
刪除 Notification Endpoint	`POST /api/Notification/Delete`

其他端點會忽略此標頭。

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-apitoken`	401	`meta.status: 401`，`meta.error.message` 描述驗證失敗原因
驗證失敗（缺少欄位、型別錯誤、業務規則違規）	200	`meta.status: 400`，`meta.errorCode: "VALIDATION_FAILED"`，`meta.error` 以請求欄位為鍵
成功	200	`meta.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。

聯絡技術支援

如有技術問題或整合問題，請寄送電子郵件至 support@returnhelper.com。為便於我們排查，請提供以下資訊：

回應中的 correlationId
所用環境（沙箱環境或正式環境）及呼叫的端點
請求時間（含時區）
請求主體及收到的回應

請勿在郵件中提供您的 API token 或 signing key。

概覽

簡介

Return Helper API

公告

速率限制：每秒 1 個請求

建立 Resend Order 支援 Seller Reference Number

新 Webhook 事件：交易已新增

API 速率限制：每秒 1 個請求

建立 Resend Order 支援 Seller Reference Number

新 Webhook 事件：交易已新增

更新紀錄

可用 API

認證

基礎 URL

沙箱環境

正式環境

冪等性(Idempotency)

User-Agent 標頭

OpenAPI 規格

下載 OpenAPI 規格

錯誤處理

失敗類型

驗證失敗範例

一般備註

Webhooks

聯絡技術支援

​Return Helper API

​公告

速率限制：每秒 1 個請求

建立 Resend Order 支援 Seller Reference Number

新 Webhook 事件：交易已新增

​API 速率限制：每秒 1 個請求

​建立 Resend Order 支援 Seller Reference Number

​新 Webhook 事件：交易已新增

​更新紀錄

​可用 API

​認證

​基礎 URL

​沙箱環境

​正式環境

​冪等性(Idempotency)

​User-Agent 標頭

​OpenAPI 規格

下載 OpenAPI 規格

​錯誤處理

​失敗類型

​驗證失敗範例

​一般備註

​Webhooks

​聯絡技術支援

Return Helper API

公告

API 速率限制：每秒 1 個請求

建立 Resend Order 支援 Seller Reference Number

新 Webhook 事件：交易已新增

更新紀錄

可用 API

認證

基礎 URL

沙箱環境

正式環境

冪等性(Idempotency)

User-Agent 標頭

OpenAPI 規格

錯誤處理

失敗類型

驗證失敗範例

一般備註

Webhooks

聯絡技術支援