Webhooks 與通知 - Return Helper API

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

概覽

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

欄位可能隨時新增。 Return Helper 會在不事先通知的情況下於 Webhook 負載中新增欄位。請勿對負載結構進行嚴格驗證——請忽略無法識別的欄位，並照常回傳 2xx。

設定您的 Webhook 端點

端點要求

在註冊端點之前，請確保您的端點符合以下要求：

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

註冊您的端點

請透過 API 自行註冊及管理您的 Webhook 端點：

用途	呼叫
註冊端點	新增 Notification Endpoint
查看已註冊的端點	列出 Notification Endpoints
移除端點	刪除 Notification Endpoint

請先部署您的處理器，再進行註冊。Return Helper 會向該 URL 發送一次已簽章的驗證請求，只有在 30 秒內回傳 2xx 狀態時，端點才會被儲存。每個已註冊的端點都會收到您帳戶的所有事件。請在您這一端依 category 與 action 欄位進行篩選。沙箱環境與正式環境需分別註冊。請在每個需要接收通知的環境中，使用該環境的憑證呼叫 API。

事件傳遞

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

通知標頭

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

標頭	類型	說明
`RETURNHELPER-TRIGGERED-AT`	string	ISO 8601 格式的 UTC 時間戳記，例如 `2026-08-14T09:31:02.1234567Z`。此值即為簽章驗證所使用的時間戳記。
`RETURNHELPER-API-ID`	string	該通知所屬帳戶的 `apiId`。可透過取得 API 帳戶資訊查詢您的值。
`RETURNHELPER-API-NAME`	string	該帳戶的 `apiName`。
`ReturnHelper-Signature`	string	用於驗證的 HMAC-SHA256 簽章——請參閱簽章驗證。

舊版標頭

以下標頭仍會隨每則通知送出，且不會被移除。新的整合請改為讀取上方的標頭。

舊版標頭	由何者取代
`Timestamp`	`RETURNHELPER-TRIGGERED-AT`——完全相同的值，逐字一致。
`x-returnhelper-apiname`	`RETURNHELPER-API-NAME`——相同的值。

HTTP 標頭名稱不區分大小寫，部分框架會將其正規化。上表為 Return Helper 實際送出的大小寫形式；若您的框架會將傳入的標頭名稱轉為小寫，請以不區分大小寫的方式比對。

簽章驗證

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

您的簽署金鑰由 Return Helper 提供（已進行 Base64 編碼）。請妥善保管並切勿暴露。您可以在使用者入口網站中與 API Key 和 Token 相同的畫面找到它——請參閱認證一節中的截圖；也可以使用取得 Signing Key以程式方式讀取。

操作範例

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

{
  "content-type": "application/json; charset=utf-8",
  "ReturnHelper-Signature": "gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=",
  "RETURNHELPER-TRIGGERED-AT": "2024-01-12T09:23:08.4863561Z",
  "RETURNHELPER-API-ID": "12345",
  "RETURNHELPER-API-NAME": "Acme Returns",
  "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 — 從 ReturnHelper-Signature 標頭中提取簽章（用於最後比對）：

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

步驟 2 — 從 RETURNHELPER-TRIGGERED-AT 標頭中提取時間戳記：

2024-01-12T09:23:08.4863561Z

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

HTTP 方法：POST
您的通知端點 URL：https://s2024-01-12.free.beeceptor.com
步驟 2 取得的 RETURNHELPER-TRIGGERED-AT 值
原始 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 RETURNHELPER-TRIGGERED-AT 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);
  }
}

// Node.js built-in module. Import at the top of your file:
//   import * as crypto from 'node:crypto';   // ESM
//   const crypto = require('node:crypto');   // CommonJS

function sign(data, secretKey) {
  const key        = Buffer.from(secretKey, 'base64');
  const hmac       = crypto.createHmac('sha256', key);
  const dataBuffer = Buffer.from(data, 'base64');
  hmac.update(dataBuffer);
  return hmac.digest('base64');
}

async function main() {
  const payload   = '<body JSON string>'; // raw request body
  const action    = '<action>';           // always "POST"
  const url       = '<url>';              // your notification endpoint
  const timestamp = '<timestamp>';        // from RETURNHELPER-TRIGGERED-AT header

  const encodedData = Buffer.from(action + url + timestamp + payload).toString('base64');
  const base64Key   = '<signing key>';
  const signature   = sign(encodedData, base64Key);

  console.log('Signature:', signature);
}

main().catch(console.error);

// Node.js built-in module. Import at the top of your file:
//   import * as crypto from 'node:crypto';

function sign(data: string, secretKey: string): string {
  const key         = Buffer.from(secretKey, 'base64');
  const hmac        = crypto.createHmac('sha256', key);
  const decodedData = Buffer.from(data, 'base64');
  hmac.update(decodedData);
  return hmac.digest('base64');
}

function main() {
  const payload   = '<body JSON string>'; // raw request body
  const action    = '<action>';           // always "POST"
  const url       = '<url>';              // your notification endpoint
  const timestamp = '<timestamp>';        // from RETURNHELPER-TRIGGERED-AT header

  const encodedData = Buffer.from(action + url + timestamp + payload, 'utf-8').toString('base64');
  const base64Key   = '<signing key>';
  const signature   = sign(encodedData, base64Key);

  console.log(signature);
}

main();

public class Main {
    private static final String ALGORITHM = 'HmacSHA256';

    public static void main() {
        String payload   = '<body JSON string>'; // raw request body
        String action    = '<action>';            // always 'POST'
        String url       = '<url>';               // your notification endpoint
        String timestamp = '<timestamp>';         // from RETURNHELPER-TRIGGERED-AT header

        Blob data        = EncodingUtil.base64Encode(
                               Blob.valueOf(action + url + timestamp + payload));
        String base64Key = '<signing key>';
        String signature = sign(data, base64Key);
        System.debug(signature);
    }

    private static String sign(Blob data, String secretKey) {
        Blob macKey   = EncodingUtil.base64Decode(secretKey);
        Blob sigBytes = Crypto.generateMac(ALGORITHM, data, macKey);
        return EncodingUtil.base64Encode(sigBytes);
    }
}

重試機制

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

通知主體公共欄位

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

欄位	類型	說明
`category`	string	通知類別（見下表）
`action`	string	具體事件動作
`eventTime`	string	事件的 ISO 8601 時間戳記
`version`	string	通知結構描述版本
`notificationId`	string	每次推送均有；用作等冪鍵即可。

通知事件參考

通知	`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 已更新
合併退件運貨單(Return Shipment)已到達	`consolidateShippingShipmentArrived`	`consolidateShippingShipmentArrived`	寄往 RH 倉庫的 Shipment 已到達並已收費
合併訂單已完成	`consolidateShippingOrderCompleted`	`consolidateShippingOrderCompleted`	合併訂單的所有明細已寄出
合併訂單已取消	`consolidateShippingOrderCancelled`	`consolidateShippingOrderCancelled`	合併訂單已由倉庫強制取消
交易已新增	`transaction`	`addTransaction`	您的帳戶記入了一筆扣款、退款或儲值

通知 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，以區域代碼為鍵。請參閱區域標籤 URL。

區域標籤 URL

regions 提供與 labelUrl 同一標籤檔案的其他 URL。在對應區域下載或列印標籤時使用。

鍵	主機	使用情境
`RHCN`	`label.returnhelperchina.com`	在中國大陸下載或列印標籤

每個值都指向與 labelUrl 相同的 PDF，僅主機不同。
所有帳戶皆包含此欄位，無需任何設定。
僅 labelGenerated 事件包含此欄位。API 回應及其他 Webhook 事件中的標籤 URL 僅使用 labelUrl 的主機。如需區域 URL，請從此事件中儲存。
當 labelUrl 為 null（標籤請求失敗）時，regions 為 {}。
請忽略無法識別的鍵。若所需的鍵不存在，請使用 labelUrl。

成功範例：

{
  "label": {
    "regions": {
      "RHCN": "https://label.returnhelperchina.com/label/202109/example-S210904-0000202.pdf"
    },
    "labelId": 11345,
    "shipmentId": 10825,
    "apiId": 21,
    "refKey": "S210904-0000202",
    "labelRequestStatusCode": "success",
    "serviceType": "usps",
    "trackingNumber": "9201994884299101443342",
    "labelUrl": "https://label.returnhelpercentre.com/label/202109/example-S210904-0000202.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": {
    "regions": {},
    "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)已收到時發送。此後必定跟隨一個或多個庫存已建立事件。

此事件會回傳您的 sellerReferenceNumber，是您的訂單紀錄與 Return Helper 識別碼之間的主要對帳點。預設的 V202207 會在一份打包負載中攜帶三個層級的 SRN；V202407 僅攜帶 Shipment 層級的 SRN。完整的對帳工作流與版本差異見 Seller Reference Number。

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)可能產生多個事件。

此負載中沒有 sellerReferenceNumber。 returnInventory 與 shipment 都不攜帶 sellerReferenceNumber；只有 shipment.referenceNumber 存在，而該欄位回傳的是您傳入的 orderNumber——並非賣家參考號。如果您依賴 sellerReferenceNumber 將庫存與您自己的紀錄對帳，請不要只訂閱 newInventoryCreated。請同時訂閱 Warehouse Shipment Arrived（V202207 下在三個層級都攜帶 SRN）或 Inventory Handling Complete（在 returnInventory.sellerReferenceNumber 上攜帶 Line Item 層級的 SRN）。完整的對帳策略見 Seller Reference Number。

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",
    "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://file.returnhelpercentre.com/img/returns/202606/27_1000040536_lmpiohbx.5n3.jpg",
    "https://file.returnhelpercentre.com/images/returns/202603/16209788537041243876_USE-21-260303-P00156-19_..._4290.jpg"
  ],
  "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"
}

imageUrlList 中的 URL 可公開存取、不會過期，可在用戶端安全快取。請直接保存使用。空狀態：imageUrlList: []。

未知來件(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
`imageList`	收貨時拍攝的圖片

unknownShipment 中的關鍵欄位：

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

回收狀態更新

Recall 即將停用。要把庫存寄至 Return Helper 香港倉庫，請建立 destinationType: RH_WAREHOUSE 的 Consolidate Shipping Order。

當回收追蹤號碼更新或取件狀態變更時發送。 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`	物件	重寄訂單詳情（見下方）
`returnInventoryList`	陣列	本次重寄的庫存項目
`resendShipmentList`	陣列	此重寄對應的重寄運貨單（見下方）

resend 中的關鍵欄位：

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

每筆 resendShipmentList 項目中的關鍵欄位：

欄位	說明
`resendShipmentId`	重寄運貨單識別碼
`resendId`	此運貨單所屬的重寄訂單
`resendShipmentNumber`	重寄運貨單號碼
`trackingNumber`	承運商追蹤號碼（可用時）
`sellerReferenceNumber`	您自己為此補寄設定的參考編號
`error`	錯誤訊息（運貨單失敗時）

resendShipmentList 總是只有一筆項目——一筆重寄有且僅有一張重寄運貨單。請直接讀取 resendShipmentList[0]。

trackingNumber 不是頂層欄位，它位於重寄運貨單內：resendShipmentList[0].trackingNumber。

檢查 resend.resendStatusCode：

3 — 已完成（讀取 resendShipmentList[0].trackingNumber）
4 — 失敗（讀取 resendShipmentList[0].error）

{
  "resend": {
    "resendId": 2902,
    "apiId": 21,
    "resendNumber": "RSD221003-0000001",
    "resendStatusCode": 3
  },
  "returnInventoryList": [
    {
      "returnInventoryId": 14129,
      "rma": "SGP240101-0000001"
    }
  ],
  "resendShipmentList": [
    {
      "resendShipmentId": 2897,
      "resendId": 2902,
      "resendShipmentNumber": "RSDS221003-0000001",
      "trackingNumber": "9201994884299101443342",
      "sellerReferenceNumber": "ORDER-0001",
      "error": null
    }
  ],
  "category": "resend",
  "action": "updateResendStatus"
}

使用 resendShipmentList[0].sellerReferenceNumber 將事件對應到您自己的訂單紀錄，就不必儲存 Return Helper 的 resendId。

只有當補寄是由 Enterprise 帳戶透過以 SKU 建立 Resend 建立、且有提供參考編號時，sellerReferenceNumber 才會有值；其餘補寄一律為 null。若要以該值即時查詢補寄，請使用以 Seller Reference Number 搜尋 Resend。

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": 65205,
      "vasResult": "VAS result details",
      "weight": 1000.0,
      "weightUom": "g",
      "dimension1": 25.0,
      "dimension2": 20.0,
      "dimension3": 10.0,
      "dimensionUom": "cm",
      "vasStatusCode": "SUCCESSFUL",
      "imageUrlList": [
        "https://file.returnhelpercentre.com/img/returns/202606/27_1000011051_eu4jjyfj.wth.jpg",
        "https://file.returnhelpercentre.com/img/returns/202606/27_1000011050_0nfetxuv.5hb.jpg"
      ]
    }
  ],
  "category": "rrliv",
  "action": "vasUpdated",
  "eventTime": "2021-07-06T12:15:55.9038524Z"
}

imageUrlList 中的 URL 可公開存取、不會過期，可在用戶端安全快取。請直接保存使用。空狀態：imageUrlList: []（某些 VAS 類型不產生圖片；這些項目仍出現在 updateVasList[] 中，但 imageUrlList 為空陣列）。

庫存處理完成

當倉庫完成處理指示（丟棄、重寄、回收等）時發送。 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`	一律為 `null`
`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`	一律為 `null`
`customFieldMap`	自訂欄位
`deliveryInstructions`	配送指示
`shipmentList`	退件運貨單(Return Shipment)列表（見下方）

shipmentList 中的每個品項：

欄位	說明
`consolidateShippingShipmentId`	退件運貨單(Return Shipment)識別碼
`consolidateShippingShipmentNumber`	退件運貨單(Return Shipment)號碼
`consolidateShippingShipmentStatus`	退件運貨單(Return Shipment)狀態
`boxList`	此退件運貨單(Return Shipment)的箱子列表

boxList 中的每個品項：

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

consolidateShippingInventoryList 中的每個品項：

欄位	說明
`consolidateShippingInventoryId`	明細識別碼
`itemType`	`RMA` 或 `FNSKU`
`returnInventoryId` / `rma`	僅 `RMA` 明細，否則為 `null`
`fnsku`	僅 `FNSKU` 明細，否則為 `null`
`quantity`	此明細在該箱中的件數。`RMA` 明細一律為 `1`
`consolidateShippingInventoryStatus`	明細狀態

一個箱子可裝 RMA 明細、FNSKU 明細或兩者。不含 RMA 明細的箱子同樣會列出。

合併退件運貨單(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 欄位。對於 RH_WAREHOUSE 訂單，倉庫記錄 AWB 時會發送此事件。consolidateShippingShipmentStatus 為 IN_TRANSIT，此時尚未收費：Shipment 到達時才收費，並透過合併退件運貨單(Return Shipment)已到達通知。

合併退件運貨單(Return Shipment)已到達

RH_WAREHOUSE 訂單的每個 Shipment 到達 Return Helper 倉庫並收取運費時，各發送一次。 category: consolidateShippingShipmentArrived / action: consolidateShippingShipmentArrived / version: 202609

版本 202609 需要申請開通。請聯絡 Return Helper 客服。

欄位	說明
`order`	訂單。`order.shipmentList` 只包含已到達的這個 Shipment。
`arrivedShipmentCount`	此訂單中含明細且已到達的 Shipment 數（包括本次）
`totalShipmentCount`	此訂單中含明細的 Shipment 數。空的 Shipment 不計入。

含明細的 Shipment 有 3 個的訂單會發送 3 次事件：1/3、2/3、3/3。 order 中的欄位：

欄位	說明
`consolidateShippingOrderId` / `consolidateShippingOrderNumber`	訂單識別碼
`apiId`	您的帳戶 ID
`consolidateShippingOrderStatus`	訂單狀態
`outboundWarehouseId`	出貨倉庫
`destinationType`	`RH_WAREHOUSE`
`destinationWarehouseId`	目的地倉庫
`shippingFee` / `currencyCode`	截至目前的訂單運費
`customFieldMap` / `deliveryInstructions`	訂單上設定的值
`shipmentList`	已到達的 Shipment（見下方）

版本 202609 不包含 shippingMethod。 shipmentList 中的每個品項：

欄位	說明
`consolidateShippingShipmentId` / `consolidateShippingShipmentNumber`	Shipment 識別碼
`consolidateShippingShipmentStatus`	`READY_TO_PICKUP`
`awb`	Air Waybill 號碼
`chargeableWeight`	計費重量（公克）
`boxList`	此 Shipment 的箱子，每個箱子含 `consolidateShippingShipmentBoxId`、`boxNumber`、`consolidateShippingShipmentBoxStatus` 和 `consolidateShippingInventoryList`

consolidateShippingInventoryList 中的每個品項：

欄位	說明
`consolidateShippingInventoryId`	明細識別碼
`itemType`	`RMA` 或 `FNSKU`
`returnInventoryId` / `rma`	僅 `RMA` 明細，否則為 `null`
`fnsku`	僅 `FNSKU` 明細，否則為 `null`
`quantity`	該箱中的件數
`consolidateShippingInventoryStatus`	明細狀態

{
  "category": "consolidateShippingShipmentArrived",
  "action": "consolidateShippingShipmentArrived",
  "eventTime": "2026-10-05T03:12:45Z",
  "version": "202609",
  "notificationId": "01K6X2M8Q4R7T9V1W3Y5Z7B9C1",
  "order": {
    "consolidateShippingOrderId": "01K6RA4F7H9J2K5M8N1P3Q6S8T",
    "consolidateShippingOrderNumber": "CNS260928-0000123",
    "apiId": 12345,
    "consolidateShippingOrderStatus": "PARTIALLY_SHIPPED",
    "outboundWarehouseId": 101,
    "destinationType": "RH_WAREHOUSE",
    "destinationWarehouseId": 1,
    "shippingFee": 27.0,
    "currencyCode": "usd",
    "customFieldMap": {},
    "deliveryInstructions": null,
    "shipmentList": [
      {
        "consolidateShippingShipmentId": "01K6T1B3D5F7H9K2M4P6R8T0V2",
        "consolidateShippingShipmentNumber": "CNSS260930-0000045",
        "consolidateShippingShipmentStatus": "READY_TO_PICKUP",
        "awb": "TRACK123456789",
        "chargeableWeight": 2400,
        "boxList": [
          {
            "consolidateShippingShipmentId": "01K6T1B3D5F7H9K2M4P6R8T0V2",
            "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
            "boxNumber": "1",
            "consolidateShippingShipmentBoxStatus": "SHIPPED",
            "consolidateShippingInventoryList": [
              {
                "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
                "consolidateShippingInventoryId": "01K6RB2C4E6G8J1L3N5Q7S9U1W",
                "itemType": "RMA",
                "returnInventoryId": 987654,
                "rma": "USE-2-260915-D00003-30",
                "fnsku": null,
                "quantity": 1,
                "consolidateShippingInventoryStatus": "SHIPPED"
              },
              {
                "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
                "consolidateShippingInventoryId": "01K6RB3D5F7H9K2M4P6R8T0V2X",
                "itemType": "FNSKU",
                "returnInventoryId": null,
                "rma": null,
                "fnsku": "X00EXAMPLE1",
                "quantity": 6,
                "consolidateShippingInventoryStatus": "SHIPPED"
              }
            ]
          }
        ]
      }
    ]
  },
  "arrivedShipmentCount": 1,
  "totalShipmentCount": 2
}

合併訂單已完成

合併訂單的所有明細都已寄出時發送。對於 RH_WAREHOUSE 訂單，所有含明細的 Shipment 也必須已到達；此事件在訂單最後一個合併退件運貨單(Return Shipment)已到達之後發送。 category: consolidateShippingOrderCompleted / action: consolidateShippingOrderCompleted order 物件遵循與合併退件運貨單(Return Shipment)全部已打包相同的結構，包含完整的 shipmentList（含 boxList 及庫存詳情）。

合併訂單已取消

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

欄位	說明
`consolidateShippingOrderId`	訂單識別碼
`consolidateShippingOrderNumber`	訂單號碼
`consolidateShippingOrderStatus`	`CANCELED`
`outboundWarehouseId`	出貨倉庫
`shippingMethod`	一律為 `null`
`shippingFee`	運送費用
`deliveryInstructions`	配送指示
`customFieldMap`	自訂欄位

交易已新增

每當有交易記入您的帳戶時發送一次，包括扣款、退款、重新扣款及儲值。

apiTransaction.notes 通常會說明該交易對應的操作，因此您無須解析 headId 即可了解交易內容。

category: transaction / action: addTransaction / version: 202610 apiTransaction 中的關鍵欄位：

欄位	類型	說明
`apiTransactionId`	long	交易識別碼
`transactionNumber`	string	交易號碼，例如 `T2600012345`。每筆交易皆唯一。
`apiId`	long	您的 API 帳戶 ID
`currencyCode`	string	貨幣代碼，小寫（例如 `usd`）
`transactionType`	string	交易類型代碼。名稱見取得所有交易類型
`headId`	string	該交易所記帳的紀錄 ID。取決於 `transactionType`；見 headId 對應的紀錄。
`amount`	number	帶正負號的金額。負數為扣款；正數為退款或儲值。
`notes`	string	供人閱讀的說明。措辭可能變更，請勿解析。
`createOn`	string	交易記入的時間（UTC，ISO 8601）
`createBy`	string

apiBalance 中的關鍵欄位：

欄位	類型	說明
`apiBalanceId`	long	餘額紀錄識別碼
`apiId`	long	您的 API 帳戶 ID
`currencyCode`	string	貨幣代碼，小寫
`balance`	number	該交易記入後，您在 `currencyCode` 幣別下的餘額

balance 是該交易記入當下的值，而非您目前的餘額。事件可能不依順序送達。如需目前餘額，請呼叫取得 API 帳戶餘額。

{
  "apiTransaction": {
    "apiTransactionId": 100245,
    "transactionNumber": "T2600012345",
    "apiId": 21,
    "currencyCode": "usd",
    "transactionType": "csl",
    "headId": "11345",
    "amount": -12.960,
    "notes": "charge for shipment:30385",
    "createOn": "2026-10-12T03:29:11.180251",
    "createBy": "21"
  },
  "apiBalance": {
    "apiBalanceId": 7,
    "apiId": 21,
    "currencyCode": "usd",
    "balance": 1520.350
  },
  "category": "transaction",
  "action": "addTransaction",
  "eventTime": "2026-10-12T03:29:11.2396605Z",
  "version": "202610",
  "notificationId": "01J8HV4X54S8AV4FY0SJKVM7QW"
}

headId 對應的紀錄

在下表中找到 transactionType，再將 headId 與您已從所列事件或回應中取得的 ID 進行比對。headId 一律為字串。退款或重新扣款的 headId 與其所調整的扣款相同。

`headId` 為	`transactionType`	取得此 ID 的位置
您的 `apiId`	`chr`, `top`, `acs`, `acf`, `rtp`	`RETURNHELPER-API-ID` 標頭，或取得 API 帳戶資訊
`labelId`	`csl`, `rcl`, `RECHARGE_SHIPPING_LABEL`, `rsl`¹	標籤結果中的 `label.labelId`
`returnRequestId`	`bps`, `brt`, `sps`, `REFUND_CANCEL_BUYER_RETURN_LABEL`, `REFUND_CANCEL_SHOPIFY_RETURN_LABEL`, `rsl`¹	買家退貨標籤已生成、Shopify 買家退貨已建立
`returnInventoryId`	`bbc`, `brc`, `fbr`, `cup`, `dis`, `soh`, `swh`, `CANCELED_LABEL_ARRIVED`, `CANCELED_LABEL_PENALTY`, `CONSOLIDATE_SHIPPING_OUTBOUND`	庫存已建立、倉庫退件運貨單(Return Shipment)抵達（v2）
`returnInventoryId`	`REFUND_` / `RECHARGE_` + `CLAIM_UNKNOWN`, `BUYER_RETURN`, `BOUNCE_BACK`, `FBA_RESTOCK`, `CANCELED_LABEL_ARRIVED`, `CANCELED_LABEL_PENALTY`	同上
`returnRequestLineItemVasId`	`rpk`, `tpc`, `pin`	VAS 更新
`resendId`	`rmh`, `rlr`	建立 Resend Order 回應、重寄狀態更新
重寄庫存紀錄 ID	`rsh`	不會在任何 API 回應或 webhook 中回傳
`fbaInstructionId`	`fbd`, `frh`	建立 FBA Instructions 回應
`fbaShipmentId`	`fih`, `fch`	建立 FBA Shipment 回應
`consolidateShippingShipmentBoxId`	`CONSOLIDATE_SHIPPING_MERGE`	合併退件運貨單(Return Shipment)全部已打包中的 `boxList`
`consolidateShippingInventoryId`	`CONSOLIDATE_SHIPPING_OUTBOUND_FNSKU`	合併退件運貨單(Return Shipment)全部已打包中的 `consolidateShippingInventoryList`
`consolidateShippingShipmentId`	`CONSOLIDATE_SHIPPING_SHIPMENT`	合併退件運貨單(Return Shipment)已寄出

¹ rsl 為生成失敗的標籤退款。headId 為 labelId；若失敗的標籤是買家退貨標籤，則為 returnRequestId。

所有交易都會發送；您無法只訂閱個別類型。請依 transactionType 及 amount 的正負進行分支處理。
可能會新增 transactionType 值。遇到無法識別的類型時，仍請記錄 amount 及 balance；請勿拒收該事件。
一個退件運貨單(Return Shipment)可能有多張標籤，因此可能有多筆 csl。請使用標籤結果將 labelId 對應至 shipmentId。
createOn 是交易記入的時間；eventTime 是通知發送的時間。

​概覽

​設定您的 Webhook 端點

​端點要求

​註冊您的端點

​事件傳遞

​通知標頭

​舊版標頭

​簽章驗證

​操作範例

​逐步驗證說明

​範例程式碼

​重試機制

​通知主體公共欄位

​通知事件參考

​通知 Payload

​標籤結果

​區域標籤 URL

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

​庫存已建立

​圖片已更新

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

​回收狀態更新

​重寄狀態更新

​VAS 更新

​庫存處理完成

​庫存重新校準

​庫存中繼資料已更新

​RMA 已更新

​SKU 已更新

​明細品項拆分

​倉庫備註已更新

​買家退貨標籤已生成

​Shopify 買家退貨已建立

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

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

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

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

​合併退件運貨單(Return Shipment)已到達

​合併訂單已完成

​合併訂單已取消

​交易已新增

​headId 對應的紀錄

概覽

設定您的 Webhook 端點

端點要求

註冊您的端點

事件傳遞

通知標頭

舊版標頭

簽章驗證

操作範例

逐步驗證說明

範例程式碼

重試機制

通知主體公共欄位

通知事件參考

通知 Payload

標籤結果

區域標籤 URL

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

庫存已建立

圖片已更新

未知來件(Unknown Shipment)已指派

回收狀態更新

重寄狀態更新

VAS 更新

庫存處理完成

庫存重新校準

庫存中繼資料已更新

RMA 已更新

SKU 已更新

明細品項拆分

倉庫備註已更新

買家退貨標籤已生成

Shopify 買家退貨已建立

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

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

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

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

合併退件運貨單(Return Shipment)已到達

合併訂單已完成

合併訂單已取消

交易已新增

headId 對應的紀錄