快速開始 - Return Helper API

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

整合前準備

整合工作由 Return Helper 與您的團隊共同完成：Return Helper 負責發放憑證並接入您的 Webhook 端點；您的工程團隊負責建構請求簽名方與 Webhook 接收方。下面的「雙方分工」表說明哪些步驟由誰負責，隨後是一份非技術專案負責人可與工程團隊一起逐項檢查的清單。

雙方分工

步驟	Return Helper	您的團隊
API key 與 token	在 User Portal 的 Settings → Signing Key and API Token 中發放	安全保存；載入至您的伺服器設定
Sandbox 存取	Sandbox base URL 見 Base URLs	所有整合測試先在 sandbox 完成
Webhook 接收方	提供用於簽名驗證的 signing key	建置 HTTPS 端點，解析原始 body，驗證簽名，及時回應 `200`
Webhook 端點註冊	在您提交申請表後由我們接入端點	端點對公網可達後提交 Webhook Setup Request Form
冪等處理	—	使用 `notificationId` 去重（見 Webhooks）
上線生產	Sandbox 驗收通過後，由我們發放生產憑證並將您註冊的端點切換至生產環境	Sandbox 測試完成、準備承接生產流量時通知 support

賣家檢查清單

呼叫任何會變更狀態的端點前，請依序完成以下事項：

取得 API 憑證。 登入 User Portal，在 Settings → Signing Key and API Token 複製 API key 與 API token。同一頁面也會顯示用於驗證 webhook 簽名的 signing key。
選定環境。 先在 sandbox（UAT）開始。生產 base URL 在 sandbox 驗收後才啟用 — 見 Base URLs。
建構 Webhook 接收方。 建立一個 HTTPS 端點：解析原始 POST body，使用 signing key 驗證 returnhelper-signature 標頭，按 notificationId 去重，並及時回應 200 OK。範例程式碼見 Webhooks → Signature Verification。
將端點註冊到我們這邊。 端點對公網可達後，提交 Webhook Setup Request Form，由我們完成連接 — 目前不提供自助註冊 API。
在 sandbox 端對端驗證。 依本指南其餘章節走完面單建立、倉庫到達、到倉後處理流程，並確認對應的 webhook 事件能在您的接收方收到。
申請上線生產。 Sandbox 測試完成後，聯絡 support 將您的憑證與已註冊端點切換至生產環境。

步驟 4 完成前，面單結果與倉庫事件無處投遞。在尚未註冊 Webhook 端點的情況下，API 仍接受請求，但您無法取回已產生的面單，也無從得知貨件何時到倉。

退貨流程概覽

典型的退貨流程分為三個階段：

抵達倉庫前 — 建立退件運貨單(Return Shipment)申請並取得運送標籤。
抵達倉庫 — 包裹被掃描入庫；圖片被上傳；退件運貨單(Return Shipment)轉換為退貨庫存(Return Inventory)記錄。
抵達後處理 — 指示倉庫如何處理庫存（丟棄、重寄、回收、VAS 等）。

端對端 Recipes

三條精簡的 recipe，把每個生命週期節點對應到您要呼叫的 API、要監聽的 Webhook 事件，以及隨後的動作。每條 recipe 都會連結到下方的詳述章節。

Recipe 1 — 建立退貨標籤

步驟	您的動作	Webhook（`action`）	後續動作
1	`POST /api/ReturnShipment/createReturnShipment`	—	從同步回應讀取 `shipmentId` 與 `labelRequestStatusCode: queued`。
2（成功）	（等候）	`labelGenerated`	從 Webhook payload 讀取 `labelUrl` 與 `trackingNumber`，把標籤交給買家。比對請使用 `shipmentId`，不要使用 `labelId`。
2（失敗）	（等候）	`labelGenerated`，附帶 `labelRequestStatusCode: failed`	檢查 `failReasons` 與 `errorMessages`，並將失敗通知您的 CS／營運團隊。

詳細流程：申請退貨標籤。

Recipe 2 — 接收倉庫到達事件

不需要任何對外 API 呼叫 — 等待倉庫主動推送事件即可。

步驟	Webhook（`action`）	後續動作
1	`markShipmentArrive`	依 `shipmentId` 比對到您先前建立的 Return Shipment。
2	`newInventoryCreated` — 每筆產生的 Return Inventory 推送一次（一份運貨單可能產生多筆）	把新的 `returnInventoryId` 關聯至您系統中對應的運貨單。
3	倉庫每次新增或替換圖片時推送 `changeLineItemImage`	重新整理該 `returnInventoryId` 的圖片 URL 快取。
變體 — Unknown Shipment	包裹無對應的賣家 Return Shipment 而到倉時，推送 `assignUnknown` 取代步驟 1+2	視為全新的 Return Inventory 處理；payload 已包含 `returnInventoryId`、`shipmentId`、`returnRequestId`，以及指派前的圖片。

詳細流程：抵達倉庫時的 Return Inventory。

Recipe 3 — 下達處理指令

依您要執行的操作選擇對應列；不同操作對應不同的 API 呼叫與 Webhook。

操作	API 呼叫	Webhook（`action`）	後續動作
Dispose / On-hold	`POST /api/ReturnInventory/UpdateReturnInventoryHandling`，並填入 dispose 或 on-hold handling code	`completeInventoryHandling`	庫存結案，無須後續動作。
Resend	`POST /api/Resend/createResend`，引用一個或多個 `returnInventoryId`	`updateResendStatus`	追蹤 resend 的對外運送，直到送達買家。
Recall	`POST /api/Recall/createRecallByReturnInventoryId`，最多 100 個 `returnInventoryId`	`recallUpdateStatus`	追蹤運送，直到庫存抵達香港集中倉。
VAS	`POST /api/Vas/CreateByReturnInventoryId`，提供 `returnInventoryId` 與所需 VAS 類型	`vasUpdated`（若 VAS 拆分庫存則另有 `splitLineItem`）	重新讀取庫存記錄。若 VAS 產生拆分，每件衍生包裹會獲得自己的 `returnInventoryId` 與自己的 RMA。

如需在處理前撤回某條 handling 指令，呼叫對應操作的取消端點（例如 POST /api/ReturnInventory/CancelReturnInventoryHandling）。詳細流程：處理指令。

申請退貨標籤

標籤建立是非同步的。流程如下：

呼叫 建立退件運貨單(Return Shipment) 以建立退件運貨單(Return Shipment)記錄並排入標籤請求佇列。
Return Helper 生成標籤，並透過 label 通知事件將結果傳遞至您的 Webhook 通知端點。

您必須已註冊 Webhook 端點才能接收標籤結果。若未註冊，將無法取得已生成的標籤。

RMA（退貨授權號碼）

當退件運貨單(Return Shipment)進入 Return Helper 倉庫時，系統會指派一個全域唯一的 RMA。Return Helper 使用 RMA 作為主要溝通識別碼，而非承運商追蹤號碼，原因有二：

追蹤號碼可能在不同承運商之間重複，甚至在同一承運商內部重複。
當包裹透過 VAS 拆分時，每個產生的包裹會獲得各自的 RMA。

一般 RMA 格式：

<warehouse prefix>-<warehouse ID>-<YYMMDD>-<env letter><sequence up to 5 digits>-<check digits>

範例：TWN-20-230101-D12345-36 拆分 RMA 格式（VAS 拆分後）：

<warehouse prefix>-<warehouse ID>-<YYMMDD>-<env letter><sequence up to 5 digits>-<split sequence 2 digits>-<check digits>

範例：TWN-20-230101-D12345-01-36

抵達倉庫時的退貨庫存(Return Inventory)

當退件運貨單(Return Shipment)抵達倉庫時，系統會將其標記為已收到，並轉換為一筆或多筆**退貨庫存(Return Inventory)**記錄，每筆記錄具有唯一的 returnInventoryId。

類型 1 — 賣家發起的退件運貨單(Return Shipment)

賣家透過 API 建立退件運貨單(Return Shipment)並提供標籤。
倉庫標記已收到 → 發送 warehouseMarkShipmentArrivedV2 Webhook，隨後發送 inventoryCreated（包含 returnInventoryId）。
若單一標籤涵蓋多個包裹，每個包裹將成為獨立的退貨庫存(Return Inventory)記錄，共享相同的 shipmentId 和 returnRequestId。每筆庫存發送一個 inventoryCreated 事件。
庫存圖片隨後上傳，並透過 changeLineItemImage 傳遞。

類型 2 — 指派給賣家的未知來件(Unknown Shipment)

退件在沒有賣家建立記錄的情況下抵達，但被識別為屬於某位賣家。
發送 assignUnknown Webhook，包含退貨庫存(Return Inventory) Payload、returnInventoryId、shipmentId 及 returnRequestId。
若包裹包含多個品項，可能會隨後發送多個 inventoryCreated 事件。
指派前拍攝的圖片包含在 assignUnknown 中；後續任何變更透過 changeLineItemImage 傳遞。

庫存圖片

當圖片上傳（或圖片列表變更）時，會發送 changeLineItemImage Webhook，其中包含圖片 URL 列表。

處理指示

退貨庫存(Return Inventory)記錄建立後，您可以指示倉庫如何處理：

丟棄(Dispose)

呼叫 更新退貨庫存(Return Inventory)處理，使用丟棄處理類型。使用 取消退貨庫存(Return Inventory)處理 撤回指示。

暫停(Hold)

呼叫 更新退貨庫存(Return Inventory)處理，使用暫停處理類型。

重寄(Resend)

呼叫 建立重寄，提供 returnInventoryId 列表。
透過 resend Webhook 通知接收重寄追蹤號碼。
若不再需要重寄，呼叫 取消重寄。

回收(Recall)

呼叫 依退貨庫存(Return Inventory) ID 建立回收，最多提供 100 個 returnInventoryId 值。
追蹤更新及取件狀態變更透過 recall Webhook 通知傳遞。

增值服務(VAS)

呼叫 建立 VAS，提供 returnInventoryId 及所需的 VAS 類型。
結果透過 UpdateVas Webhook 通知傳遞。

自訂欄位

自訂欄位可讓您將任意的鍵值對中繼資料附加至退貨記錄。Return Helper 會儲存這些資料但不進行處理，並在相關的 Webhook 通知中回傳給您。

類型：Dictionary<string, string>
每筆退貨最多 24 個自訂欄位。

{
  "customFieldMap": {
    "customerId": "buyer123",
    "dateOfPurchase": "2024-07-01"
  }
}

自訂欄位可在 建立退件運貨單(Return Shipment) 中使用，並在 warehouseMarkShipmentArrivedV2 通知中回傳。

FBA（亞馬遜物流）退貨

客戶可將 FBA 商品寄送至 Return Helper 倉庫進行處理（補貨、補充、回收、丟棄等）。 典型 FBA 工作流程：

呼叫 建立 FBA 退件運貨單(FBA Shipment) 通知 Return Helper 並將商品寄送至倉庫。
退件運貨單(Return Shipment)被收到並以 fnsku 和 quantity 存入 FBA 庫存，並透過 Webhook 傳遞。
使用 取得 FBA 倉庫庫存列表 查看現有 FBA 庫存。
透過 建立 FBA 指示 建立指示（補充庫存需要額外的退件運貨單(Return Shipment)資訊，目前 API 尚未提供）。
Return Helper 處理指示並透過 Webhook 通知您結果。
透過相關的「取得 FBA 指示詳情」端點（回收、丟棄、補貨、其他）查看指示狀態。

取得歷史 FBA 資料（適用於正在遷移至 API 的現有入口網站使用者）：

使用 列出 FBA 退件運貨單(FBA Shipment) 取得指定日期範圍內的過去退件運貨單(Return Shipment)，收集 fbaShipmentId 值。
呼叫 取得 FBA 退件運貨單(FBA Shipment)品項列表 取得每筆退件運貨單(Return Shipment)的品項、FNSKU 及數量。
使用 取得 FBA 倉庫庫存列表 並提供 FNSKU 查看目前庫存。
使用 列出 FBA 指示 查找過去的指示。
對每筆指示使用 取得 FBA 指示品項列表 取得明細項目詳情。

取得歷史資料後，請依賴正常的 API 呼叫和 Webhook 事件，而非持續輪詢。

取得歷史資料

本章節適用於正在遷移至 API 的現有 Return Helper 入口網站使用者。若您是全新整合，所有必要資料均透過正常的 API 呼叫和 Webhook 事件交換，無需取得歷史資料。

取得歷史退件運貨單(Return Shipment)資料： 使用 列出退件運貨單(Return Shipment) 取得指定日期範圍內的過去退件運貨單(Return Shipment)。 取得歷史退貨庫存(Return Inventory)資料： 使用 列出退貨庫存(Return Inventory) 取得指定日期範圍內的過去退貨庫存(Return Inventory)記錄。 FBA 歷史資料請參閱上方的取得歷史 FBA 資料章節。取得所有歷史資料後，請依賴正常的 API 呼叫和 Webhook 事件，而非持續輪詢歷史資料。

回應結構

每個 API 回應均包含一個 meta 物件，用於指示結果狀態。 成功回應（status: 200）：

{
  "apiBalances": [
    {
      "apiBalanceId": 7,
      "currencyCode": "usd",
      "balance": 2044.233
    }
  ],
  "correlationId": "0HM9VIKSKH2CB:00000002",
  "meta": {
    "status": 200,
    "data": {},
    "errorCode": null,
    "error": {}
  },
  "totalNumberOfRecords": 1
}

失敗回應（例如無效的 warehouseId）：

{
  "correlationId": "0HM9VIKSKH2CF:00000002",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "warehouseId": "The value 'invalid' is not valid."
    }
  }
}

任何非 200 的 status 值均表示請求未成功完成。errorCode 和 error 欄位提供詳細說明。

​整合前準備

​雙方分工

​賣家檢查清單

​退貨流程概覽

​端對端 Recipes

​Recipe 1 — 建立退貨標籤

​Recipe 2 — 接收倉庫到達事件

​Recipe 3 — 下達處理指令

​申請退貨標籤

​RMA（退貨授權號碼）

​抵達倉庫時的退貨庫存(Return Inventory)

​類型 1 — 賣家發起的退件運貨單(Return Shipment)

​類型 2 — 指派給賣家的未知來件(Unknown Shipment)

​庫存圖片

​處理指示

​丟棄(Dispose)

​暫停(Hold)

​重寄(Resend)

​回收(Recall)

​增值服務(VAS)

​自訂欄位

​FBA（亞馬遜物流）退貨

​取得歷史資料

​回應結構

整合前準備

雙方分工

賣家檢查清單

退貨流程概覽

端對端 Recipes

Recipe 1 — 建立退貨標籤

Recipe 2 — 接收倉庫到達事件

Recipe 3 — 下達處理指令

申請退貨標籤

RMA（退貨授權號碼）

抵達倉庫時的退貨庫存(Return Inventory)

類型 1 — 賣家發起的退件運貨單(Return Shipment)

類型 2 — 指派給賣家的未知來件(Unknown Shipment)

庫存圖片

處理指示

丟棄(Dispose)

暫停(Hold)

重寄(Resend)

回收(Recall)

增值服務(VAS)

自訂欄位

FBA（亞馬遜物流）退貨

取得歷史資料

回應結構