Webhooks 與通知 - Return Helper API

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

概覽

當 Return Helper 系統中發生事件時（例如標籤生成或退件運貨單(Return Shipment)抵達倉庫），Webhooks 會傳遞非同步通知。您的伺服器必須公開一個 HTTPS 端點以接收這些 POST 請求。

設定您的 Webhook 端點

端點要求

在提交設定請求前，請確保您的端點符合以下要求：

可公開存取 — URL 必須可從網際網路存取（不可使用 VPN、localhost 或僅限內部存取的位址）
HTTPS — 端點必須使用具有有效 TLS 憑證的 HTTPS
HTTP POST — 端點必須接受含 application/json 主體的 POST 請求
回應 HTTP 200 — 您的伺服器在收到請求後必須迅速回傳 200 OK 狀態；任何其他狀態碼或逾時均視為傳遞失敗
快速回應 — 如有需要請以非同步方式處理事件；請勿在回應前執行繁重的作業，以避免傳遞逾時

註冊您的端點

如需註冊 Webhook 端點，請填寫 Webhook 設定申請表。此表單包含我們完成設定所需的所有資訊，是啟用端點最快速的方式。

我們建議使用上方的表單，因為它可確保一次性收集所有必要資訊。若您無法使用表單，也可以透過電子郵件提出申請——請參閱下方範本。

電子郵件範本（若您無法使用表單）

若您偏好透過電子郵件聯絡，請將以下內容發送至 support@returnhelper.com，並副本給 paco@returnhelper.com、tingfung@returnhelper.com 及 roy@returnhelper.com：

Subject: Request webhook setup in Return Helper - <YOUR CLIENT CODE>

To: support@returnhelper.com
CC: paco@returnhelper.com, tingfung@returnhelper.com, roy@returnhelper.com

Dear Support Team,

We would like to request webhook setup in Return Helper. Please find the details below:

Email address: <YOUR EMAIL ADDRESS>
Client code:   <YOUR CLIENT CODE>
Endpoint:      https://your-server.example.com/webhook
Environment:   <Sandbox / Production / Both>
Comments:      <Any additional information, or leave blank>

事件傳遞

時間 — 事件可能在觸發動作後幾秒鐘抵達，在極少數情況下可能延遲至幾分鐘後。 重複事件 — 您的端點可能收到相同事件超過一次。請實作冪等處理（例如追蹤已處理的 eventTime + notificationId 組合）。 事件順序 — 不保證傳遞順序。請將您的處理器設計為可以任意順序處理事件。例如，inventoryCreated 可能在 warehouseMarkShipmentArrivedV2 之前抵達。請使用 API 取得您收到的亂序事件中所參考的任何物件。每個事件均包含 ISO 8601 格式的 eventTime 欄位。

通知標頭

每個 Webhook 請求均包含以下標頭：

標頭	類型	說明
`timestamp`	string	ISO 8601 時間戳記
`returnhelper-signature`	string	用於驗證的 HMAC-SHA256 簽章

簽章驗證

在處理任何 Payload 之前，請務必先驗證簽章。請使用原始請求主體 — 任何轉換（例如框架重新序列化 JSON）都會導致驗證失敗。

您的簽署金鑰由 Return Helper 提供（已進行 Base64 編碼）。請妥善保管並切勿暴露。

操作範例

以下為收到的請求範例： 標頭：

{
  "content-type": "application/json; charset=utf-8",
  "returnhelper-signature": "gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=",
  "timestamp": "2024-01-12T09:23:08.4863561Z"
}

主體（原始 JSON，不得重新序列化）：

{"label":{"regions":{"RHCN":"https://label.returnhelperchina.com/label/202401/10595-S240112-0000001-pqk2pvydgxp.pdf"},"labelId":31033,"shipmentId":30385,"apiId":33,"refKey":"S240112-0000001","labelRequestStatusCode":"success","serviceType":"RETURN_ENDICIA_USPS_GROUND_ADVANTAGE_NJ","trackingNumber":"9434611899562082901137","labelUrl":"https://label-service-dev-files.returnshelper.com/label/202401/10595-S240112-0000001-pqk2pvydgxp.pdf","error":null,"qrcodeUrl":null,"qrcodeError":null,"correlationId":null,"cancelCutoffTime":"2024-02-11T09:21:24.0795","meta":null},"category":"labelGenerated","action":"labelGenerated","eventTime":"2024-01-12T09:23:08.4862743Z"}

逐步驗證說明

步驟 1 — 從標頭中提取簽章（用於最後比對）：

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

步驟 2 — 從標頭中提取時間戳記：

2024-01-12T09:23:08.4863561Z

步驟 3 — 建立 string_to_sign 依序串接以下四個值（無分隔符）：

HTTP 方法：POST
您的通知端點 URL：https://s2024-01-12.free.beeceptor.com
步驟 2 的時間戳記
原始 JSON 主體

串接後的字串：

POSThttps://s2024-01-12.free.beeceptor.com2024-01-12T09:23:08.4863561Z{"label":{"regions":...},...}

接著對整個串接字串進行 Base64 編碼。結果即為 string_to_sign：

UE9TVGh0dHBzOi8vczIwMjQtMDEtMTIuZnJlZS5iZWVjZXB0b3IuY29tMjAyNC0wMS0xMlQwOToyMzowOC40ODYzNTYxWnvigJxsYWJlbOKAnTp74oCccmVnaW9uc+KAnTp74oCcUkhDTuKAnTrigJxodHRwczovL2xhYmVsLnJldHVybmhlbHBlcmNoaW5hLmNvbS9sYWJlbC8yMDI0MDEvMTA1OTUtUzI0MDExMi0wMDAwMDAxLXBxazJwdnlkZ3hwLnBkZuKAnX0s4oCcbGFiZWxJZOKAnTozMTAzMyzigJxzaGlwbWVudElk4oCdOjMwMzg1LOKAnGFwaUlk4oCdOjMzLOKAnHJlZktleeKAnTrigJxTMjQwMTEyLTAwMDAwMDHigJ0s4oCcbGFiZWxSZXF1ZXN0SWTigJ06MTA1OTUs4oCcbGFiZWxSZXF1ZXN0U3RhdHVzQ29kZeKAnTrigJxzdWNjZXNz4oCdLOKAnHNlcnZpY2VUeXBl4oCdOuKAnFJFVFVSTl9FTkRJQ0lBX1VTUFNfR1JPVU5EX0FEVkFOVEFHRV9OSuKAnSzigJx0cmFja2luZ051bWJlcuKAnTrigJw5NDM0NjExODk5NTYyMDgyOTAxMTM3IizigJxsYWJlbFVybOKAnTrigJxodHRwczovL2xhYmVsLXNlcnZpY2UtZGV2LWZpbGVzLnJldHVybnNoZWxwZXIuY29tL2xhYmVsLzIwMjQwMS8xMDU5NS1TMjQwMTEyLTAwMDAwMDEtcHFrMnB2eWRneHAucGRm4oCdLOKAnGVycm9y4oCdOm51bGws4oCccXJjb2RlVXJs4oCdOm51bGws4oCccXJjb2RlRXJyb3LigJ06bnVsbCzigJxjb3JyZWxhdGlvbklk4oCdOm51bGws4oCcY2FuY2VsQ3V0b2ZmVGltZeKAnTrigJwyMDI0LTAyLTExVDA5OjIxOjI0LjA3OTUiLOKAnG1ldGHigJ06bnVsbH0s4oCcY2F0ZWdvcnnigJ064oCcbGFiZWxHZW5lcmF0ZWTigJ0s4oCcYWN0aW9u4oCdOuKAnGxhYmVsR2VuZXJhdGVk4oCdLOKAnGV2ZW50VGltZeKAnTrigJwyMDI0LTAxLTEyVDA5OjIzOjA4LjQ4NjI3NDNa4oCdfQ==

步驟 4 — 計算 HMAC-SHA256 簽章 使用範例簽署金鑰（您的實際金鑰將有所不同）：

PEnA0mzKb7fUlGfMgCGhXPjPmPGvW70UU8bkNKdG78WDrQRwzFa572e2JsFIE1e4PLaP9h/ZEvERSR0FBDYNlQ==

操作步驟：

將 string_to_sign（步驟 3）從 Base64 解碼 → 位元組陣列
將您的簽署金鑰從 Base64 解碼 → 位元組陣列
使用簽署金鑰位元組對 string_to_sign 位元組計算 HMAC-SHA256 → 簽章位元組陣列
將簽章位元組陣列進行 Base64 編碼

預期結果：

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

步驟 5 — 比對簽章 將步驟 4 計算出的簽章與步驟 1 提取的簽章進行比對。請使用常數時間字串比對以防止時序攻擊。 額外安全措施： 拒絕 eventTime 與您系統時鐘相差超過 15 分鐘的事件（重放攻擊防護）。

範例程式碼

// Required imports (add at the top of your file):
//   import java.security.InvalidKeyException;
//   import java.security.NoSuchAlgorithmException;
//   import javax.crypto.Mac;
//   import javax.crypto.spec.SecretKeySpec;
//   import org.apache.commons.codec.binary.Base64;

class Main {
  private static final String CHARACTER_ENCODING = "UTF-8";
  final static String ALGORITHM = "HmacSHA256";

  public static void main(String[] args) throws Exception {
    String payload   = "<body JSON string>";
    String action    = "<action>";           // always "POST"
    String url       = "<url>";              // your notification endpoint
    String timestamp = "<timestamp>";        // from header

    String data = new String(
      Base64.encodeBase64((action + url + timestamp + payload).getBytes(CHARACTER_ENCODING))
    );

    String base64Key  = "<signing key>";
    String signature  = sign(data, base64Key);
    System.out.println(signature);
  }

  private static String sign(String data, String secretKey)
      throws NoSuchAlgorithmException, InvalidKeyException {
    Mac mac = Mac.getInstance(ALGORITHM);
    mac.init(new SecretKeySpec(Base64.decodeBase64(secretKey), ALGORITHM));
    byte[] signature = mac.doFinal(Base64.decodeBase64(data));
    return new String(Base64.encodeBase64(signature), CHARACTER_ENCODING);
  }
}

重試機制

請以 2xx HTTP 狀態碼回應以確認已收到。非 2xx 回應將觸發重試。連續 10 次失敗後，傳遞至您端點的通知將暫停 24 小時。

通知主體公共欄位

所有通知主體共享以下頂層欄位：

欄位	類型	說明
`category`	string	通知類別（見下表）
`action`	string	具體事件動作
`eventTime`	string	事件的 ISO 8601 時間戳記
`version`	string	通知結構描述版本
`notificationId`	string	唯一通知 ID（較新的通知中存在）

通知事件參考

通知	`category`	`action`	說明
標籤結果	`labelGenerated`	`labelGenerated`	標籤生成結果（成功或失敗）
倉庫退件運貨單(Return Shipment)抵達（v2）	`rsl`	`markShipmentArrive`	退件運貨單(Return Shipment)已在倉庫收到（目前版本）
庫存已建立	`newInventoryCreated`	`newInventoryCreated`	新退貨庫存(Return Inventory)已建立
圖片已更新	`rrli`	`changeLineItemImage`	明細品項圖片新增、變更或移除
未知來件(Unknown Shipment)已指派	`rsl`	`assignUnknown`	未知來件(Unknown Shipment)已指派給賣家
回收狀態更新	`recall`	`recallUpdateStatus`	回收追蹤號碼或取件狀態已變更
重寄狀態更新	`resend`	`updateResendStatus`	重寄追蹤號碼或狀態已變更
VAS 更新	`rrliv`	`vasUpdated`	增值服務(VAS)已完成或更新
庫存處理完成	`rinv`	`completeInventoryHandling`	處理指示已由倉庫完成
庫存重新校準	`completeRecalibrate`	`completeRecalibrate`	倉庫已更新庫存尺寸／重量
庫存中繼資料已更新	`updateReturnInventoryMeta`	`updateReturnInventoryMeta`	倉庫或使用者新增／更新中繼資料
RMA 已更新	`notifyUserRmaSwapped`	`notifyUserRmaSwapped`	倉庫更正了 RMA 指派
SKU 已更新	`userUpdateReturnInventorySku`	`userUpdateReturnInventorySku`	賣家更新了庫存 SKU
明細品項拆分	`lineItemVasReturnInventoryLineItem`	`splitLineItem`	VAS 將包裹拆分為多個庫存
倉庫備註已更新	`warehouseUpdateWarehouseRemarks`	`warehouseUpdateWarehouseRemarks`	倉庫更新了退貨申請(Return Request)的備註
買家退貨標籤已生成	`buyerReturnRrLabel`	`buyerReturnLabelGenerated`	已為買家生成品牌退貨入口網站標籤
Shopify 買家退貨已建立	`shopifyBuyerCreateReturn`	`shopifyBuyerCreateReturn`	買家透過 Shopify 整合建立了退貨
合併退件運貨單(Return Shipment)費用已更新	`consolidateShippingOrderShippingFeeUpdated`	`consolidateShippingOrderShippingFeeUpdated`	合併退件運貨單(Return Shipment)訂單費用已更新
合併退件運貨單(Return Shipment)全部已打包	`consolidateShippingOrderInventoryAllPacked`	`consolidateShippingOrderInventoryAllPacked`	合併訂單的所有庫存已打包
合併退件運貨單(Return Shipment)已寄出	`consolidateShippingShipmentSent`	`consolidateShippingShipmentSent`	合併退件運貨單(Return Shipment)已派送至承運商
合併退件運貨單(Return Shipment) AWB 已更新	`consolidateShippingShipmentShipped`	`consolidateShippingShipmentShipped`	合併退件運貨單(Return Shipment) AWB 已更新
合併訂單已完成	`consolidateShippingOrderCompleted`	`consolidateShippingOrderCompleted`	合併訂單中所有退件運貨單(Return Shipment)已寄出
合併訂單已取消	`consolidateShippingOrderCancelled`	`consolidateShippingOrderCancelled`	合併訂單已由倉庫強制取消

通知 Payload

標籤結果

當退貨標籤請求完成時發送（成功或失敗）。

請務必使用 shipmentId 將標籤與您系統中的退件運貨單(Return Shipment)進行匹配 — 請勿使用 labelId。在極少數情況下，承運商故障會導致為同一 shipmentId 發出新標籤（具有新的 labelId）。

category: labelGenerated / action: labelGenerated label 中的關鍵欄位：

欄位	說明
`labelId`	標籤識別碼（請勿用於匹配 — 見上方警告）
`shipmentId`	退件運貨單(Return Shipment)識別碼（請使用此欄位進行匹配）
`apiId`	賣家 API ID
`refKey`	退件運貨單(Return Shipment)參考金鑰
`labelRequestStatusCode`	`"success"` 或 `"fail"`
`serviceType`	使用的承運商服務類型
`trackingNumber`	承運商追蹤號碼（成功時）
`labelUrl`	下載標籤 PDF 的 URL（成功時）
`error`	錯誤訊息（失敗時）
`qrcodeUrl`	QR 碼 URL（如適用）
`qrcodeError`	QR 碼錯誤（如適用）
`shipmentInstruction`	退件運貨單(Return Shipment)指示
`correlationId`	請求追蹤的關聯 ID
`cancelCutoffTime`	取消此標籤的截止時間
`meta`	額外中繼資料
`regions`	區域代碼對應地區標籤 URL 的映射

成功範例：

{
  "label": {
    "labelId": 11345,
    "shipmentId": 10825,
    "apiId": 21,
    "refKey": "S210904-0000202",
    "labelRequestStatusCode": "success",
    "serviceType": "usps",
    "trackingNumber": "9201994884299101443342",
    "labelUrl": "https://example.com/label.pdf",
    "qrcodeUrl": "https://example.com/qrcode.png",
    "qrcodeError": null,
    "error": null,
    "correlationId": null,
    "meta": null
  },
  "category": "labelGenerated",
  "action": "labelGenerated",
  "eventTime": "2021-09-04T17:03:15.8888073Z"
}

失敗範例：

{
  "label": {
    "labelId": 11352,
    "shipmentId": 10833,
    "apiId": 21,
    "refKey": "S210906-0000085",
    "labelRequestStatusCode": "fail",
    "serviceType": "ap",
    "trackingNumber": null,
    "labelUrl": null,
    "error": "Your combination of suburb, state & postcode doesn't match.",
    "qrcodeUrl": null,
    "qrcodeError": null
  },
  "category": "labelGenerated",
  "action": "labelGenerated",
  "eventTime": "2021-09-06T08:16:33.4674332Z"
}

倉庫退件運貨單(Return Shipment)抵達（v2）

當倉庫標記退件運貨單(Return Shipment)已收到時發送。此後必定跟隨一個或多個庫存已建立事件。 category: rsl / action: markShipmentArrive / version: 202407 shipment 中的關鍵欄位：

欄位	說明
`shipmentId`	唯一退件運貨單(Return Shipment)識別碼
`returnRequestId`	關聯的退貨申請(Return Request)
`trackingNumber`	承運商追蹤號碼
`sellerReferenceNumber`	您的參考號碼
`serviceType`	使用的運送服務
`customFieldMap`	來自原始退件運貨單(Return Shipment)的自訂欄位
`shipToWarehouseId`	收貨倉庫
`receiveDate`	ISO 8601 收貨時間戳記

{
  "shipment": {
    "shipmentId": "35732",
    "sellerReferenceNumber": "R240725-0000003",
    "returnRequestId": "66848",
    "trackingNumber": "TRACK123456",
    "referenceNumber": "R240725-0000003",
    "serviceType": "fedex",
    "customFieldMap": {
      "customerId": "buyer123"
    },
    "shipToWarehouseId": 2,
    "receiveDate": "2024-07-25T08:53:05.7827073Z"
  },
  "category": "rsl",
  "action": "markShipmentArrive",
  "eventTime": "2024-07-29T05:48:21.381658Z",
  "version": "202407"
}

庫存已建立

在退件運貨單(Return Shipment)收到後（或 VAS 拆分後）發送，通知已建立新的退貨庫存(Return Inventory)記錄。每筆庫存品項發送一個事件 — 若在同一標籤下收到多個包裹，同一退件運貨單(Return Shipment)可能產生多個事件。 category: newInventoryCreated / action: newInventoryCreated returnInventory 中的關鍵欄位：

欄位	說明
`returnInventoryId`	唯一庫存識別碼 — 使用此欄位指派處理
`warehouseId`	存放庫存的倉庫
`rma`	倉庫指派的 RMA 值
`handlingCode`	目前的處理指示
`handlingStatusCode`	目前的處理狀態
`imageList`	收貨時拍攝的圖片
`returnInventoryMetaList`	額外中繼資料（例如來自退件運貨單(Return Shipment)的自訂欄位）

{
  "returnInventory": {
    "returnInventoryId": "19973",
    "warehouseId": 2,
    "apiId": 21,
    "description": "Item description",
    "quantity": 1,
    "dimension1": 20,
    "dimension2": 20,
    "dimension3": 22,
    "dimensionUom": "cm",
    "weight": 300,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 10,
    "handlingCode": "tbc",
    "handlingStatusCode": "pending",
    "completeOn": null,
    "warehouseRemarks": null,
    "handlingUpdatedOn": "2024-07-15T03:29:53.889398",
    "sku": null,
    "rma": "USE-2-240715-D00003-30",
    "modifyOn": "2024-07-15T03:29:53.903982",
    "createOn": "2024-07-15T03:29:53.88968",
    "imageList": [
      {
        "imageUrl": "https://example.com/image1.jpg",
        "imageKey": "images/returns/202407/image1.jpg"
      }
    ],
    "returnInventoryMetaList": [
      {
        "metaType": "shipmentCustomField",
        "metaMap": {
          "customerId": "buyer123"
        }
      }
    ]
  },
  "shipment": {
    "shipmentId": "9999",
    "returnRequestId": "1234",
    "trackingNumber": "TRACK123456",
    "referenceNumber": "",
    "serviceType": "fedex",
    "customFieldMap": {},
    "shipToWarehouseId": 2,
    "receiveDate": "2024-07-15T03:29:00.000000"
  },
  "category": "newInventoryCreated",
  "action": "newInventoryCreated",
  "eventTime": "2024-07-15T03:30:05.1984163Z",
  "version": "202207"
}

圖片已更新

當退貨庫存(Return Inventory)明細品項的圖片被新增、變更或移除時發送。 category: rrli / action: changeLineItemImage 頂層 Payload 欄位：

欄位	類型	說明
`imageUrlList`	字串陣列	此明細品項目前的圖片 URL
`returnRequestLineItem`	物件	受影響的明細品項（見下方）

returnRequestLineItem 中的關鍵欄位：

欄位	說明
`returnRequestLineItemId`	明細品項識別碼
`apiId`	賣家 API ID
`returnRequestId`	關聯的退貨申請(Return Request) ID
`sellerReferenceNumber`	賣家的參考號碼
`description`	品項說明
`quantity`	品項數量
`weight` / `weightUom`	重量及單位
`valueCurrencyCode` / `value`	價值及幣別
`handlingCode`	處理指示
`isDeleted`	明細品項是否已刪除
`rma`	RMA 值
`isFraudulent`	詐騙標記
`fraudReasonCode`	詐騙原因代碼（若已標記）
`customFieldMap`	自訂欄位

{
  "imageUrlList": [
    "https://example.com/return-image-1.png"
  ],
  "returnRequestLineItem": {
    "returnRequestLineItemId": 10759,
    "apiId": 21,
    "returnRequestId": 9237,
    "returnRequestLineItemNumber": "RL210706-0000020",
    "sellerReferenceNumber": "RL210706-0000020",
    "description": "Item description",
    "quantity": 1,
    "weight": 100.0,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 463.0,
    "handlingCode": 0,
    "isDeleted": false
  },
  "category": "rrli",
  "action": "changeLineItemImage",
  "eventTime": "2021-07-06T13:02:24.5575164Z"
}

未知來件(Unknown Shipment)已指派

當沒有先前退貨申請(Return Request)的退件運貨單(Return Shipment)被識別並指派給賣家時發送。 category: rsl / action: assignUnknown / version: 202407 returnInventory 中的關鍵欄位：

欄位	說明
`returnInventoryId`	唯一庫存識別碼
`warehouseId`	存放庫存的倉庫
`apiId`	賣家 API ID
`description`	品項說明
`quantity`	品項數量
`dimension1` / `dimension2` / `dimension3`	測量尺寸
`dimensionUom`	尺寸單位
`weight`	測量重量
`weightUom`	重量單位
`valueCurrencyCode`	價值幣別代碼
`value`	申報價值
`handlingCode`	目前的處理指示
`handlingStatusCode`	目前的處理狀態
`completeOn`	處理完成時間戳記
`warehouseRemarks`	倉庫備註
`handlingUpdatedOn`	最後處理更新時間戳記
`sku`	賣家指派的 SKU
`rma`	倉庫指派的 RMA
`modifyOn` / `createOn`	稽核時間戳記
`imageList`	收貨時拍攝的圖片

unknownShipment 中的關鍵欄位：

欄位	說明
`unknownShipmentId`	唯一未知來件(Unknown Shipment)識別碼
`unknownShipmentNumber`	未知來件(Unknown Shipment)參考號碼
`description`	說明
`unknownShipmentStatusCode`	目前狀態
`unknownShipmentCountryCode`	國家代碼
`warehouseId`	收貨倉庫
`unknownShipmentServiceType`	運送服務類型
`trackingNumber`	承運商追蹤號碼
`totalWeight` / `totalWeightUom`	總重量及單位
`dimension1` / `dimension2` / `dimension3`	測量尺寸
`dimensionUom`	尺寸單位
`totalValue` / `totalValueCurrency`	申報價值及幣別
`modifyOn`	最後修改時間戳記

回收狀態更新

當回收追蹤號碼更新或取件狀態變更時發送。 category: recall / action: recallUpdateStatus recallUpdateTypeStatus 值：

值	回收庫存狀態	說明
`updateTrackingNumber`	`in-transit`	追蹤號碼已指派
`readyToPickUp`	`ready-to-pick-up`	品項已準備好取件
`pickupBySelf`	`picked-up`	由客戶自行取件
`pickupByCourier`	`picked-up`	由當地快遞取件
`pickupByOthers`	`picked-up`	由其他方取件

{
  "recall": {
    "apiId": 103,
    "recallId": 938,
    "recallNumber": "RCL240423-0000001",
    "recallStatusCode": "in-progress",
    "warehouseRemarks": null,
    "recallInventoryList": [
      {
        "recallInventoryId": 1145,
        "returnInventoryId": 18600,
        "recallInventoryStatusCode": "in-transit",
        "pickUpCode": "pending",
        "trackingNumber": "AWB-TRACKING-NUMBER",
        "listName": null,
        "weight": null,
        "amount": null,
        "pickUpOn": null,
        "courierTrackingNumber": null,
        "remarks": null,
        "recallServiceType": "dhl",
        "rma": "USE-1005-240523-D00001-25"
      }
    ]
  },
  "recallUpdateTypeStatus": "updateTrackingNumber",
  "category": "recall",
  "action": "recallUpdateStatus",
  "eventTime": "2024-04-23T07:50:49.2479819Z"
}

重寄狀態更新

當重寄追蹤號碼更新，或重寄完成或失敗時發送。 category: resend / action: updateResendStatus 頂層 Payload 欄位：

欄位	類型	說明
`resend`	物件	重寄訂單詳情（見下方）
`trackingNumber`	string	追蹤號碼（可用時）
`failureReason`	string	失敗原因（重寄失敗時）

resend 中的關鍵欄位：

欄位	說明
`resendId`	唯一重寄訂單識別碼
`apiId`	賣家 API ID
`resendNumber`	重寄訂單號碼
`resendStatusCode`	目前狀態：`1` — 待處理，`2` — 進行中，`3` — 已完成，`4` — 失敗
`description`	訂單說明
`remarks`	賣家備註
`warehouseRemarks`	倉庫備註

檢查 resend.resendStatusCode：

3 — 已完成（檢查 trackingNumber）
4 — 失敗（檢查 failureReason）

VAS 更新

當增值服務(VAS)完成時發送。 category: rrliv / action: vasUpdated updateVasList 中的每個品項：

欄位	說明
`returnRequestLineItemVasId`	VAS 記錄識別碼
`vasResult`	VAS 結果說明
`weight` / `weightUom`	VAS 後的重量及單位
`dimension1` / `dimension2` / `dimension3`	VAS 後的尺寸
`dimensionUom`	尺寸單位
`vasStatusCode`	VAS 狀態代碼
`imageUrlList`	VAS 結果圖片

{
  "updateVasList": [
    {
      "returnRequestLineItemVasId": 1468,
      "vasResult": "VAS result details",
      "weight": 500.0,
      "weightUom": "g",
      "dimension1": 10.0,
      "dimension2": 20.0,
      "dimension3": 30.0,
      "dimensionUom": "cm",
      "vasStatusCode": 1,
      "imageUrlList": null
    }
  ],
  "category": "rrliv",
  "action": "vasUpdated",
  "eventTime": "2021-07-06T12:15:55.9038524Z"
}

庫存處理完成

當倉庫完成處理指示（丟棄、重寄、回收等）時發送。 category: rinv / action: completeInventoryHandling returnInventory 中的關鍵欄位：

欄位	說明
`returnInventoryId`	唯一庫存識別碼
`warehouseId`	存放庫存的倉庫
`returnRequestLineItemId`	關聯的明細品項 ID
`apiId`	賣家 API ID
`returnRequestId`	關聯的退貨申請(Return Request) ID
`sellerReferenceNumber`	賣家的參考號碼
`description`	品項說明
`quantity`	品項數量
`dimension1` / `dimension2` / `dimension3`	測量尺寸
`dimensionUom`	尺寸單位
`weight`	測量重量
`weightUom`	重量單位
`valueCurrencyCode`	價值幣別代碼
`value`	申報價值
`handlingCode`	處理指示（見下表）
`handlingStatusCode`	處理狀態（見下表）
`completeBy`	完成處理的使用者
`completeOn`	完成時間戳記
`warehouseRemarks`	倉庫備註
`handlingUpdatedOn`	最後處理更新時間戳記
`stopAgingOn`	老化停止時間戳記
`sku`	賣家指派的 SKU
`rma`	倉庫指派的 RMA
`returnInventoryMetaList`	額外中繼資料列表

handlingCode 值：

ID	代碼	說明
0	`tbc`	待確認
1	`rtn`	回收
2	`dis`	丟棄
3	`rsd`	重寄
4	`ohd`	暫停
5	`oth`	其他

handlingStatusCode 值：

ID	代碼	說明
0	`pending`	待處理
1	`inProgress`	進行中
2	`completed`	已完成

庫存重新校準

當倉庫更新退貨庫存(Return Inventory)的測量尺寸或重量時發送。 category: completeRecalibrate / action: completeRecalibrate recalibrateSupplement 中的關鍵欄位：

欄位	說明
`warehouseId`	執行重新校準的倉庫
`returnInventoryId`	受影響的庫存 ID
`returnRequestLineItemId`	關聯的明細品項 ID
`rma`	RMA 值
`dimension1` / `dimension2` / `dimension3`	更新後的尺寸
`weight`	更新後的重量
`recalibratedOn`	重新校準時間戳記
`returnInventoryMetaList`	更新後的中繼資料列表（每筆包含 `metaType` 和 `metaMap`）

{
  "recalibrateSupplement": {
    "warehouseId": 8,
    "returnInventoryId": 18191,
    "returnRequestLineItemId": 38320,
    "rma": "USE-1005-240523-D00001-25",
    "dimension1": 20.0,
    "dimension2": 20.0,
    "dimension3": 20.0,
    "weight": 310.0,
    "recalibratedOn": "2024-04-04T00:42:11.1325135Z"
  },
  "category": "completeRecalibrate",
  "action": "completeRecalibrate",
  "eventTime": "2024-04-04T00:54:29.4337417Z"
}

庫存中繼資料已更新

當倉庫或使用者新增或更新退貨庫存(Return Inventory)的中繼資料時發送。 category: updateReturnInventoryMeta / action: updateReturnInventoryMeta Payload 包含與庫存已建立相同結構的 returnInventory，其中包含更新後的 returnInventoryMetaList。 metaType 值：

usr — 使用者提供的中繼資料
whs — 倉庫提供的中繼資料

RMA 已更新

當倉庫更正不正確的 RMA 指派時發送。 category: notifyUserRmaSwapped / action: notifyUserRmaSwapped payload 中的關鍵欄位：

欄位	說明
`userApiId`	賣家 API ID
`clientCode`	客戶代碼
`returnInventoryId`	受影響的庫存 ID
`oldRma`	先前的 RMA 值
`newRma`	新的正確 RMA 值

{
  "payload": {
    "userApiId": 21,
    "clientCode": "RH21",
    "returnInventoryId": "19029",
    "oldRma": "USE-2-240517-D00026-56",
    "newRma": "USE-2-240520-D00001-35"
  },
  "category": "notifyUserRmaSwapped",
  "action": "notifyUserRmaSwapped",
  "eventTime": "2024-05-23T06:26:43.4416977Z"
}

SKU 已更新

當賣家更新退貨庫存(Return Inventory)的 SKU 時發送。 category: userUpdateReturnInventorySku / action: userUpdateReturnInventorySku Payload 包含 returnRequest 和 returnInventory。 returnRequest 中的關鍵欄位：

欄位	說明
`returnRequestId`	唯一退貨申請(Return Request)識別碼
`apiId`	賣家 API ID
`sellerReferenceNumber`	賣家的參考號碼
`returnStatusCode`	退貨申請(Return Request)狀態
`returnTitle`	退貨標題
`totalValue` / `totalValueCurrency`	總申報價值及幣別
`remarks`	備註
`rma`	RMA 值
`isArchived`	申請是否已封存
`returnRequestSourceType`	退貨申請(Return Request)的來源類型

returnInventory 物件遵循與庫存處理完成相同的結構，包含更新後的 sku 欄位。

明細品項拆分

當 VAS 操作將包裹拆分為多個庫存時發送。包含每個產生的包裹的新明細品項和庫存記錄。 category: lineItemVasReturnInventoryLineItem / action: splitLineItem 頂層 Payload 欄位：

欄位	類型	說明
`returnRequestId`	integer	關聯的退貨申請(Return Request) ID
`returnRequestLineItemId`	long	原始明細品項 ID
`returnRequestLineItemVasId`	long	觸發拆分的 VAS 記錄 ID
`vasStatusCode`	string	VAS 狀態代碼
`splitLineItemAndReturnInventoryList`	陣列	產生的拆分品項列表（見下方）

splitLineItemAndReturnInventoryList 中的每個品項包含：

欄位	類型	說明
`returnRequestLineItem`	物件	新的明細品項記錄（包含 `returnRequestLineItemId`、`sellerReferenceNumber`、`description`、`quantity`、`weight`、`weightUom`、`valueCurrencyCode`、`value`、`handlingCode`、`rma`、`customFieldMap`）
`returnInventory`	物件	新的庫存記錄（與庫存處理完成結構相同）
`returnRequestLineItemSupplement`	物件	包含新明細品項尺寸及重量的補充資料

倉庫備註已更新

當倉庫更新退貨申請(Return Request)的備註時發送。 category: warehouseUpdateWarehouseRemarks / action: warehouseUpdateWarehouseRemarks Payload 包含三個物件：

returnRequest — 退貨申請(Return Request)（與 SKU 已更新 → returnRequest 結構相同）
shipment — 包含完整地址詳情、尺寸、重量、費用及 customFieldMap 的退件運貨單(Return Shipment)記錄
returnInventory — 受影響的庫存（與庫存處理完成結構相同），包含更新後的 warehouseRemarks 欄位

買家退貨標籤已生成

當買家在品牌退貨入口網站建立退貨且標籤已生成時發送。

僅適用於整合了 Return Helper 品牌退貨服務的客戶。

category: buyerReturnRrLabel / action: buyerReturnLabelGenerated 請檢查 buyerReturn.labelRequestStatusCode 是否為 "success" 或 "fail"。 buyerReturn 中的關鍵欄位：

欄位	說明
`buyerReturnId`	唯一買家退貨識別碼
`apiId`	賣家 API ID
`sellerReferenceNumber`	賣家的參考號碼
`returnRequestId`	關聯的退貨申請(Return Request) ID（若已建立）
`shipmentId`	關聯的退件運貨單(Return Shipment) ID（若已建立）
`returnRequestNumber`	退貨申請(Return Request)號碼
`shipmentNumber`	退件運貨單(Return Shipment)號碼
`totalValue` / `totalValueCurrency`	申報價值及幣別
`remarks`	備註
`labelId`	標籤 ID
`labelRequestStatusCode`	`"success"` 或 `"fail"`
`trackingNumber`	追蹤號碼（成功時）
`labelFile`	包含 `labelUrl` 和 `labelKey` 的物件
`shipmentInstruction`	退件運貨單(Return Shipment)指示
`error`	錯誤訊息（失敗時）
`warehouseId`	目的地倉庫
`shipmentServiceType`	運送服務類型
`shipmentCountryCode`	退件運貨單(Return Shipment)國家
`shipmentName` / `shipmentPhone` / `shipmentEmail`	聯絡資訊
`shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`	地址行
`shipmentCity` / `shipmentState` / `shipmentPostalCode`	地址詳情
`costCurrencyCode` / `cost`	運送費用
`sellerCostCurrencyCode` / `sellerCost`	賣家費用
`buyerCostCurrencyCode` / `buyerCost`	買家費用
`boxType`	箱型
`weight` / `weightUom`	重量及單位
`dimension1` / `dimension2` / `dimension3` / `dimensionUom`	包裹尺寸
`customFieldMap`	自訂欄位
`buyerReturnLineItemList`	明細品項列表（見下方）

buyerReturnLineItemList 中的每個品項：

欄位	說明
`buyerReturnLineItemId`	明細品項 ID
`sellerReferenceNumber`	賣家的參考號碼
`description`	品項說明
`quantity`	數量
`weight` / `weightUom`	重量及單位
`value` / `valueCurrencyCode`	價值及幣別
`returnReasonCode` / `returnReason`	買家選擇的退貨原因
`customFieldMap`	自訂欄位

Shopify 買家退貨已建立

當買家透過 Shopify 整合建立退貨申請(Return Request)時發送。 category: shopifyBuyerCreateReturn / action: shopifyBuyerCreateReturn shopifyReturn 中的關鍵欄位：

欄位	說明
`shopifyReturnId`	唯一 Shopify 退貨識別碼
`apiId`	賣家 API ID
`referenceNumber`	參考號碼
`returnRequestId`	關聯的退貨申請(Return Request) ID（若已建立）
`shipmentId`	關聯的退件運貨單(Return Shipment) ID（若已建立）
`returnRequestNumber` / `shipmentNumber`	退貨及退件運貨單(Return Shipment)號碼
`totalValue` / `totalValueCurrency`	申報價值及幣別
`remarks`	備註
`labelRequestStatusCode`	標籤狀態：`"success"` 或 `"fail"`
`trackingNumber`	追蹤號碼（成功時）
`labelUrl`	標籤 URL（成功時）
`error`	錯誤訊息（失敗時）
`warehouseId`	目的地倉庫
`shipmentServiceType` / `shipmentCountryCode`	運送服務及國家
`shipmentName` / `shipmentPhone` / `shipmentEmail`	聯絡資訊
`shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`	地址行
`shipmentCity` / `shipmentState` / `shipmentPostalCode`	地址詳情
`costCurrencyCode` / `cost`	運送費用
`boxType`	箱型
`weight` / `weightUom`	重量及單位
`dimension1` / `dimension2` / `dimension3` / `dimensionUom`	包裹尺寸
`shopifyShopId`	Shopify 商店識別碼
`shopifyOrderId` / `shopifyOrderNumber` / `shopifyOrderName`	Shopify 訂單詳情
`shopifyReturnStatusCode`	Shopify 退貨狀態
`requestParty`	發起退貨的一方
`customFieldMap`	自訂欄位

shopifyReturnLineItemList 中的每個品項：

欄位	說明
`shopifyReturnLineItemId`	明細品項 ID
`sellerReferenceNumber`	賣家的參考號碼
`description`	品項說明
`quantity`	數量
`sku`	商品 SKU
`weight` / `weightUom`	重量及單位
`value` / `valueCurrencyCode`	價值及幣別
`returnReasonCode` / `returnReason`	買家選擇的退貨原因
`shopifyProductId`	Shopify 商品 ID
`buyerNotes`	買家備註
`customFieldMap`	自訂欄位

合併退件運貨單(Return Shipment)費用已更新

當合併退件運貨單(Return Shipment)訂單的運送費用更新時發送。 category: consolidateShippingOrderShippingFeeUpdated / action: consolidateShippingOrderShippingFeeUpdated order 中的關鍵欄位：

欄位	說明
`consolidateShippingOrderId`	訂單識別碼
`consolidateShippingOrderNumber`	訂單號碼
`consolidateShippingOrderStatus`	目前狀態
`outboundWarehouseId`	出貨倉庫
`shippingMethod`	運送方式
`shippingFee` / `currencyCode`	更新後的運送費用及幣別
`shipToContactName` / `shipToPhone` / `shipToEmail`	收件人聯絡資訊
`shipToCompanyName`	收件公司
`shipToStreet1` / `shipToStreet2` / `shipToStreet3`	收件地址行
`shipToCity` / `shipToState` / `shipToPostalCode` / `shipToCountry`	收件地址
`deliveryInstructions`	配送指示

合併退件運貨單(Return Shipment)全部已打包

當倉庫已將合併訂單的所有庫存打包入箱時發送。 category: consolidateShippingOrderInventoryAllPacked / action: consolidateShippingOrderInventoryAllPacked order 中的關鍵欄位：

欄位	說明
`consolidateShippingOrderId`	訂單識別碼
`consolidateShippingOrderNumber`	訂單號碼
`consolidateShippingOrderStatus`	目前狀態
`outboundWarehouseId`	出貨倉庫
`shippingFee` / `currencyCode`	運送費用及幣別
`shippingMethod`	運送方式
`customFieldMap`	自訂欄位
`deliveryInstructions`	配送指示
`shipmentList`	退件運貨單(Return Shipment)列表（見下方）

shipmentList 中的每個品項：

欄位	說明
`consolidateShippingShipmentId`	退件運貨單(Return Shipment)識別碼
`consolidateShippingShipmentNumber`	退件運貨單(Return Shipment)號碼
`consolidateShippingShipmentStatus`	退件運貨單(Return Shipment)狀態
`awb`	航空退件運貨單(Return Shipment)號碼
`serviceProvider`	承運商服務提供商
`shipDate`	出貨日期
`boxList`	此退件運貨單(Return Shipment)的箱子列表

boxList 中的每個品項：

欄位	說明
`consolidateShippingShipmentBoxId`	箱子識別碼
`boxNumber`	箱子號碼
`consolidateShippingShipmentBoxStatus`	箱子狀態
`consolidateShippingInventoryList`	此箱子中的庫存

consolidateShippingInventoryList 中的每個品項：

欄位	說明
`consolidateShippingInventoryId`	庫存識別碼
`returnInventoryId`	關聯的退貨庫存(Return Inventory) ID
`rma`	RMA 值
`consolidateShippingInventoryStatus`	庫存狀態

合併退件運貨單(Return Shipment)已寄出

當倉庫將合併退件運貨單(Return Shipment)派送至承運商時發送。 category: consolidateShippingShipmentSent / action: consolidateShippingShipmentSent shipment 中的關鍵欄位：

欄位	說明
`consolidateShippingShipmentId`	退件運貨單(Return Shipment)識別碼
`consolidateShippingShipmentNumber`	退件運貨單(Return Shipment)號碼
`consolidateShippingShipmentStatus`	目前狀態
`awb`	航空退件運貨單(Return Shipment)號碼
`serviceProvider`	承運商服務提供商
`shipDate`	出貨日期
`boxList`	箱子列表（與全部已打包 → boxList結構相同）
`consolidateShippingOrderId`	上層訂單識別碼
`consolidateShippingOrderNumber`	上層訂單號碼
`consolidateShippingOrderStatus`	上層訂單狀態
`outboundWarehouseId`	出貨倉庫
`customFieldMap`	自訂欄位

合併退件運貨單(Return Shipment) AWB 已更新

當合併退件運貨單(Return Shipment)的航空退件運貨單(Return Shipment)號碼更新時發送。 category: consolidateShippingShipmentShipped / action: consolidateShippingShipmentShipped shipment 物件遵循與合併退件運貨單(Return Shipment)已寄出相同的結構，包含更新後的 awb 欄位。

合併訂單已完成

當合併訂單中所有退件運貨單(Return Shipment)均已寄出時發送。 category: consolidateShippingOrderCompleted / action: consolidateShippingOrderCompleted order 物件遵循與合併退件運貨單(Return Shipment)全部已打包相同的結構，包含完整的 shipmentList（含 boxList 及庫存詳情）。

合併訂單已取消

當倉庫強制取消合併退件運貨單(Return Shipment)訂單時發送。 category: consolidateShippingOrderCancelled / action: consolidateShippingOrderCancelled order 中的關鍵欄位：

欄位	說明
`consolidateShippingOrderId`	訂單識別碼
`consolidateShippingOrderNumber`	訂單號碼
`consolidateShippingOrderStatus`	目前狀態（已取消）
`outboundWarehouseId`	出貨倉庫
`shippingMethod`	運送方式
`shippingFee`	運送費用
`deliveryInstructions`	配送指示
`customFieldMap`	自訂欄位

事件

​概覽

​設定您的 Webhook 端點

​端點要求

​註冊您的端點

​事件傳遞

​通知標頭

​簽章驗證

​操作範例

​逐步驗證說明

​範例程式碼

​重試機制

​通知主體公共欄位

​通知事件參考

​通知 Payload

​標籤結果

​倉庫退件運貨單(Return Shipment)抵達（v2）

​庫存已建立

​圖片已更新

​未知來件(Unknown Shipment)已指派

​回收狀態更新

​重寄狀態更新

​VAS 更新

​庫存處理完成

​庫存重新校準

​庫存中繼資料已更新

​RMA 已更新

​SKU 已更新

​明細品項拆分

​倉庫備註已更新

​買家退貨標籤已生成

​Shopify 買家退貨已建立

​合併退件運貨單(Return Shipment)費用已更新

​合併退件運貨單(Return Shipment)全部已打包

​合併退件運貨單(Return Shipment)已寄出

​合併退件運貨單(Return Shipment) AWB 已更新

​合併訂單已完成

​合併訂單已取消

概覽

設定您的 Webhook 端點

端點要求

註冊您的端點

事件傳遞

通知標頭

簽章驗證

操作範例

逐步驗證說明

範例程式碼

重試機制

通知主體公共欄位

通知事件參考

通知 Payload

標籤結果

倉庫退件運貨單(Return Shipment)抵達（v2）

庫存已建立

圖片已更新

未知來件(Unknown Shipment)已指派

回收狀態更新

重寄狀態更新

VAS 更新

庫存處理完成

庫存重新校準

庫存中繼資料已更新

RMA 已更新

SKU 已更新

明細品項拆分

倉庫備註已更新

買家退貨標籤已生成

Shopify 買家退貨已建立

合併退件運貨單(Return Shipment)費用已更新

合併退件運貨單(Return Shipment)全部已打包

合併退件運貨單(Return Shipment)已寄出

合併退件運貨單(Return Shipment) AWB 已更新

合併訂單已完成

合併訂單已取消