Webhooks 与通知 - Return Helper API

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

概览

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

设置您的 Webhook 端点

端点要求

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

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

注册您的端点

要注册您的 Webhook 端点，请填写 Webhook 设置申请表。该表单包含我们快速完成设置所需的所有信息，是激活端点最快捷的方式。

我们建议使用上述表单，因为它能一步确认所有必要信息。如果您无法使用该表单，也可以通过电子邮件发送申请——请参见下方模板。

电子邮件模板（如无法使用表单）

如果您希望通过电子邮件联系我们，请将以下内容发送至 support@returnhelper.com，并抄送 paco@returnhelper.com、tingfung@returnhelper.com 和 roy@returnhelper.com：

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

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

Dear Support Team,

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

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

事件推送

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

通知请求头

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

请求头	类型	说明
`timestamp`	string	ISO 8601 时间戳
`returnhelper-signature`	string	用于验证的 HMAC-SHA256 签名

签名验证

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

您的签名密钥由 Return Helper 提供（Base64 编码）。请安全存储，切勿泄露。

详细示例

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

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

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

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

逐步验证

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

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

步骤 2 — 从请求头中提取时间戳：

2024-01-12T09:23:08.4863561Z

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

HTTP 方法：POST
您的通知端点 URL：https://s2024-01-12.free.beeceptor.com
步骤 2 中的时间戳
原始 JSON 请求体

拼接后的字符串：

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

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

UE9TVGh0dHBzOi8vczIwMjQtMDEtMTIuZnJlZS5iZWVjZXB0b3IuY29tMjAyNC0wMS0xMlQwOToyMzowOC40ODYzNTYxWnvigJxsYWJlbOKAnTp74oCccmVnaW9uc+KAnTp74oCcUkhDTuKAnTrigJxodHRwczovL2xhYmVsLnJldHVybmhlbHBlcmNoaW5hLmNvbS9sYWJlbC8yMDI0MDEvMTA1OTUtUzI0MDExMi0wMDAwMDAxLXBxazJwdnlkZ3hwLnBkZuKAnX0s4oCcbGFiZWxJZOKAnTozMTAzMyzigJxzaGlwbWVudElk4oCdOjMwMzg1LOKAnGFwaUlk4oCdOjMzLOKAnHJlZktleeKAnTrigJxTMjQwMTEyLTAwMDAwMDHigJ0s4oCcbGFiZWxSZXF1ZXN0SWTigJ06MTA1OTUs4oCcbGFiZWxSZXF1ZXN0U3RhdHVzQ29kZeKAnTrigJxzdWNjZXNz4oCdLOKAnHNlcnZpY2VUeXBl4oCdOuKAnFJFVFVSTl9FTkRJQ0lBX1VTUFNfR1JPVU5EX0FEVkFOVEFHRV9OSuKAnSzigJx0cmFja2luZ051bWJlcuKAnTrigJw5NDM0NjExODk5NTYyMDgyOTAxMTM3IizigJxsYWJlbFVybOKAnTrigJxodHRwczovL2xhYmVsLXNlcnZpY2UtZGV2LWZpbGVzLnJldHVybnNoZWxwZXIuY29tL2xhYmVsLzIwMjQwMS8xMDU5NS1TMjQwMTEyLTAwMDAwMDEtcHFrMnB2eWRneHAucGRm4oCdLOKAnGVycm9y4oCdOm51bGws4oCccXJjb2RlVXJs4oCdOm51bGws4oCccXJjb2RlRXJyb3LigJ06bnVsbCzigJxjb3JyZWxhdGlvbklk4oCdOm51bGws4oCcY2FuY2VsQ3V0b2ZmVGltZeKAnTrigJwyMDI0LTAyLTExVDA5OjIxOjI0LjA3OTUiLOKAnG1ldGHigJ06bnVsbH0s4oCcY2F0ZWdvcnnigJ064oCcbGFiZWxHZW5lcmF0ZWTigJ0s4oCcYWN0aW9u4oCdOuKAnGxhYmVsR2VuZXJhdGVk4oCdLOKAnGV2ZW50VGltZeKAnTrigJwyMDI0LTAxLTEyVDA5OjIzOjA4LjQ4NjI3NDNa4oCdfQ==

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

PEnA0mzKb7fUlGfMgCGhXPjPmPGvW70UU8bkNKdG78WDrQRwzFa572e2JsFIE1e4PLaP9h/ZEvERSR0FBDYNlQ==

操作步骤：

将步骤 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 header

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

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

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

重试机制

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

通用请求体字段

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

字段	类型	说明
`category`	string	通知类别（见下表）
`action`	string	具体事件动作
`eventTime`	string	事件的 ISO 8601 时间戳
`version`	string	通知 Schema 版本
`notificationId`	string	唯一通知 ID（较新的通知中包含）

通知事件参考

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

通知数据结构

面单结果

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

请始终使用 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 的映射

成功示例：

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

失败示例：

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

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

当仓库标记退件运货单(Return Shipment)为已收货时推送。之后始终跟随一个或多个库存已创建事件。 category: rsl / action: markShipmentArrive / version: 202407 shipment 中的关键字段：

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

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

库存已创建

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

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

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

图片已更新

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

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

returnRequestLineItem 中的关键字段：

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

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

未知来件(Unknown Shipment)已分配

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

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

unknownShipment 中的关键字段：

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

回收状态更新

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

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

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

重寄状态更新

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

字段	类型	说明
`resend`	对象	重寄订单详情（见下方）
`trackingNumber`	string	追踪号（可用时）
`failureReason`	string	失败原因（重寄失败时）

resend 中的关键字段：

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

检查 resend.resendStatusCode：

3 — 已完成（检查 trackingNumber）
4 — 失败（检查 failureReason）

增值服务(VAS)更新

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

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

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

库存处理完成

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

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

handlingCode 值：

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

handlingStatusCode 值：

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

库存重新校准

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

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

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

库存元数据更新

当仓库或用户在退货库存(Return Inventory)上添加或更新元数据时推送。 category: updateReturnInventoryMeta / action: updateReturnInventoryMeta 数据包含 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`	运输方式
`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`	运输方式
`customFieldMap`	自定义字段
`deliveryInstructions`	配送说明
`shipmentList`	退件运货单(Return Shipment)列表（见下方）

shipmentList 中每项：

字段	说明
`consolidateShippingShipmentId`	退件运货单(Return Shipment)标识符
`consolidateShippingShipmentNumber`	退件运货单(Return Shipment)编号
`consolidateShippingShipmentStatus`	退件运货单(Return Shipment)状态
`awb`	航空退件运货单(Return Shipment)号
`serviceProvider`	承运商服务提供商
`shipDate`	发货日期
`boxList`	此退件运货单(Return Shipment)中的箱子列表

boxList 中每项：

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

consolidateShippingInventoryList 中每项：

字段	说明
`consolidateShippingInventoryId`	库存标识符
`returnInventoryId`	关联的退货库存(Return Inventory) ID
`rma`	RMA 值
`consolidateShippingInventoryStatus`	库存状态

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

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

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

合并运输 AWB 已更新

当合并退件运货单(Return Shipment)的航空退件运货单(Return Shipment)号更新时推送。 category: consolidateShippingShipmentShipped / action: consolidateShippingShipmentShipped shipment 对象结构与合并退件运货单(Return Shipment)已发出相同，其中 awb 字段已更新。

合并订单已完成

当合并订单中所有退件运货单(Return Shipment)均已发货时推送。 category: consolidateShippingOrderCompleted / action: consolidateShippingOrderCompleted order 对象结构与合并运输全部打包相同，包含完整的 shipmentList（含 boxList 和库存详情）。

合并订单已取消

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

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

事件

​概览

​设置您的 Webhook 端点

​端点要求

​注册您的端点

​事件推送

​通知请求头

​签名验证

​详细示例

​逐步验证

​示例代码

​重试机制

​通用请求体字段

​通知事件参考

​通知数据结构

​面单结果

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

​库存已创建

​图片已更新

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

​回收状态更新

​重寄状态更新

​增值服务(VAS)更新

​库存处理完成

​库存重新校准

​库存元数据更新

​RMA 已更新

​SKU 已更新

​行项拆分

​仓库备注已更新

​买家退货面单已生成

​Shopify 买家退货已创建

​合并运费已更新

​合并运输全部打包

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

​合并运输 AWB 已更新

​合并订单已完成

​合并订单已取消

概览

设置您的 Webhook 端点

端点要求

注册您的端点

事件推送

通知请求头

签名验证

详细示例

逐步验证

示例代码

重试机制

通用请求体字段

通知事件参考

通知数据结构

面单结果

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

库存已创建

图片已更新

未知来件(Unknown Shipment)已分配

回收状态更新

重寄状态更新

增值服务(VAS)更新

库存处理完成

库存重新校准

库存元数据更新

RMA 已更新

SKU 已更新

行项拆分

仓库备注已更新

买家退货面单已生成

Shopify 买家退货已创建

合并运费已更新

合并运输全部打包

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

合并运输 AWB 已更新

合并订单已完成

合并订单已取消