快速開始

​

前置條件

1. API 憑證 — 請參閱認證章節。
2. 已備妥一個 Webhook 通知端點，用於接收來自 Return Helper 的非同步事件。若未提供通知端點，將無法接收標籤結果及倉庫事件。
3. 閱讀本指南以了解主要退貨流程。

​

退貨流程概覽

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

​

申請退貨標籤

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

​

RMA（退貨授權號碼）

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

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

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

​

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

​

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

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

​

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

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

​

庫存圖片

​

處理指示

​

丟棄(Dispose)

​

暫停(Hold)

​

重寄(Resend)

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

​

回收(Recall)

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

​

增值服務(VAS)

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

​

自訂欄位

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

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

​

FBA（亞馬遜物流）退貨

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

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

​

取得歷史資料

​

回應結構

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

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