快速开始

​

前提条件

1. 获取 API 凭证 — 请参阅认证章节。
2. 准备好可接收 Return Helper 异步事件的 Webhook 通知端点。如果未提供通知端点，将无法接收面单结果和仓库事件。
3. 通读本指南，了解主要退货流程。

​

退货流程概览

1. 到仓前 — 创建退件运货单(Return Shipment)并获取快递面单。
2. 到达仓库 — 包裹被扫描入库；图片上传；退件运货单(Return Shipment)转化为退货库存(Return Inventory)记录。
3. 到仓后处理 — 指示仓库如何处理该库存（销毁、重寄、回收、增值服务(VAS)等）。

​

申请退货面单

1. 调用创建退件运货单(Return Shipment)，创建退件运货单(Return Shipment)记录并将面单请求加入队列。
2. Return Helper 生成面单后，通过 label 通知事件 将结果推送至您的 Webhook 通知端点。

​

RMA（退货授权码）

• 追踪号可能在不同承运商之间重复，甚至在同一承运商内部重复。
• 当包裹通过增值服务(VAS)进行拆分时，每个生成的包裹都会获得自己的 RMA。

<仓库前缀>-<仓库ID>-<YYMMDD>-<环境字母><最多5位序列号>-<校验位>

<仓库前缀>-<仓库ID>-<YYMMDD>-<环境字母><最多5位序列号>-<拆分序列2位>-<校验位>

​

到仓后的退货库存(Return Inventory)

​

类型 1 — 卖家主动创建的退件运货单(Return Shipment)

1. 卖家通过 API 创建了退件运货单(Return Shipment)并提供了面单。
2. 仓库标记为已收货 → 发送 warehouseMarkShipmentArrivedV2 Webhook，随后发送 inventoryCreated（其中包含 returnInventoryId）。
3. 如果单张面单涵盖多个包裹，每个包裹将成为独立的退货库存(Return Inventory)记录，共享相同的 shipmentId 和 returnRequestId。每条库存记录发送一次 inventoryCreated 事件。
4. 库存图片随后上传，并通过 changeLineItemImage 推送。

​

类型 2 — 未知来件(Unknown Shipment)被分配给卖家

1. 退件到达时没有卖家创建的记录，但被人工识别为属于某卖家。
2. 发送 assignUnknown Webhook，其中包含退货库存(Return Inventory)数据、returnInventoryId、shipmentId 和 returnRequestId。
3. 如果包裹包含多件商品，可能会跟随发送多个 inventoryCreated 事件。
4. 分配前拍摄的图片包含在 assignUnknown 中；之后的图片变动通过 changeLineItemImage 推送。

​

库存图片

​

处理指令

​

销毁(Dispose)

​

暂扣(Hold)

​

重寄(Resend)

1. 调用创建重寄订单，附上 returnInventoryId 列表。
2. 通过 resend Webhook 通知接收重寄追踪号。
3. 如不再需要重寄，调用取消重寄订单。

​

回收(Recall)

1. 调用按退货库存(Return Inventory) ID 创建回收，最多可传入 100 个 returnInventoryId。
2. 追踪更新和取件状态变更通过 recall Webhook 通知推送。

​

增值服务(VAS)

1. 调用创建增值服务(VAS)，附上 returnInventoryId 和所需增值服务(VAS)类型。
2. 结果通过 UpdateVas Webhook 通知推送。

​

自定义字段

• 类型：Dictionary<string, string>
• 每次退货最多 24 个自定义字段。

{
  "customFieldMap": {
    "customerId": "buyer123",
    "dateOfPurchase": "2024-07-01"
  }
}

​

FBA（亚马逊配送）退货

1. 调用创建 FBA 退件运货单(FBA Shipment)，通知 Return Helper 并将商品发往仓库。
2. 退件运货单(Return Shipment)收货后，作为 FBA 库存入库（包含 fnsku 和 quantity），并通过 Webhook 推送。
3. 通过按 FNSKU 获取 FBA 仓库库存列表查询现有 FBA 库存。
4. 通过创建 FBA 指令创建操作指令（补货操作需要额外的运输信息，目前 API 暂不支持）。
5. Return Helper 处理指令后，通过 Webhook 通知您结果。
6. 通过相关”获取 FBA 指令详情”接口（回收、销毁、补货、其他）查询指令状态。

1. 使用列出 FBA 退件运货单(FBA Shipment)按日期范围检索历史退件运货单(Return Shipment)，收集 fbaShipmentId 值。
2. 调用获取 FBA 退件运货单(FBA Shipment)商品列表获取每个退件运货单(Return Shipment)的商品、FNSKU 和数量。
3. 使用按 FNSKU 获取 FBA 仓库库存列表查看当前库存。
4. 使用列出 FBA 指令查找历史指令。
5. 使用获取 FBA 指令商品列表按指令获取行项明细。

​

检索历史数据

​

响应结构

{
  "apiBalances": [
    {
      "apiBalanceId": 7,
      "currencyCode": "usd",
      "balance": 2044.233
    }
  ],
  "correlationId": "0HM9VIKSKH2CB:00000002",
  "meta": {
    "status": 200,
    "data": {},
    "errorCode": null,
    "error": {}
  },
  "totalNumberOfRecords": 1
}

{
  "correlationId": "0HM9VIKSKH2CF:00000002",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "warehouseId": "The value 'invalid' is not valid."
    }
  }
}