Webhooks 与通知 - Return Helper API

此页面由 AI 自动翻译。如有任何疑问或不一致之处，请以英文版本为准。

概览

当 Return Helper 系统发生事件时（例如面单生成或退件运货单(Return Shipment)到达仓库），Webhook 会推送异步通知。您的服务器必须暴露一个 HTTPS 端点来接收这些 POST 请求。

字段可能随时新增。 Return Helper 会在不事先通知的情况下向 Webhook 负载新增字段。请勿对负载结构进行严格校验——请忽略无法识别的字段，并照常返回 2xx。

设置您的 Webhook 端点

端点要求

在注册端点之前，请确保您的端点满足以下要求：

可公开访问 — URL 必须可从互联网访问（不能是 VPN、localhost 或内网地址）
HTTPS — 端点必须通过 HTTPS 提供服务，并具有有效的 TLS 证书
HTTP POST — 端点必须接受携带 application/json 请求体的 POST 请求
响应 2xx — 收到请求后，您的服务器必须及时返回 2xx 状态码；任何其他状态码或超时均被视为推送失败
快速响应 — 如需进行耗时处理，请异步进行；不要在响应之前执行耗时操作，以免触发推送超时
接受您不处理的事件 — 对于您的处理程序不处理的任何 category / action，也请返回 2xx。新事件会陆续加入，并推送到每个已注册的端点。

注册您的端点

请通过 API 自行注册和管理您的 Webhook 端点：

用途	调用
注册端点	添加 Notification Endpoint
查看已注册的端点	列出 Notification Endpoints
移除端点	删除 Notification Endpoint

请先部署您的处理器，再进行注册。Return Helper 会向该 URL 发送一次已签名的验证请求，只有在 30 秒内返回 2xx 状态码时，端点才会被保存。每个已注册的端点都会收到您账户的所有事件。请在您这一端根据 category 和 action 字段进行筛选。沙箱环境与生产环境需分别注册。请在每个需要接收通知的环境中，使用该环境的凭证调用 API。

事件推送

时效 — 事件通常在触发动作后几秒内到达，极少数情况下可能延迟数分钟。 重复事件 — 您的端点可能多次收到同一事件。请追踪已处理的 notificationId 进行去重；notificationId 在每次推送中唯一且必定存在，因此可单独作为稳定的幂等键使用。 事件顺序 — 推送顺序不受保证。请将您的处理程序设计为可以按任意顺序处理事件。例如，inventoryCreated 可能先于 warehouseMarkShipmentArrivedV2 到达。如果收到乱序事件，请使用 API 获取事件中引用的对象。每个事件包含一个 ISO 8601 格式的 eventTime 字段。

通知请求头

每个 Webhook 请求都包含以下请求头：

请求头	类型	说明
`RETURNHELPER-TRIGGERED-AT`	string	ISO 8601 格式的 UTC 时间戳，例如 `2026-08-14T09:31:02.1234567Z`。该值即为签名验证所使用的时间戳。
`RETURNHELPER-API-ID`	string	该通知所属账户的 `apiId`。可通过获取 API 账户信息查询您的值。
`RETURNHELPER-API-NAME`	string	该账户的 `apiName`。
`ReturnHelper-Signature`	string	用于验证的 HMAC-SHA256 签名——请参阅签名验证。

旧版请求头

以下请求头仍会随每条通知发送，且不会被移除。新的集成请改为读取上方的请求头。

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

HTTP 请求头名称不区分大小写，部分框架会将其规范化。上表为 Return Helper 实际发送的大小写形式；若您的框架会把传入的请求头名称转为小写，请以不区分大小写的方式比对。

签名验证

在处理任何数据之前，请务必验证签名。请使用原始请求体 — 任何转换操作（例如框架重新序列化 JSON）都会导致验证失败。

您的签名密钥由 Return Helper 提供（Base64 编码）。请安全存储，切勿泄露。您可以在用户门户中与 API Key 和 Token 相同的界面找到它——请参阅认证一节中的截图；也可以使用获取 Signing Key以程序方式读取。

详细示例

给定以下传入请求： 请求头：

{
  "content-type": "application/json; charset=utf-8",
  "ReturnHelper-Signature": "gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=",
  "RETURNHELPER-TRIGGERED-AT": "2024-01-12T09:23:08.4863561Z",
  "RETURNHELPER-API-ID": "12345",
  "RETURNHELPER-API-NAME": "Acme Returns",
  "Timestamp": "2024-01-12T09:23:08.4863561Z"
}

请求体（原始 JSON，请勿重新序列化）：

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

逐步验证

步骤 1 — 从 ReturnHelper-Signature 请求头中提取签名（用于最终比对）：

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

步骤 2 — 从 RETURNHELPER-TRIGGERED-AT 请求头中提取时间戳：

2024-01-12T09:23:08.4863561Z

步骤 3 — 构建 string_to_sign 按顺序拼接以下四个值（无分隔符）：

HTTP 方法：POST
您的通知端点 URL：https://s2024-01-12.free.beeceptor.com
步骤 2 获取的 RETURNHELPER-TRIGGERED-AT 值
原始 JSON 请求体

拼接后的字符串：

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

然后对整个拼接字符串进行 Base64 编码，结果即为 string_to_sign：

UE9TVGh0dHBzOi8vczIwMjQtMDEtMTIuZnJlZS5iZWVjZXB0b3IuY29tMjAyNC0wMS0xMlQwOToyMzowOC40ODYzNTYxWnvigJxsYWJlbOKAnTp74oCccmVnaW9uc+KAnTp74oCcUkhDTuKAnTrigJxodHRwczovL2xhYmVsLnJldHVybmhlbHBlcmNoaW5hLmNvbS9sYWJlbC8yMDI0MDEvMTA1OTUtUzI0MDExMi0wMDAwMDAxLXBxazJwdnlkZ3hwLnBkZuKAnX0s4oCcbGFiZWxJZOKAnTozMTAzMyzigJxzaGlwbWVudElk4oCdOjMwMzg1LOKAnGFwaUlk4oCdOjMzLOKAnHJlZktleeKAnTrigJxTMjQwMTEyLTAwMDAwMDHigJ0s4oCcbGFiZWxSZXF1ZXN0SWTigJ06MTA1OTUs4oCcbGFiZWxSZXF1ZXN0U3RhdHVzQ29kZeKAnTrigJxzdWNjZXNz4oCdLOKAnHNlcnZpY2VUeXBl4oCdOuKAnFJFVFVSTl9FTkRJQ0lBX1VTUFNfR1JPVU5EX0FEVkFOVEFHRV9OSuKAnSzigJx0cmFja2luZ051bWJlcuKAnTrigJw5NDM0NjExODk5NTYyMDgyOTAxMTM3IizigJxsYWJlbFVybOKAnTrigJxodHRwczovL2xhYmVsLXNlcnZpY2UtZGV2LWZpbGVzLnJldHVybnNoZWxwZXIuY29tL2xhYmVsLzIwMjQwMS8xMDU5NS1TMjQwMTEyLTAwMDAwMDEtcHFrMnB2eWRneHAucGRm4oCdLOKAnGVycm9y4oCdOm51bGws4oCccXJjb2RlVXJs4oCdOm51bGws4oCccXJjb2RlRXJyb3LigJ06bnVsbCzigJxjb3JyZWxhdGlvbklk4oCdOm51bGws4oCcY2FuY2VsQ3V0b2ZmVGltZeKAnTrigJwyMDI0LTAyLTExVDA5OjIxOjI0LjA3OTUiLOKAnG1ldGHigJ06bnVsbH0s4oCcY2F0ZWdvcnnigJ064oCcbGFiZWxHZW5lcmF0ZWTigJ0s4oCcYWN0aW9u4oCdOuKAnGxhYmVsR2VuZXJhdGVk4oCdLOKAnGV2ZW50VGltZeKAnTrigJwyMDI0LTAxLTEyVDA5OjIzOjA4LjQ4NjI3NDNa4oCdfQ==

步骤 4 — 计算 HMAC-SHA256 签名 使用示例签名密钥（您的实际密钥会有所不同）：

PEnA0mzKb7fUlGfMgCGhXPjPmPGvW70UU8bkNKdG78WDrQRwzFa572e2JsFIE1e4PLaP9h/ZEvERSR0FBDYNlQ==

操作步骤：

将步骤 3 中的 string_to_sign 从 Base64 解码 → 字节数组
将您的签名密钥从 Base64 解码 → 字节数组
使用签名密钥字节对 string_to_sign 字节计算 HMAC-SHA256 → 签名字节数组
对签名字节数组进行 Base64 编码

期望结果：

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

步骤 5 — 比较签名 将步骤 4 计算的签名与步骤 1 提取的签名进行比较。请使用常量时间字符串比较以防止时序攻击。 额外安全措施： 如果 eventTime 与您系统时钟的偏差超过 15 分钟，请拒绝该事件（防止重放攻击）。

示例代码

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

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

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

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

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

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

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

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

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

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

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

main().catch(console.error);

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

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

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

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

  console.log(signature);
}

main();

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

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

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

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

重试机制

以 2xx HTTP 状态码响应以确认收到通知。非 2xx 响应将触发重试。连续失败 10 次后，向您端点的通知推送将暂停 24 小时。

通用请求体字段

所有通知请求体共享以下顶级字段：

字段	类型	说明
`category`	string	通知类别（见下表）
`action`	string	具体事件动作
`eventTime`	string	事件的 ISO 8601 时间戳
`version`	string	通知 Schema 版本
`notificationId`	string	每次推送均有；用作幂等键即可。

通知事件参考

通知	`category`	`action`	说明
面单结果	`labelGenerated`	`labelGenerated`	面单生成结果（成功或失败）
仓库退件运货单(Return Shipment)到达（v2）	`rsl`	`markShipmentArrive`	退件运货单(Return Shipment)到达仓库（当前版本）
库存已创建	`newInventoryCreated`	`newInventoryCreated`	新退货库存(Return Inventory)已创建
图片已更新	`rrli`	`changeLineItemImage`	行项图片添加、更改或删除
未知来件(Unknown Shipment)已分配	`rsl`	`assignUnknown`	未知来件(Unknown Shipment)已分配给卖家
回收状态更新	`recall`	`recallUpdateStatus`	回收追踪号或取件状态已变更
重寄状态更新	`resend`	`updateResendStatus`	重寄追踪号或状态已变更
增值服务(VAS)更新	`rrliv`	`vasUpdated`	增值服务(VAS)已完成或更新
库存处理完成	`rinv`	`completeInventoryHandling`	处理指令已完成
库存重新校准	`completeRecalibrate`	`completeRecalibrate`	仓库更新了库存尺寸/重量
库存元数据更新	`updateReturnInventoryMeta`	`updateReturnInventoryMeta`	仓库或用户添加/更新了元数据
RMA 已更新	`notifyUserRmaSwapped`	`notifyUserRmaSwapped`	仓库更正了 RMA 分配
SKU 已更新	`userUpdateReturnInventorySku`	`userUpdateReturnInventorySku`	卖家更新了库存 SKU
行项拆分	`lineItemVasReturnInventoryLineItem`	`splitLineItem`	增值服务(VAS)将包裹拆分为多个库存
仓库备注已更新	`warehouseUpdateWarehouseRemarks`	`warehouseUpdateWarehouseRemarks`	仓库更新了退货申请(Return Request)备注
买家退货面单已生成	`buyerReturnRrLabel`	`buyerReturnLabelGenerated`	品牌退货门户为买家生成了面单
Shopify 买家退货已创建	`shopifyBuyerCreateReturn`	`shopifyBuyerCreateReturn`	买家通过 Shopify 集成创建了退货
合并运费已更新	`consolidateShippingOrderShippingFeeUpdated`	`consolidateShippingOrderShippingFeeUpdated`	合并运输订单费用已更新
合并运输全部打包	`consolidateShippingOrderInventoryAllPacked`	`consolidateShippingOrderInventoryAllPacked`	合并订单的所有库存已打包
合并退件运货单(Return Shipment)已发出	`consolidateShippingShipmentSent`	`consolidateShippingShipmentSent`	合并退件运货单(Return Shipment)已发往承运商
合并运输 AWB 已更新	`consolidateShippingShipmentShipped`	`consolidateShippingShipmentShipped`	合并退件运货单(Return Shipment) AWB 已更新
合并运输已到达	`consolidateShippingShipmentArrived`	`consolidateShippingShipmentArrived`	寄往 RH 仓库的 Shipment 已到达并已收费
合并订单已完成	`consolidateShippingOrderCompleted`	`consolidateShippingOrderCompleted`	合并订单的所有明细已寄出
合并订单已取消	`consolidateShippingOrderCancelled`	`consolidateShippingOrderCancelled`	合并订单被仓库强制取消
交易已添加	`transaction`	`addTransaction`	您的账户记入了一笔扣费、退款或充值

通知数据结构

面单结果

当退货面单请求完成时（成功或失败）推送。

请始终使用 shipmentId 将面单与您系统中的退件运货单(Return Shipment)匹配——请勿使用 labelId。在极少数情况下，承运商故障会导致为同一 shipmentId 重新签发一张新面单（带有新的 labelId）。

category: labelGenerated / action: labelGenerated label 中的关键字段：

字段	说明
`labelId`	面单标识符（请勿用于匹配——见上方警告）
`shipmentId`	退件运货单(Return Shipment)标识符（请用此字段进行匹配）
`apiId`	卖家 API ID
`refKey`	退件运货单(Return Shipment)参考键
`labelRequestStatusCode`	`"success"` 或 `"fail"`
`serviceType`	使用的承运商服务类型
`trackingNumber`	承运商追踪号（成功时）
`labelUrl`	下载面单 PDF 的 URL（成功时）
`error`	错误信息（失败时）
`qrcodeUrl`	二维码 URL（如适用）
`qrcodeError`	二维码错误（如适用）
`shipmentInstruction`	退件运货单(Return Shipment)说明
`correlationId`	请求追踪的关联 ID
`cancelCutoffTime`	取消此面单的截止时间
`meta`	附加元数据
`regions`	同一面单文件的其他下载 URL，以区域代码为键。参见区域面单 URL。

区域面单 URL

regions 提供与 labelUrl 同一面单文件的其他 URL。在对应区域下载或打印面单时使用。

键	主机	使用场景
`RHCN`	`label.returnhelperchina.com`	在中国大陆下载或打印面单

每个值都指向与 labelUrl 相同的 PDF，仅主机不同。
所有账户均包含此字段，无需任何设置。
仅 labelGenerated 事件包含此字段。API 响应和其他 Webhook 事件中的面单 URL 仅使用 labelUrl 的主机。如需区域 URL，请从此事件中保存。
当 labelUrl 为 null（面单请求失败）时，regions 为 {}。
请忽略无法识别的键。如果所需的键不存在，请使用 labelUrl。

成功示例：

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

失败示例：

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

仓库退件运货单(Return Shipment)到达（v2）

当仓库标记退件运货单(Return Shipment)为已收货时推送。之后始终跟随一个或多个库存已创建事件。

此事件会回传您的 sellerReferenceNumber，是您的订单记录与 Return Helper 标识符之间的主要对账点。默认的 V202207 会在一份打包负载中携带三个层级的 SRN；V202407 只携带 Shipment 层级的 SRN。完整的对账工作流与版本差异见 Seller Reference Number。

category: rsl / action: markShipmentArrive / version: 202407 shipment 中的关键字段：

字段	说明
`shipmentId`	唯一退件运货单(Return Shipment)标识符
`returnRequestId`	关联的退货申请(Return Request)
`trackingNumber`	承运商追踪号
`sellerReferenceNumber`	您的参考编号
`serviceType`	使用的运输服务
`customFieldMap`	原始退件运货单(Return Shipment)中的自定义字段
`shipToWarehouseId`	收货仓库
`receiveDate`	ISO 8601 收货时间戳

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

库存已创建

在退件运货单(Return Shipment)收货（或增值服务(VAS)拆分发生）后推送，通知新的退货库存(Return Inventory)记录已创建。每条库存记录发送一次事件——如果同一面单下收到多个包裹，单次退件运货单(Return Shipment)可能产生多个事件。

此负载中没有 sellerReferenceNumber。 returnInventory 与 shipment 都不携带 sellerReferenceNumber；只有 shipment.referenceNumber 存在，而该字段回传的是您传入的 orderNumber——并非卖家参考号。如果您依赖 sellerReferenceNumber 将库存与您自己的记录对账，请不要只订阅 newInventoryCreated。请同时订阅 Warehouse Shipment Arrived（V202207 下在三个层级都携带 SRN）或 Inventory Handling Complete（在 returnInventory.sellerReferenceNumber 上携带 Line Item 层级的 SRN）。完整的对账策略见 Seller Reference Number。

category: newInventoryCreated / action: newInventoryCreated returnInventory 中的关键字段：

字段	说明
`returnInventoryId`	唯一库存标识符——用此字段分配处理指令
`warehouseId`	存放库存的仓库
`rma`	仓库分配的 RMA 值
`handlingCode`	当前处理指令
`handlingStatusCode`	当前处理状态
`imageList`	收货时拍摄的图片
`returnInventoryMetaList`	附加元数据（例如退件运货单(Return Shipment)中的自定义字段）

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

图片已更新

当退货库存(Return Inventory)行项的图片被添加、更改或删除时推送。 category: rrli / action: changeLineItemImage 顶级数据字段：

字段	类型	说明
`imageUrlList`	字符串数组	此行项当前的图片 URL 列表
`returnRequestLineItem`	对象	受影响的行项（见下方）

returnRequestLineItem 中的关键字段：

字段	说明
`returnRequestLineItemId`	行项标识符
`apiId`	卖家 API ID
`returnRequestId`	关联的退货申请(Return Request) ID
`sellerReferenceNumber`	卖家参考编号
`description`	商品描述
`quantity`	商品数量
`weight` / `weightUom`	重量及单位
`valueCurrencyCode` / `value`	价值及货币
`handlingCode`	处理指令
`isDeleted`	行项是否已删除
`rma`	RMA 值
`isFraudulent`	欺诈标志
`fraudReasonCode`	欺诈原因代码（如已标记）
`customFieldMap`	自定义字段

{
  "imageUrlList": [
    "https://file.returnhelpercentre.com/img/returns/202606/27_1000040536_lmpiohbx.5n3.jpg",
    "https://file.returnhelpercentre.com/images/returns/202603/16209788537041243876_USE-21-260303-P00156-19_..._4290.jpg"
  ],
  "returnRequestLineItem": {
    "returnRequestLineItemId": 10759,
    "apiId": 21,
    "returnRequestId": 9237,
    "returnRequestLineItemNumber": "RL210706-0000020",
    "sellerReferenceNumber": "RL210706-0000020",
    "description": "Item description",
    "quantity": 1,
    "weight": 100.0,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 463.0,
    "handlingCode": 0,
    "isDeleted": false
  },
  "category": "rrli",
  "action": "changeLineItemImage",
  "eventTime": "2021-07-06T13:02:24.5575164Z"
}

imageUrlList 中的 URL 公网可访问、不会过期，可在客户端安全缓存。请直接保存使用。空状态：imageUrlList: []。

未知来件(Unknown Shipment)已分配

当一个没有预先退货申请(Return Request)记录的退件运货单(Return Shipment)被识别并分配给卖家时推送。 category: rsl / action: assignUnknown / version: 202407 returnInventory 中的关键字段：

字段	说明
`returnInventoryId`	唯一库存标识符
`warehouseId`	存放库存的仓库
`apiId`	卖家 API ID
`description`	商品描述
`quantity`	商品数量
`dimension1` / `dimension2` / `dimension3`	实测尺寸
`dimensionUom`	尺寸计量单位
`weight`	实测重量
`weightUom`	重量计量单位
`valueCurrencyCode`	价值货币代码
`value`	申报价值
`handlingCode`	当前处理指令
`handlingStatusCode`	当前处理状态
`completeOn`	处理完成时间戳
`warehouseRemarks`	仓库备注
`handlingUpdatedOn`	最后处理更新时间戳
`sku`	卖家分配的 SKU
`rma`	仓库分配的 RMA
`imageList`	收货时拍摄的图片

unknownShipment 中的关键字段：

字段	说明
`unknownShipmentId`	唯一未知来件(Unknown Shipment)标识符
`unknownShipmentNumber`	未知来件(Unknown Shipment)参考编号
`description`	描述
`unknownShipmentStatusCode`	当前状态
`unknownShipmentCountryCode`	国家代码
`warehouseId`	收货仓库
`unknownShipmentServiceType`	运输服务类型
`trackingNumber`	承运商追踪号
`totalWeight` / `totalWeightUom`	总重量及单位
`dimension1` / `dimension2` / `dimension3`	实测尺寸
`dimensionUom`	尺寸计量单位
`totalValue` / `totalValueCurrency`	申报价值及货币

回收状态更新

Recall 即将停用。要把库存寄至 Return Helper 香港仓库，请创建 destinationType: RH_WAREHOUSE 的 Consolidate Shipping Order。

当回收追踪号更新或取件状态变更时推送。 category: recall / action: recallUpdateStatus recallUpdateTypeStatus 值：

值	回收库存状态	说明
`updateTrackingNumber`	`in-transit`	已分配追踪号
`readyToPickUp`	`ready-to-pick-up`	商品已准备好取件
`pickupBySelf`	`picked-up`	客户自取
`pickupByCourier`	`picked-up`	本地快递取件
`pickupByOthers`	`picked-up`	其他方取件

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

重寄状态更新

当重寄追踪号更新或重寄完成/失败时推送。 category: resend / action: updateResendStatus 顶级数据字段：

字段	类型	说明
`resend`	对象	重寄订单详情（见下方）
`returnInventoryList`	数组	本次重寄的库存项
`resendShipmentList`	数组	此重寄对应的重寄运货单（见下方）

resend 中的关键字段：

字段	说明
`resendId`	唯一重寄订单标识符
`apiId`	卖家 API ID
`resendNumber`	重寄订单编号
`resendStatusCode`	当前状态：`0` — 待处理，`1` — 已取消，`2` — 进行中，`3` — 已完成，`4` — 失败，`5` — 已排队，`6` — 面单已生成
`description`	订单描述
`remarks`	卖家备注
`warehouseRemarks`	仓库备注

每笔 resendShipmentList 条目中的关键字段：

字段	说明
`resendShipmentId`	重寄运货单标识符
`resendId`	此运货单所属的重寄订单
`resendShipmentNumber`	重寄运货单编号
`trackingNumber`	承运商追踪号（可用时）
`sellerReferenceNumber`	您自己为此补寄设置的参考编号
`error`	错误信息（运货单失败时）

resendShipmentList 总是只有一条条目——一笔重寄有且仅有一张重寄运货单。请直接读取 resendShipmentList[0]。

trackingNumber 不是顶级字段，它位于重寄运货单内：resendShipmentList[0].trackingNumber。

检查 resend.resendStatusCode：

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

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

使用 resendShipmentList[0].sellerReferenceNumber 将事件对应到您自己的订单记录，就不必存储 Return Helper 的 resendId。

只有当补寄是由 Enterprise 账户通过按 SKU 创建 Resend 创建、且有提供参考编号时，sellerReferenceNumber 才会有值；其余补寄一律为 null。若要以该值即时查询补寄，请使用按 Seller Reference Number 搜索 Resend。

增值服务(VAS)更新

当增值服务(VAS)完成时推送。 category: rrliv / action: vasUpdated updateVasList 中每项：

字段	说明
`returnRequestLineItemVasId`	增值服务(VAS)记录标识符
`vasResult`	增值服务(VAS)结果描述
`weight` / `weightUom`	增值服务(VAS)后的重量及单位
`dimension1` / `dimension2` / `dimension3`	增值服务(VAS)后的尺寸
`dimensionUom`	尺寸计量单位
`vasStatusCode`	增值服务(VAS)状态码
`imageUrlList`	增值服务(VAS)结果图片

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

imageUrlList 中的 URL 公网可访问、不会过期，可在客户端安全缓存。请直接保存使用。空状态：imageUrlList: []（某些 VAS 类型不产生图片；这些条目仍出现在 updateVasList[] 中，但 imageUrlList 为空数组）。

库存处理完成

当仓库完成处理指令（销毁、重寄、回收等）时推送。 category: rinv / action: completeInventoryHandling returnInventory 中的关键字段：

字段	说明
`returnInventoryId`	唯一库存标识符
`warehouseId`	存放库存的仓库
`returnRequestLineItemId`	关联的行项 ID
`apiId`	卖家 API ID
`returnRequestId`	关联的退货申请(Return Request) ID
`sellerReferenceNumber`	卖家参考编号
`description`	商品描述
`quantity`	商品数量
`dimension1` / `dimension2` / `dimension3`	实测尺寸
`dimensionUom`	尺寸计量单位
`weight`	实测重量
`weightUom`	重量计量单位
`valueCurrencyCode`	价值货币代码
`value`	申报价值
`handlingCode`	处理指令（见下表）
`handlingStatusCode`	处理状态（见下表）
`completeBy`	完成处理的用户
`completeOn`	完成时间戳
`warehouseRemarks`	仓库备注
`handlingUpdatedOn`	最后处理更新时间戳
`stopAgingOn`	停止老化时间戳
`sku`	卖家分配的 SKU
`rma`	仓库分配的 RMA
`returnInventoryMetaList`	附加元数据列表

handlingCode 值：

ID	代码	说明
0	`tbc`	待确认
1	`rtn`	回收
2	`dis`	销毁
3	`rsd`	重寄
4	`ohd`	暂扣
5	`oth`	其他

handlingStatusCode 值：

ID	代码	说明
0	`pending`	待处理
1	`inProgress`	进行中
2	`completed`	已完成

库存重新校准

当仓库更新退货库存(Return Inventory)的实测尺寸或重量时推送。 category: completeRecalibrate / action: completeRecalibrate recalibrateSupplement 中的关键字段：

字段	说明
`warehouseId`	执行重新校准的仓库
`returnInventoryId`	受影响的库存 ID
`returnRequestLineItemId`	关联的行项 ID
`rma`	RMA 值
`dimension1` / `dimension2` / `dimension3`	更新后的尺寸
`weight`	更新后的重量
`recalibratedOn`	重新校准时间戳
`returnInventoryMetaList`	更新后的元数据列表（每项含 `metaType` 和 `metaMap`）

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

库存元数据更新

当仓库或用户在退货库存(Return Inventory)上添加或更新元数据时推送。 category: updateReturnInventoryMeta / action: updateReturnInventoryMeta 数据包含 returnInventory，结构与库存已创建相同，包含更新后的 returnInventoryMetaList。 metaType 值：

usr — 用户提供的元数据
whs — 仓库提供的元数据

RMA 已更新

当仓库更正错误的 RMA 分配时推送。 category: notifyUserRmaSwapped / action: notifyUserRmaSwapped payload 中的关键字段：

字段	说明
`userApiId`	卖家 API ID
`clientCode`	客户代码
`returnInventoryId`	受影响的库存 ID
`oldRma`	旧的 RMA 值
`newRma`	更正后的新 RMA 值

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

SKU 已更新

当卖家更新退货库存(Return Inventory)的 SKU 时推送。 category: userUpdateReturnInventorySku / action: userUpdateReturnInventorySku 数据包含 returnRequest 和 returnInventory。 returnRequest 中的关键字段：

字段	说明
`returnRequestId`	唯一退货申请(Return Request)标识符
`apiId`	卖家 API ID
`sellerReferenceNumber`	卖家参考编号
`returnStatusCode`	退货申请(Return Request)状态
`returnTitle`	退货标题
`totalValue` / `totalValueCurrency`	总申报价值及货币
`remarks`	备注
`rma`	RMA 值
`isArchived`	申请是否已归档
`returnRequestSourceType`	退货申请(Return Request)来源类型

returnInventory 对象结构与库存处理完成相同，其中 sku 字段已更新。

行项拆分

当增值服务(VAS)操作将包裹拆分为多个库存时推送。包含每个生成包裹的新行项和库存记录。 category: lineItemVasReturnInventoryLineItem / action: splitLineItem 顶级数据字段：

字段	类型	说明
`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`	对象	新库存记录（结构与库存处理完成相同）
`returnRequestLineItemSupplement`	对象	新行项的尺寸和重量补充信息

仓库备注已更新

当仓库更新退货申请(Return Request)备注时推送。 category: warehouseUpdateWarehouseRemarks / action: warehouseUpdateWarehouseRemarks 数据包含三个对象：

returnRequest — 退货申请(Return Request)（结构与 SKU 已更新 → returnRequest 相同）
shipment — 退件运货单(Return Shipment)记录，包含完整地址详情、尺寸、重量、费用和 customFieldMap
returnInventory — 受影响的库存（结构与库存处理完成相同），其中 warehouseRemarks 字段已更新

买家退货面单已生成

当买家在品牌退货门户创建退货且面单生成时推送。

仅适用于与 Return Helper 品牌退货服务集成的客户。

category: buyerReturnRrLabel / action: buyerReturnLabelGenerated 检查 buyerReturn.labelRequestStatusCode 的值为 "success" 或 "fail"。 buyerReturn 中的关键字段：

字段	说明
`buyerReturnId`	唯一买家退货标识符
`apiId`	卖家 API ID
`sellerReferenceNumber`	卖家参考编号
`returnRequestId`	关联的退货申请(Return Request) ID（如已创建）
`shipmentId`	关联的退件运货单(Return Shipment) ID（如已创建）
`returnRequestNumber`	退货申请(Return Request)编号
`shipmentNumber`	退件运货单(Return Shipment)编号
`totalValue` / `totalValueCurrency`	申报价值及货币
`remarks`	备注
`labelId`	面单 ID
`labelRequestStatusCode`	`"success"` 或 `"fail"`
`trackingNumber`	追踪号（成功时）
`labelFile`	包含 `labelUrl` 和 `labelKey` 的对象
`shipmentInstruction`	退件运货单(Return Shipment)说明
`error`	错误信息（失败时）
`warehouseId`	目的仓库
`shipmentServiceType`	运输服务类型
`shipmentCountryCode`	退件运货单(Return Shipment)国家
`shipmentName` / `shipmentPhone` / `shipmentEmail`	联系方式
`shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`	地址行
`shipmentCity` / `shipmentState` / `shipmentPostalCode`	地址详情
`costCurrencyCode` / `cost`	运费
`sellerCostCurrencyCode` / `sellerCost`	卖家费用
`buyerCostCurrencyCode` / `buyerCost`	买家费用
`boxType`	箱型
`weight` / `weightUom`	重量及单位
`dimension1` / `dimension2` / `dimension3` / `dimensionUom`	包裹尺寸
`customFieldMap`	自定义字段
`buyerReturnLineItemList`	行项列表（见下方）

buyerReturnLineItemList 中每项：

字段	说明
`buyerReturnLineItemId`	行项 ID
`sellerReferenceNumber`	卖家参考编号
`description`	商品描述
`quantity`	数量
`weight` / `weightUom`	重量及单位
`value` / `valueCurrencyCode`	价值及货币
`returnReasonCode` / `returnReason`	买家选择的退货原因
`customFieldMap`	自定义字段

Shopify 买家退货已创建

当买家通过 Shopify 集成创建退货申请(Return Request)时推送。 category: shopifyBuyerCreateReturn / action: shopifyBuyerCreateReturn shopifyReturn 中的关键字段：

字段	说明
`shopifyReturnId`	唯一 Shopify 退货标识符
`apiId`	卖家 API ID
`referenceNumber`	参考编号
`returnRequestId`	关联的退货申请(Return Request) ID（如已创建）
`shipmentId`	关联的退件运货单(Return Shipment) ID（如已创建）
`returnRequestNumber` / `shipmentNumber`	退货及退件运货单(Return Shipment)编号
`totalValue` / `totalValueCurrency`	申报价值及货币
`remarks`	备注
`labelRequestStatusCode`	面单状态：`"success"` 或 `"fail"`
`trackingNumber`	追踪号（成功时）
`labelUrl`	面单 URL（成功时）
`error`	错误信息（失败时）
`warehouseId`	目的仓库
`shipmentServiceType` / `shipmentCountryCode`	运输服务及国家
`shipmentName` / `shipmentPhone` / `shipmentEmail`	联系方式
`shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`	地址行
`shipmentCity` / `shipmentState` / `shipmentPostalCode`	地址详情
`costCurrencyCode` / `cost`	运费
`boxType`	箱型
`weight` / `weightUom`	重量及单位
`dimension1` / `dimension2` / `dimension3` / `dimensionUom`	包裹尺寸
`shopifyShopId`	Shopify 店铺标识符
`shopifyOrderId` / `shopifyOrderNumber` / `shopifyOrderName`	Shopify 订单详情
`shopifyReturnStatusCode`	Shopify 退货状态
`requestParty`	发起退货的一方
`customFieldMap`	自定义字段

shopifyReturnLineItemList 中每项：

字段	说明
`shopifyReturnLineItemId`	行项 ID
`sellerReferenceNumber`	卖家参考编号
`description`	商品描述
`quantity`	数量
`sku`	产品 SKU
`weight` / `weightUom`	重量及单位
`value` / `valueCurrencyCode`	价值及货币
`returnReasonCode` / `returnReason`	买家选择的退货原因
`shopifyProductId`	Shopify 产品 ID
`buyerNotes`	买家备注
`customFieldMap`	自定义字段

合并运费已更新

当合并运输订单的运费更新时推送。 category: consolidateShippingOrderShippingFeeUpdated / action: consolidateShippingOrderShippingFeeUpdated order 中的关键字段：

字段	说明
`consolidateShippingOrderId`	订单标识符
`consolidateShippingOrderNumber`	订单编号
`consolidateShippingOrderStatus`	当前状态
`outboundWarehouseId`	出库仓库
`shippingMethod`	始终为 `null`
`shippingFee` / `currencyCode`	更新后的运费及货币
`shipToContactName` / `shipToPhone` / `shipToEmail`	收货联系人
`shipToCompanyName`	收货公司
`shipToStreet1` / `shipToStreet2` / `shipToStreet3`	收货地址行
`shipToCity` / `shipToState` / `shipToPostalCode` / `shipToCountry`	收货地址
`deliveryInstructions`	配送说明

合并运输全部打包

当仓库已将合并订单的所有库存打包入箱时推送。 category: consolidateShippingOrderInventoryAllPacked / action: consolidateShippingOrderInventoryAllPacked order 中的关键字段：

字段	说明
`consolidateShippingOrderId`	订单标识符
`consolidateShippingOrderNumber`	订单编号
`consolidateShippingOrderStatus`	当前状态
`outboundWarehouseId`	出库仓库
`shippingFee` / `currencyCode`	运费及货币
`shippingMethod`	始终为 `null`
`customFieldMap`	自定义字段
`deliveryInstructions`	配送说明
`shipmentList`	退件运货单(Return Shipment)列表（见下方）

shipmentList 中每项：

字段	说明
`consolidateShippingShipmentId`	退件运货单(Return Shipment)标识符
`consolidateShippingShipmentNumber`	退件运货单(Return Shipment)编号
`consolidateShippingShipmentStatus`	退件运货单(Return Shipment)状态
`boxList`	此退件运货单(Return Shipment)中的箱子列表

boxList 中每项：

字段	说明
`consolidateShippingShipmentBoxId`	箱子标识符
`boxNumber`	箱号
`consolidateShippingShipmentBoxStatus`	箱子状态
`consolidateShippingInventoryList`	此箱中的库存

consolidateShippingInventoryList 中每项：

字段	说明
`consolidateShippingInventoryId`	明细标识符
`itemType`	`RMA` 或 `FNSKU`
`returnInventoryId` / `rma`	仅 `RMA` 明细，否则为 `null`
`fnsku`	仅 `FNSKU` 明细，否则为 `null`
`quantity`	此明细在该箱中的件数。`RMA` 明细始终为 `1`
`consolidateShippingInventoryStatus`	明细状态

一个箱子可装 RMA 明细、FNSKU 明细或两者。不含 RMA 明细的箱子同样会列出。

合并退件运货单(Return Shipment)已发出

当仓库将合并退件运货单(Return Shipment)发往承运商时推送。 category: consolidateShippingShipmentSent / action: consolidateShippingShipmentSent shipment 中的关键字段：

字段	说明
`consolidateShippingShipmentId`	退件运货单(Return Shipment)标识符
`consolidateShippingShipmentNumber`	退件运货单(Return Shipment)编号
`consolidateShippingShipmentStatus`	当前状态
`awb`	航空退件运货单(Return Shipment)号
`serviceProvider`	承运商服务提供商
`shipDate`	发货日期
`boxList`	箱子列表（结构与全部打包 → boxList相同）
`consolidateShippingOrderId`	父订单标识符
`consolidateShippingOrderNumber`	父订单编号
`consolidateShippingOrderStatus`	父订单状态
`outboundWarehouseId`	出库仓库
`customFieldMap`	自定义字段

合并运输 AWB 已更新

当合并退件运货单(Return Shipment)的航空退件运货单(Return Shipment)号更新时推送。 category: consolidateShippingShipmentShipped / action: consolidateShippingShipmentShipped shipment 对象结构与合并退件运货单(Return Shipment)已发出相同，其中 awb 字段已更新。对于 RH_WAREHOUSE 订单，仓库记录 AWB 时会发送此事件。consolidateShippingShipmentStatus 为 IN_TRANSIT，此时尚未收费：Shipment 到达时才收费，并通过合并运输已到达通知。

合并运输已到达

RH_WAREHOUSE 订单的每个 Shipment 到达 Return Helper 仓库并收取运费时，各发送一次。 category: consolidateShippingShipmentArrived / action: consolidateShippingShipmentArrived / version: 202609

版本 202609 需要申请开通。请联系 Return Helper 客服。

字段	说明
`order`	订单。`order.shipmentList` 只包含已到达的这个 Shipment。
`arrivedShipmentCount`	此订单中含明细且已到达的 Shipment 数（包括本次）
`totalShipmentCount`	此订单中含明细的 Shipment 数。空的 Shipment 不计入。

含明细的 Shipment 有 3 个的订单会发送 3 次事件：1/3、2/3、3/3。 order 中的字段：

字段	说明
`consolidateShippingOrderId` / `consolidateShippingOrderNumber`	订单标识符
`apiId`	您的账户 ID
`consolidateShippingOrderStatus`	订单状态
`outboundWarehouseId`	出货仓库
`destinationType`	`RH_WAREHOUSE`
`destinationWarehouseId`	目的地仓库
`shippingFee` / `currencyCode`	截至目前的订单运费
`customFieldMap` / `deliveryInstructions`	订单上设置的值
`shipmentList`	已到达的 Shipment（见下方）

版本 202609 不包含 shippingMethod。 shipmentList 中的每一项：

字段	说明
`consolidateShippingShipmentId` / `consolidateShippingShipmentNumber`	Shipment 标识符
`consolidateShippingShipmentStatus`	`READY_TO_PICKUP`
`awb`	Air Waybill 号码
`chargeableWeight`	计费重量（克）
`boxList`	此 Shipment 的箱子，每个箱子含 `consolidateShippingShipmentBoxId`、`boxNumber`、`consolidateShippingShipmentBoxStatus` 和 `consolidateShippingInventoryList`

consolidateShippingInventoryList 中的每一项：

字段	说明
`consolidateShippingInventoryId`	明细标识符
`itemType`	`RMA` 或 `FNSKU`
`returnInventoryId` / `rma`	仅 `RMA` 明细，否则为 `null`
`fnsku`	仅 `FNSKU` 明细，否则为 `null`
`quantity`	该箱中的件数
`consolidateShippingInventoryStatus`	明细状态

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

合并订单已完成

合并订单的所有明细都已寄出时发送。对于 RH_WAREHOUSE 订单，所有含明细的 Shipment 也必须已到达；此事件在订单最后一个合并运输已到达之后发送。 category: consolidateShippingOrderCompleted / action: consolidateShippingOrderCompleted order 对象结构与合并运输全部打包相同，包含完整的 shipmentList（含 boxList 和库存详情）。

合并订单已取消

当仓库强制取消合并运输订单时推送。 category: consolidateShippingOrderCancelled / action: consolidateShippingOrderCancelled order 中的关键字段：

字段	说明
`consolidateShippingOrderId`	订单标识符
`consolidateShippingOrderNumber`	订单编号
`consolidateShippingOrderStatus`	`CANCELED`
`outboundWarehouseId`	出库仓库
`shippingMethod`	始终为 `null`
`shippingFee`	运费
`deliveryInstructions`	配送说明
`customFieldMap`	自定义字段

交易已添加

每当有交易记入您的账户时推送一次，包括扣费、退款、重新扣费和充值。

apiTransaction.notes 通常会说明该交易对应的操作，因此您无需解析 headId 即可了解交易内容。

category: transaction / action: addTransaction / version: 202610 apiTransaction 中的关键字段：

字段	类型	说明
`apiTransactionId`	long	交易标识符
`transactionNumber`	string	交易编号，例如 `T2600012345`。每笔交易唯一。
`apiId`	long	您的 API 账户 ID
`currencyCode`	string	货币代码，小写（例如 `usd`）
`transactionType`	string	交易类型代码。名称见获取所有交易类型
`headId`	string	该交易所记账的记录 ID。取决于 `transactionType`；见 headId 对应的记录。
`amount`	number	带正负号的金额。负数为扣费；正数为退款或充值。
`notes`	string	供人阅读的说明。措辞可能变更，请勿解析。
`createOn`	string	交易记入的时间（UTC，ISO 8601）
`createBy`	string

apiBalance 中的关键字段：

字段	类型	说明
`apiBalanceId`	long	余额记录标识符
`apiId`	long	您的 API 账户 ID
`currencyCode`	string	货币代码，小写
`balance`	number	该交易记入后，您在 `currencyCode` 币种下的余额

balance 是该交易记入时的值，而非您当前的余额。事件可能不按顺序送达。如需当前余额，请调用获取 API 账户余额。

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

headId 对应的记录

在下表中找到 transactionType，再将 headId 与您已从所列事件或响应中获得的 ID 进行匹配。headId 始终为字符串。退款或重新扣费的 headId 与其所调整的扣费相同。

`headId` 为	`transactionType`	获取此 ID 的位置
您的 `apiId`	`chr`, `top`, `acs`, `acf`, `rtp`	`RETURNHELPER-API-ID` 请求头，或获取 API 账户信息
`labelId`	`csl`, `rcl`, `RECHARGE_SHIPPING_LABEL`, `rsl`¹	面单结果中的 `label.labelId`
`returnRequestId`	`bps`, `brt`, `sps`, `REFUND_CANCEL_BUYER_RETURN_LABEL`, `REFUND_CANCEL_SHOPIFY_RETURN_LABEL`, `rsl`¹	买家退货面单已生成、Shopify 买家退货已创建
`returnInventoryId`	`bbc`, `brc`, `fbr`, `cup`, `dis`, `soh`, `swh`, `CANCELED_LABEL_ARRIVED`, `CANCELED_LABEL_PENALTY`, `CONSOLIDATE_SHIPPING_OUTBOUND`	库存已创建、仓库退件运货单(Return Shipment)到达（v2）
`returnInventoryId`	`REFUND_` / `RECHARGE_` + `CLAIM_UNKNOWN`, `BUYER_RETURN`, `BOUNCE_BACK`, `FBA_RESTOCK`, `CANCELED_LABEL_ARRIVED`, `CANCELED_LABEL_PENALTY`	同上
`returnRequestLineItemVasId`	`rpk`, `tpc`, `pin`	增值服务(VAS)更新
`resendId`	`rmh`, `rlr`	创建 Resend Order 响应、重寄状态更新
重寄库存记录 ID	`rsh`	不会在任何 API 响应或 webhook 中返回
`fbaInstructionId`	`fbd`, `frh`	创建 FBA Instructions 响应
`fbaShipmentId`	`fih`, `fch`	创建 FBA Shipment 响应
`consolidateShippingShipmentBoxId`	`CONSOLIDATE_SHIPPING_MERGE`	合并运输全部打包中的 `boxList`
`consolidateShippingInventoryId`	`CONSOLIDATE_SHIPPING_OUTBOUND_FNSKU`	合并运输全部打包中的 `consolidateShippingInventoryList`
`consolidateShippingShipmentId`	`CONSOLIDATE_SHIPPING_SHIPMENT`	合并退件运货单(Return Shipment)已发出

¹ rsl 为生成失败的面单退款。headId 为 labelId；若失败的面单是买家退货面单，则为 returnRequestId。

所有交易都会推送；您无法只订阅个别类型。请根据 transactionType 和 amount 的正负进行分支处理。
可能会新增 transactionType 值。遇到无法识别的类型时，仍请记录 amount 和 balance；不要拒收该事件。
一个退件运货单(Return Shipment)可能有多张面单，因此可能有多笔 csl。请使用面单结果将 labelId 对应到 shipmentId。
createOn 是交易记入的时间；eventTime 是通知发送的时间。

​概览

​设置您的 Webhook 端点

​端点要求

​注册您的端点

​事件推送

​通知请求头

​旧版请求头

​签名验证

​详细示例

​逐步验证

​示例代码

​重试机制

​通用请求体字段

​通知事件参考

​通知数据结构

​面单结果

​区域面单 URL

​仓库退件运货单(Return Shipment)到达（v2）

​库存已创建

​图片已更新

​未知来件(Unknown Shipment)已分配

​回收状态更新

​重寄状态更新

​增值服务(VAS)更新

​库存处理完成

​库存重新校准

​库存元数据更新

​RMA 已更新

​SKU 已更新

​行项拆分

​仓库备注已更新

​买家退货面单已生成

​Shopify 买家退货已创建

​合并运费已更新

​合并运输全部打包

​合并退件运货单(Return Shipment)已发出

​合并运输 AWB 已更新

​合并运输已到达

​合并订单已完成

​合并订单已取消

​交易已添加

​headId 对应的记录

概览

设置您的 Webhook 端点

端点要求

注册您的端点

事件推送

通知请求头

旧版请求头

签名验证

详细示例

逐步验证

示例代码

重试机制

通用请求体字段

通知事件参考

通知数据结构

面单结果

区域面单 URL

仓库退件运货单(Return Shipment)到达（v2）

库存已创建

图片已更新

未知来件(Unknown Shipment)已分配

回收状态更新

重寄状态更新

增值服务(VAS)更新

库存处理完成

库存重新校准

库存元数据更新

RMA 已更新

SKU 已更新

行项拆分

仓库备注已更新

买家退货面单已生成

Shopify 买家退货已创建

合并运费已更新

合并运输全部打包

合并退件运货单(Return Shipment)已发出

合并运输 AWB 已更新

合并运输已到达

合并订单已完成

合并订单已取消

交易已添加

headId 对应的记录