> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt > Use this file to discover all available pages before exploring further. # 快速開始 > 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](/zh-Hant/introduction#base-urls) | 所有整合測試先在 sandbox 完成 | | Webhook 接收方 | 提供用於簽名驗證的 signing key | 建置 HTTPS 端點，解析原始 body，驗證簽名，及時回應 `200` | | Webhook 端點註冊 | 在您提交申請表後由我們接入端點 | 端點對公網可達後提交 [Webhook Setup Request Form](https://forms.gle/iBVkRZvfLQ8o1Nqg8) | | 冪等處理 | — | 使用 `notificationId` 去重（見 [Webhooks](/zh-Hant/webhooks#event-delivery)） | | 上線生產 | Sandbox 驗收通過後，由我們發放生產憑證並將您註冊的端點切換至生產環境 | Sandbox 測試完成、準備承接生產流量時通知 support |

賣家檢查清單

呼叫任何會變更狀態的端點前，請依序完成以下事項： 1. **取得 API 憑證。** 登入 User Portal，在 **Settings → Signing Key and API Token** 複製 API key 與 API token。同一頁面也會顯示用於驗證 webhook 簽名的 **signing key**。 2. **選定環境。** 先在 sandbox（UAT）開始。生產 base URL 在 sandbox 驗收後才啟用 — 見 [Base URLs](/zh-Hant/introduction#base-urls)。 3. **建構 Webhook 接收方。** 建立一個 HTTPS 端點：解析原始 POST body，使用 signing key 驗證 `returnhelper-signature` 標頭，按 `notificationId` 去重，並及時回應 `200 OK`。範例程式碼見 [Webhooks → Signature Verification](/zh-Hant/webhooks#signature-verification)。 4. **將端點註冊到我們這邊。** 端點對公網可達後，提交 [Webhook Setup Request Form](https://forms.gle/iBVkRZvfLQ8o1Nqg8)，由我們完成連接 — 目前不提供自助註冊 API。 5. **在 sandbox 端對端驗證。** 依本指南其餘章節走完面單建立、倉庫到達、到倉後處理流程，並確認對應的 webhook 事件能在您的接收方收到。 6. **申請上線生產。** Sandbox 測試完成後，聯絡 support 將您的憑證與已註冊端點切換至生產環境。 步驟 4 完成前，面單結果與倉庫事件無處投遞。在尚未註冊 Webhook 端點的情況下，API 仍接受請求，但您無法取回已產生的面單，也無從得知貨件何時到倉。

退貨流程概覽

典型的退貨流程分為三個階段： 1. **抵達倉庫前** — 建立退件運貨單(Return Shipment)申請並取得運送標籤。 2. **抵達倉庫** — 包裹被掃描入庫；圖片被上傳；退件運貨單(Return Shipment)轉換為退貨庫存(Return Inventory)記錄。 3. **抵達後處理** — 指示倉庫如何處理庫存（丟棄、重寄、回收、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／營運團隊。 | 詳細流程：[申請退貨標籤](#requesting-a-return-label)。

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](#return-inventory-at-warehouse-arrival)。

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`）。 詳細流程：[處理指令](#handling-instructions)。 ***

申請退貨標籤

標籤建立是**非同步**的。流程如下： 1. 呼叫 [**建立退件運貨單(Return Shipment)**](/zh-Hant/api-reference/returnshipment/create-return-shipment) 以建立退件運貨單(Return Shipment)記錄並排入標籤請求佇列。 2. Return Helper 生成標籤，並透過 [**label** 通知事件](/zh-Hant/webhooks#label-result) 將結果傳遞至您的 Webhook 通知端點。 您必須已註冊 Webhook 端點才能接收標籤結果。若未註冊，將無法取得已生成的標籤。 ```mermaid theme={null} sequenceDiagram participant S as 賣家系統 participant RH as Return Helper (RH) participant W as 賣家 Webhook 端點 S->>RH: createReturnShipment(request) RH->>RH: 驗證請求 alt 無驗證錯誤 RH-->>S: 200 OK（請求提交成功） RH->>RH: 將標籤生成排入佇列 RH->>W: POST /label-notification（結果 Payload） Note over W: [標籤生成成功]
Payload 包含 labelUrl Note over W: [標籤生成失敗]
Payload 包含 failReasons + errorMessages else 驗證錯誤 RH-->>S: 4xx 錯誤（驗證錯誤訊息） end ``` ***

RMA（退貨授權號碼）

當退件運貨單(Return Shipment)進入 Return Helper 倉庫時，系統會指派一個全域唯一的 RMA。Return Helper 使用 RMA 作為主要溝通識別碼，而非承運商追蹤號碼，原因有二： * 追蹤號碼可能在不同承運商之間重複，甚至在同一承運商內部重複。 * 當包裹透過 VAS 拆分時，每個產生的包裹會獲得各自的 RMA。 **一般 RMA 格式：** ``` ---- ``` 範例：`TWN-20-230101-D12345-36` **拆分 RMA 格式**（VAS 拆分後）： ``` ----- ``` 範例：`TWN-20-230101-D12345-01-36` ***

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

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

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

1. 賣家透過 API 建立退件運貨單(Return Shipment)並提供標籤。 2. 倉庫標記已收到 → 發送 [**warehouseMarkShipmentArrivedV2**](/zh-Hant/webhooks#warehouse-shipment-arrived-v2) Webhook，隨後發送 [**inventoryCreated**](/zh-Hant/webhooks#inventory-created)（包含 `returnInventoryId`）。 3. 若單一標籤涵蓋多個包裹，每個包裹將成為獨立的退貨庫存(Return Inventory)記錄，共享相同的 `shipmentId` 和 `returnRequestId`。每筆庫存發送一個 [**inventoryCreated**](/zh-Hant/webhooks#inventory-created) 事件。 4. 庫存圖片隨後上傳，並透過 [**changeLineItemImage**](/zh-Hant/webhooks#image-updated) 傳遞。

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

1. 退件在沒有賣家建立記錄的情況下抵達，但被識別為屬於某位賣家。 2. 發送 [**assignUnknown**](/zh-Hant/webhooks#unknown-shipment-assigned) Webhook，包含退貨庫存(Return Inventory) Payload、`returnInventoryId`、`shipmentId` 及 `returnRequestId`。 3. 若包裹包含多個品項，可能會隨後發送多個 [**inventoryCreated**](/zh-Hant/webhooks#inventory-created) 事件。 4. 指派前拍攝的圖片包含在 [**assignUnknown**](/zh-Hant/webhooks#unknown-shipment-assigned) 中；後續任何變更透過 [**changeLineItemImage**](/zh-Hant/webhooks#image-updated) 傳遞。 ***

庫存圖片

當圖片上傳（或圖片列表變更）時，會發送 [**changeLineItemImage**](/zh-Hant/webhooks#image-updated) Webhook，其中包含圖片 URL 列表。 ***

處理指示

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

丟棄(Dispose)

呼叫 [**更新退貨庫存(Return Inventory)處理**](/zh-Hant/api-reference/returninventory/update-return-inventory-handling)，使用丟棄處理類型。使用 [**取消退貨庫存(Return Inventory)處理**](/zh-Hant/api-reference/returninventory/cancel-return-inventory-handling) 撤回指示。

暫停(Hold)

呼叫 [**更新退貨庫存(Return Inventory)處理**](/zh-Hant/api-reference/returninventory/update-return-inventory-handling)，使用暫停處理類型。

重寄(Resend)

1. 呼叫 [**建立重寄**](/zh-Hant/api-reference/resend/create-resend-order)，提供 `returnInventoryId` 列表。 2. 透過 [**resend**](/zh-Hant/webhooks#resend-status-update) Webhook 通知接收重寄追蹤號碼。 3. 若不再需要重寄，呼叫 [**取消重寄**](/zh-Hant/api-reference/resend/cancel-resend-order)。

回收(Recall)

1. 呼叫 [**依退貨庫存(Return Inventory) ID 建立回收**](/zh-Hant/api-reference/recall/create-recall-by-return-inventory-ids)，最多提供 100 個 `returnInventoryId` 值。 2. 追蹤更新及取件狀態變更透過 [**recall**](/zh-Hant/webhooks#recall-status-update) Webhook 通知傳遞。

增值服務(VAS)

1. 呼叫 [**建立 VAS**](/zh-Hant/api-reference/vas/create-vas-by-return-inventory-id)，提供 `returnInventoryId` 及所需的 VAS 類型。 2. 結果透過 [**UpdateVas**](/zh-Hant/webhooks#vas-update) Webhook 通知傳遞。 ***

自訂欄位

自訂欄位可讓您將任意的鍵值對中繼資料附加至退貨記錄。Return Helper 會儲存這些資料但不進行處理，並在相關的 Webhook 通知中回傳給您。 * 類型：`Dictionary` * 每筆退貨最多 24 個自訂欄位。 ```json theme={null} { "customFieldMap": { "customerId": "buyer123", "dateOfPurchase": "2024-07-01" } } ``` 自訂欄位可在 [**建立退件運貨單(Return Shipment)**](/zh-Hant/api-reference/returnshipment/create-return-shipment) 中使用，並在 [**warehouseMarkShipmentArrivedV2**](/zh-Hant/webhooks#warehouse-shipment-arrived-v2) 通知中回傳。 ***

FBA（亞馬遜物流）退貨

客戶可將 FBA 商品寄送至 Return Helper 倉庫進行處理（補貨、補充、回收、丟棄等）。 **典型 FBA 工作流程：** 1. 呼叫 [**建立 FBA 退件運貨單(FBA Shipment)**](/zh-Hant/api-reference/fbashipment/create-fba-shipment) 通知 Return Helper 並將商品寄送至倉庫。 2. 退件運貨單(Return Shipment)被收到並以 `fnsku` 和 `quantity` 存入 FBA 庫存，並透過 Webhook 傳遞。 3. 使用 [**取得 FBA 倉庫庫存列表**](/zh-Hant/api-reference/fbawarehouseinventory/get-fba-warehouse-inventory-list-by-fnsku) 查看現有 FBA 庫存。 4. 透過 [**建立 FBA 指示**](/zh-Hant/api-reference/fbainstruction/create-fba-instructions) 建立指示（補充庫存需要額外的退件運貨單(Return Shipment)資訊，目前 API 尚未提供）。 5. Return Helper 處理指示並透過 Webhook 通知您結果。 6. 透過相關的「取得 FBA 指示詳情」端點（回收、丟棄、補貨、其他）查看指示狀態。 **取得歷史 FBA 資料**（適用於正在遷移至 API 的現有入口網站使用者）： 1. 使用 [**列出 FBA 退件運貨單(FBA Shipment)**](/zh-Hant/api-reference/fbashipment/list-fba-shipments-with-pagination) 取得指定日期範圍內的過去退件運貨單(Return Shipment)，收集 `fbaShipmentId` 值。 2. 呼叫 [**取得 FBA 退件運貨單(FBA Shipment)品項列表**](/zh-Hant/api-reference/fbashipmentitem/get-items-in-fba-shipment) 取得每筆退件運貨單(Return Shipment)的品項、FNSKU 及數量。 3. 使用 [**取得 FBA 倉庫庫存列表**](/zh-Hant/api-reference/fbawarehouseinventory/get-fba-warehouse-inventory-list-by-fnsku) 並提供 FNSKU 查看目前庫存。 4. 使用 [**列出 FBA 指示**](/zh-Hant/api-reference/fbainstruction/list-fba-instructions-with-pagination) 查找過去的指示。 5. 對每筆指示使用 [**取得 FBA 指示品項列表**](/zh-Hant/api-reference/fbainstructionitem/get-items-in-fba-instruction) 取得明細項目詳情。 取得歷史資料後，請依賴正常的 API 呼叫和 Webhook 事件，而非持續輪詢。 ***

取得歷史資料

本章節適用於正在遷移至 API 的現有 Return Helper 入口網站使用者。若您是全新整合，所有必要資料均透過正常的 API 呼叫和 Webhook 事件交換，無需取得歷史資料。 **取得歷史退件運貨單(Return Shipment)資料：** 使用 [**列出退件運貨單(Return Shipment)**](/zh-Hant/api-reference/shipment/list-shipments-with-pagination) 取得指定日期範圍內的過去退件運貨單(Return Shipment)。 **取得歷史退貨庫存(Return Inventory)資料：** 使用 [**列出退貨庫存(Return Inventory)**](/zh-Hant/api-reference/returninventory/list-return-inventories-with-pagination) 取得指定日期範圍內的過去退貨庫存(Return Inventory)記錄。 FBA 歷史資料請參閱上方的**取得歷史 FBA 資料**章節。 取得所有歷史資料後，請依賴正常的 API 呼叫和 Webhook 事件，而非持續輪詢歷史資料。 ***

回應結構

每個 API 回應均包含一個 `meta` 物件，用於指示結果狀態。 **成功回應（`status: 200`）：** ```json theme={null} { "apiBalances": [ { "apiBalanceId": 7, "currencyCode": "usd", "balance": 2044.233 } ], "correlationId": "0HM9VIKSKH2CB:00000002", "meta": { "status": 200, "data": {}, "errorCode": null, "error": {} }, "totalNumberOfRecords": 1 } ``` **失敗回應（例如無效的 `warehouseId`）：** ```json theme={null} { "correlationId": "0HM9VIKSKH2CF:00000002", "meta": { "status": 400, "data": {}, "errorCode": "VALIDATION_FAILED", "error": { "warehouseId": "The value 'invalid' is not valid." } } } ``` 任何非 `200` 的 `status` 值均表示請求未成功完成。`errorCode` 和 `error` 欄位提供詳細說明。