> ## 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.

# Webhooks 與通知

> 接收來自 Return Helper 的非同步事件通知

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

<h2 id="overview">
  概覽
</h2>

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

<h2 id="setting-up-your-webhook-endpoint">
  設定您的 Webhook 端點
</h2>

<h3 id="endpoint-requirements">
  端點要求
</h3>

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

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

<h3 id="registering-your-endpoint">
  註冊您的端點
</h3>

如需註冊 Webhook 端點，請填寫 [Webhook 設定申請表](https://forms.gle/iBVkRZvfLQ8o1Nqg8)。此表單包含我們完成設定所需的所有資訊，是啟用端點最快速的方式。

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

<Accordion title="電子郵件範本（若您無法使用表單）">
  若您偏好透過電子郵件聯絡，請將以下內容發送至 [support@returnhelper.com](mailto:support@returnhelper.com)：

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

  To: support@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>
  ```
</Accordion>

<h2 id="event-delivery">
  事件傳遞
</h2>

**時間** — 事件可能在觸發動作後幾秒鐘抵達，在極少數情況下可能延遲至幾分鐘後。

**重複事件** — 您的端點可能收到相同事件超過一次。請追蹤已處理的 `notificationId` 進行去重；`notificationId` 在每次推送中均為唯一且必定存在，因此可單獨作為穩定的等冪鍵使用。

**事件順序** — 不保證傳遞順序。請將您的處理器設計為可以任意順序處理事件。例如，`inventoryCreated` 可能在 `warehouseMarkShipmentArrivedV2` 之前抵達。請使用 API 取得您收到的亂序事件中所參考的任何物件。

每個事件均包含 ISO 8601 格式的 `eventTime` 欄位。

<h2 id="notification-headers">
  通知標頭
</h2>

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

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

<h3 id="legacy-headers">
  舊版標頭
</h3>

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

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

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

<h2 id="signature-verification">
  簽章驗證
</h2>

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

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

<h3 id="worked-example">
  操作範例
</h3>

以下為收到的請求範例：

**標頭：**

```json theme={null}
{
  "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"}
```

<h3 id="step-by-step-verification">
  逐步驗證說明
</h3>

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

```
gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=
```

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

```
2024-01-12T09:23:08.4863561Z
```

**步驟 3 — 建立 `string_to_sign`**

依序串接以下四個值（無分隔符）：

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

操作步驟：

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

預期結果：

```
gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=
```

**步驟 5 — 比對簽章**

將步驟 4 計算出的簽章與步驟 1 提取的簽章進行比對。請使用**常數時間字串比對**以防止時序攻擊。

**額外安全措施：** 拒絕 `eventTime` 與您系統時鐘相差超過 15 分鐘的事件（重放攻擊防護）。

<h3 id="sample-code">
  範例程式碼
</h3>

<CodeGroup>
  ```java Java theme={null}
  // 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);
    }
  }
  ```

  ```javascript Node.js theme={null}
  // 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);
  ```

  ```typescript TypeScript theme={null}
  // 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();
  ```

  ```apex Apex (Salesforce) theme={null}
  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);
      }
  }
  ```
</CodeGroup>

<h2 id="retry-mechanism">
  重試機制
</h2>

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

<h2 id="common-body-fields">
  通知主體公共欄位
</h2>

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

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

***

<h2 id="notification-event-reference">
  通知事件參考
</h2>

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

***

<h2 id="notification-payloads">
  通知 Payload
</h2>

<h3 id="label-result">
  標籤結果
</h3>

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

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

`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 的映射                    |

**成功範例：**

```json theme={null}
{
  "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"
}
```

**失敗範例：**

```json theme={null}
{
  "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"
}
```

***

<h3 id="warehouse-shipment-arrived-v2">
  倉庫退件運貨單(Return Shipment)抵達（v2）
</h3>

當倉庫標記退件運貨單(Return Shipment)已收到時發送。此後必定跟隨一個或多個[庫存已建立](#inventory-created)事件。

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

`category: rsl` / `action: markShipmentArrive` / `version: 202407`

`shipment` 中的關鍵欄位：

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

```json theme={null}
{
  "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"
}
```

***

<h3 id="inventory-created">
  庫存已建立
</h3>

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

<Note>
  **此負載中沒有 `sellerReferenceNumber`。** `returnInventory` 與 `shipment` 都不攜帶 `sellerReferenceNumber`；只有 `shipment.referenceNumber` 存在，而該欄位回傳的是您傳入的 `orderNumber`——並非賣家參考號。如果您依賴 `sellerReferenceNumber` 將庫存與您自己的紀錄對帳，**請不要只訂閱 `newInventoryCreated`**。請同時訂閱 [Warehouse Shipment Arrived](#warehouse-shipment-arrived-v2)（V202207 下在三個層級都攜帶 SRN）或 [Inventory Handling Complete](#inventory-handling-complete)（在 `returnInventory.sellerReferenceNumber` 上攜帶 Line Item 層級的 SRN）。完整的對帳策略見 [Seller Reference Number](/zh-Hant/reference/seller-reference-number)。
</Note>

`category: newInventoryCreated` / `action: newInventoryCreated`

`returnInventory` 中的關鍵欄位：

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

```json theme={null}
{
  "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"
}
```

***

<h3 id="image-updated">
  圖片已更新
</h3>

當退貨庫存(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`              | 自訂欄位                       |

```json theme={null}
{
  "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: []`。

***

<h3 id="unknown-shipment-assigned">
  未知來件(Unknown Shipment)已指派
</h3>

當沒有先前退貨申請(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`                                 | 最後修改時間戳記                    |

***

<h3 id="recall-status-update">
  回收狀態更新
</h3>

當回收追蹤號碼更新或取件狀態變更時發送。

`category: recall` / `action: recallUpdateStatus`

`recallUpdateTypeStatus` 值：

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

```json theme={null}
{
  "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"
}
```

***

<h3 id="resend-status-update">
  重寄狀態更新
</h3>

當重寄追蹤號碼更新，或重寄完成或失敗時發送。

`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`                 | 錯誤訊息（運貨單失敗時）   |

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

<Warning>
  `trackingNumber` **不是** 頂層欄位，它位於重寄運貨單內：`resendShipmentList[0].trackingNumber`。
</Warning>

檢查 `resend.resendStatusCode`：

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

```json theme={null}
{
  "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`。

<Note>
  只有當補寄是由 **Enterprise** 帳戶透過 [以 SKU 建立 Resend](/zh-Hant/api-reference/resend/create-resend-by-sku) 建立、且有提供參考編號時，`sellerReferenceNumber` 才會有值；其餘補寄一律為 `null`。若要以該值即時查詢補寄，請使用 [以 Seller Reference Number 搜尋 Resend](/zh-Hant/api-reference/resend/search-resend-by-seller-reference-number)。
</Note>

***

<h3 id="vas-update">
  VAS 更新
</h3>

當增值服務(VAS)完成時發送。

`category: rrliv` / `action: vasUpdated`

`updateVasList` 中的每個品項：

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

```json theme={null}
{
  "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` 為空陣列）。

***

<h3 id="inventory-handling-complete">
  庫存處理完成
</h3>

當倉庫完成處理指示（丟棄、重寄、回收等）時發送。

`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`  | 已完成 |

***

<h3 id="inventory-recalibrated">
  庫存重新校準
</h3>

當倉庫更新退貨庫存(Return Inventory)的測量尺寸或重量時發送。

`category: completeRecalibrate` / `action: completeRecalibrate`

`recalibrateSupplement` 中的關鍵欄位：

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

```json theme={null}
{
  "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"
}
```

***

<h3 id="inventory-meta-updated">
  庫存中繼資料已更新
</h3>

當倉庫或使用者新增或更新退貨庫存(Return Inventory)的中繼資料時發送。

`category: updateReturnInventoryMeta` / `action: updateReturnInventoryMeta`

Payload 包含與[庫存已建立](#inventory-created)相同結構的 `returnInventory`，其中包含更新後的 `returnInventoryMetaList`。

`metaType` 值：

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

***

<h3 id="rma-updated">
  RMA 已更新
</h3>

當倉庫更正不正確的 RMA 指派時發送。

`category: notifyUserRmaSwapped` / `action: notifyUserRmaSwapped`

`payload` 中的關鍵欄位：

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

```json theme={null}
{
  "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"
}
```

***

<h3 id="sku-updated">
  SKU 已更新
</h3>

當賣家更新退貨庫存(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` 物件遵循與[庫存處理完成](#inventory-handling-complete)相同的結構，包含更新後的 `sku` 欄位。

***

<h3 id="split-line-item">
  明細品項拆分
</h3>

當 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`                 | 物件 | 新的庫存記錄（與[庫存處理完成](#inventory-handling-complete)結構相同）                                                                                                                            |
| `returnRequestLineItemSupplement` | 物件 | 包含新明細品項尺寸及重量的補充資料                                                                                                                                                              |

***

<h3 id="warehouse-remarks-updated">
  倉庫備註已更新
</h3>

當倉庫更新退貨申請(Return Request)的備註時發送。

`category: warehouseUpdateWarehouseRemarks` / `action: warehouseUpdateWarehouseRemarks`

Payload 包含三個物件：

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

***

<h3 id="buyer-return-label-generated">
  買家退貨標籤已生成
</h3>

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

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

`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`                    | 自訂欄位      |

***

<h3 id="shopify-buyer-return-created">
  Shopify 買家退貨已建立
</h3>

當買家透過 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`                    | 自訂欄位          |

***

<h3 id="consolidate-shipping-cost-updated">
  合併退件運貨單(Return Shipment)費用已更新
</h3>

當合併退件運貨單(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`                                              | 配送指示        |

***

<h3 id="consolidate-shipping-all-packed">
  合併退件運貨單(Return Shipment)全部已打包
</h3>

當倉庫已將合併訂單的所有庫存打包入箱時發送。

`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` | 庫存狀態                         |

***

<h3 id="consolidate-shipment-sent">
  合併退件運貨單(Return Shipment)已寄出
</h3>

當倉庫將合併退件運貨單(Return Shipment)派送至承運商時發送。

`category: consolidateShippingShipmentSent` / `action: consolidateShippingShipmentSent`

`shipment` 中的關鍵欄位：

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

***

<h3 id="consolidate-shipping-awb-updated">
  合併退件運貨單(Return Shipment) AWB 已更新
</h3>

當合併退件運貨單(Return Shipment)的航空退件運貨單(Return Shipment)號碼更新時發送。

`category: consolidateShippingShipmentShipped` / `action: consolidateShippingShipmentShipped`

`shipment` 物件遵循與[合併退件運貨單(Return Shipment)已寄出](#consolidate-shipment-sent)相同的結構，包含更新後的 `awb` 欄位。

***

<h3 id="consolidate-order-completed">
  合併訂單已完成
</h3>

當合併訂單中所有退件運貨單(Return Shipment)均已寄出時發送。

`category: consolidateShippingOrderCompleted` / `action: consolidateShippingOrderCompleted`

`order` 物件遵循與[合併退件運貨單(Return Shipment)全部已打包](#consolidate-shipping-all-packed)相同的結構，包含完整的 `shipmentList`（含 `boxList` 及庫存詳情）。

***

<h3 id="consolidate-order-cancelled">
  合併訂單已取消
</h3>

當倉庫強制取消合併退件運貨單(Return Shipment)訂單時發送。

`category: consolidateShippingOrderCancelled` / `action: consolidateShippingOrderCancelled`

`order` 中的關鍵欄位：

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

***