> ## 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)到达仓库），Webhook 会推送异步通知。您的服务器必须暴露一个 HTTPS 端点来接收这些 POST 请求。

<h2 id="setting-up-your-webhook-endpoint">
  设置您的 Webhook 端点
</h2>

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

在提交设置请求之前，请确保您的端点满足以下要求：

* **可公开访问** — URL 必须可从互联网访问（不能是 VPN、localhost 或内网地址）
* **HTTPS** — 端点必须通过 HTTPS 提供服务，并具有有效的 TLS 证书
* **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-Hans/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>
  在处理任何数据之前，请务必验证签名。请使用**原始请求体** — 任何转换操作（例如框架重新序列化 JSON）都会导致验证失败。
</Warning>

您的签名密钥由 Return Helper 提供（Base64 编码）。请安全存储，切勿泄露。您可以在用户门户中与 API Key 和 Token 相同的界面找到它——请参阅 [认证](/zh-Hans/introduction#authentication) 一节中的截图；也可以使用[获取 Signing Key](/zh-Hans/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. 将步骤 3 中的 `string_to_sign` 从 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 | 通知 Schema 版本     |
| `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 集成创建了退货             |
| [合并运费已更新](#consolidate-shipping-cost-updated)                    | `consolidateShippingOrderShippingFeeUpdated` | `consolidateShippingOrderShippingFeeUpdated` | 合并运输订单费用已更新                      |
| [合并运输全部打包](#consolidate-shipping-all-packed)                     | `consolidateShippingOrderInventoryAllPacked` | `consolidateShippingOrderInventoryAllPacked` | 合并订单的所有库存已打包                     |
| [合并退件运货单(Return Shipment)已发出](#consolidate-shipment-sent)        | `consolidateShippingShipmentSent`            | `consolidateShippingShipmentSent`            | 合并退件运货单(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">
  通知数据结构
</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`              | 二维码 URL（如适用）                         |
| `qrcodeError`            | 二维码错误（如适用）                           |
| `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-Hans/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-Hans/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`

顶级数据字段：

| 字段                      | 类型    | 说明              |
| ----------------------- | ----- | --------------- |
| `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`

顶级数据字段：

| 字段                    | 类型 | 说明               |
| --------------------- | -- | ---------------- |
| `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-Hans/api-reference/resend/create-resend-by-sku) 创建、且有提供参考编号时，`sellerReferenceNumber` 才会有值；其余补寄一律为 `null`。若要以该值即时查询补寄，请使用 [按 Seller Reference Number 搜索 Resend](/zh-Hans/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`

数据包含 `returnInventory`，结构与[库存已创建](#inventory-created)相同，包含更新后的 `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`

数据包含 `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`

顶级数据字段：

| 字段                                    | 类型      | 说明                         |
| ------------------------------------- | ------- | -------------------------- |
| `returnRequestId`                     | integer | 关联的退货申请(Return Request) ID |
| `returnRequestLineItemId`             | long    | 原始行项 ID                    |
| `returnRequestLineItemVasId`          | long    | 触发拆分的增值服务(VAS)记录 ID        |
| `vasStatusCode`                       | string  | 增值服务(VAS)状态码               |
| `splitLineItemAndReturnInventoryList` | array   | 拆分结果列表（见下方）                |

`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`

数据包含三个对象：

* `returnRequest` — 退货申请(Return Request)（结构与 [SKU 已更新 → returnRequest](#sku-updated) 相同）
* `shipment` — 退件运货单(Return Shipment)记录，包含完整地址详情、尺寸、重量、费用和 `customFieldMap`
* `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">
  合并运费已更新
</h3>

当合并运输订单的运费更新时推送。

`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">
  合并运输全部打包
</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">
  合并运输 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` 对象结构与[合并运输全部打包](#consolidate-shipping-all-packed)相同，包含完整的 `shipmentList`（含 `boxList` 和库存详情）。

***

<h3 id="consolidate-order-cancelled">
  合并订单已取消
</h3>

当仓库强制取消合并运输订单时推送。

`category: consolidateShippingOrderCancelled` / `action: consolidateShippingOrderCancelled`

`order` 中的关键字段：

| 字段                               | 说明        |
| -------------------------------- | --------- |
| `consolidateShippingOrderId`     | 订单标识符     |
| `consolidateShippingOrderNumber` | 订单编号      |
| `consolidateShippingOrderStatus` | 当前状态（已取消） |
| `outboundWarehouseId`            | 出库仓库      |
| `shippingMethod`                 | 运输方式      |
| `shippingFee`                    | 运费        |
| `deliveryInstructions`           | 配送说明      |
| `customFieldMap`                 | 自定义字段     |

***