快速开始 - Return Helper API

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

集成前准备

集成工作由 Return Helper 与您的团队共同完成：Return Helper 负责发放凭证并接入您的 Webhook 端点；您的工程团队负责构建请求签名方与 Webhook 接收方。下面的”双方分工”表说明哪些步骤由谁负责，随后是一份非技术项目负责人可与工程团队一起逐项检查的清单。

双方分工

步骤	Return Helper	您的团队
API key 与 token	在 User Portal 的 Settings → Signing Key and API Token 中发放	安全保存；加载至您的服务端配置
Sandbox 访问	Sandbox base URL 见 Base URLs	所有集成测试先在 sandbox 完成
Webhook 接收方	提供用于签名校验的 signing key	搭建 HTTPS 端点，解析原始 body，校验签名，及时返回 `200`
Webhook 端点注册	在您提交申请表后由我们接入端点	端点对公网可达后提交 Webhook Setup Request Form
幂等处理	—	使用 `notificationId` 去重（见 Webhooks）
上生产	Sandbox 验收通过后，由我们发放生产凭证并将您注册的端点切换至生产环境	Sandbox 测试完成、准备承接生产流量时告知 support

卖家检查清单

调用任何会改变状态的接口前，请按顺序完成以下事项：

获取 API 凭证。 登录 User Portal，在 Settings → Signing Key and API Token 复制 API key 与 API token。同一页面也会显示用于校验 webhook 签名的 signing key。
选定环境。 先在 sandbox（UAT）开始。生产 base URL 在 sandbox 验收后再启用 — 见 Base URLs。
构建 Webhook 接收方。 搭建一个 HTTPS 端点：解析原始 POST body，使用 signing key 校验 returnhelper-signature 头，按 notificationId 去重，并及时返回 200 OK。参考代码见 Webhooks → Signature Verification。
将端点注册到我们这边。 端点对公网可达后，提交 Webhook Setup Request Form，由我们完成对接 — 当前不提供自助注册 API。
在 sandbox 端到端验证。 按指南其余章节走完面单创建、仓库到达、到仓后处理流程，确认对应的 webhook 事件能在您的接收方落地。
申请上生产。 Sandbox 测试完成后，联系 support 将您的凭证与已注册端点切换至生产环境。

步骤 4 完成前，面单结果与仓库事件无处投递。在未注册 Webhook 端点的情况下，API 仍接受请求，但您无法取回生成的面单，也无从得知货件何时到仓。

退货流程概览

一次典型的退货包含三个阶段：

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

端到端 Recipes

三条紧凑的 recipe，把每个生命周期节点对应到您要调用的 API、要监听的 Webhook 事件，以及随后的动作。每条 recipe 都会链接到下方的详述章节。

Recipe 1 — 创建退货面单

步骤	您的动作	Webhook（`action`）	后续动作
1	`POST /api/ReturnShipment/createReturnShipment`	—	从同步响应中读取 `shipmentId` 与 `labelRequestStatusCode: queued`。
2（成功）	（等待）	`labelGenerated`	从 Webhook payload 读取 `labelUrl` 与 `trackingNumber`，把面单交给买家。匹配请使用 `shipmentId`，不要用 `labelId`。
2（失败）	（等待）	`labelGenerated`，附带 `labelRequestStatusCode: failed`	检查 `failReasons` 与 `errorMessages`，并把失败通知您的 CS／运营团队。

详细流程：申请退货面单。

Recipe 2 — 接收仓库到达事件

无需任何外发 API 调用 — 等待仓库主动推送事件即可。

步骤	Webhook（`action`）	后续动作
1	`markShipmentArrive`	按 `shipmentId` 匹配到您先前创建的 Return Shipment。
2	`newInventoryCreated` — 每条产生的 Return Inventory 推送一次（一份运货单可能产生多条）	把新的 `returnInventoryId` 关联到您系统中对应的运货单。
3	仓库每次新增或替换图片时推送 `changeLineItemImage`	刷新该 `returnInventoryId` 的图片 URL 缓存。
变体 — Unknown Shipment	包裹无对应卖家 Return Shipment 而到仓时，推送 `assignUnknown` 取代步骤 1+2	当作全新的 Return Inventory 处理；payload 已包含 `returnInventoryId`、`shipmentId`、`returnRequestId`，及分配前的图片。

详细流程：到达仓库时的 Return Inventory。

Recipe 3 — 下发处理指令

按您要执行的操作选择对应行；不同操作对应不同的 API 调用与 Webhook。

操作	API 调用	Webhook（`action`）	后续动作
Dispose / On-hold	`POST /api/ReturnInventory/UpdateReturnInventoryHandling` 并填入 dispose 或 on-hold handling code	`completeInventoryHandling`	库存关闭，无需后续动作。
Resend	`POST /api/Resend/createResend`，引用一个或多个 `returnInventoryId`	`updateResendStatus`	跟踪 resend 的对外运输，直到送达买家。
Recall	`POST /api/Recall/createRecallByReturnInventoryId`，最多 100 个 `returnInventoryId`	`recallUpdateStatus`	跟踪运输，直到库存到达香港集中仓。
VAS	`POST /api/Vas/CreateByReturnInventoryId`，提供 `returnInventoryId` 与所需 VAS 类型	`vasUpdated`（若 VAS 拆分库存则另有 `splitLineItem`）	重新读取库存记录。若 VAS 产生了拆分，每件衍生包裹会得到自己的 `returnInventoryId` 与自己的 RMA。

如需在处理前撤回某条 handling 指令，调用对应操作的取消接口（例如 POST /api/ReturnInventory/CancelReturnInventoryHandling）。详细流程：处理指令。

申请退货面单

面单创建是异步的。流程如下：

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

您必须注册 Webhook 端点才能接收面单结果。否则，您将无法获取已生成的面单。

RMA（退货授权码）

当退件运货单(Return Shipment)进入 Return Helper 仓库时，系统会为其分配一个全局唯一的 RMA。Return Helper 使用 RMA 而非承运商追踪号作为主要通信标识符，原因如下：

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

普通 RMA 格式：

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

示例：TWN-20-230101-D12345-36 拆分 RMA 格式（增值服务(VAS)拆分后）：

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

示例：TWN-20-230101-D12345-01-36

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

当退件运货单(Return Shipment)到达仓库时，系统会将其标记为已收货，并转化为一条或多条**退货库存(Return Inventory)**记录，每条记录都有唯一的 returnInventoryId。

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

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

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

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

库存图片

当图片上传（或图片列表发生变化）时，系统会发送 changeLineItemImage Webhook，其中包含图片 URL 列表。

处理指令

退货库存(Return Inventory)记录创建后，您可以指示仓库如何处理：

销毁(Dispose)

调用更新退货库存(Return Inventory)处理方式，指定销毁处理类型。如需撤销指令，请调用取消退货库存(Return Inventory)处理。

暂扣(Hold)

调用更新退货库存(Return Inventory)处理方式，指定暂扣处理类型。

重寄(Resend)

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

回收(Recall)

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

增值服务(VAS)

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

自定义字段

自定义字段允许您为退货附加任意的键值对元数据。Return Helper 仅存储这些数据，不会对其进行处理——它们会在相关 Webhook 通知中原样返回给您。

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

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

自定义字段可在创建退件运货单(Return Shipment)中使用，并会在 warehouseMarkShipmentArrivedV2 通知中原样返回。

FBA（亚马逊配送）退货

买家可将 FBA 商品发送至 Return Helper 仓库进行处理（补货、补充、回收、销毁等）。 典型 FBA 工作流程：

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

检索历史 FBA 数据（适用于从门户迁移至 API 的现有用户）：

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

检索历史数据后，之后请通过常规 API 调用和 Webhook 事件获取数据，而非持续轮询历史记录。

检索历史数据

本章节适用于正在从 Return Helper 门户迁移至 API 的现有用户。如果您是从零开始集成，所有必要数据均通过常规 API 调用和 Webhook 事件交换——无需检索历史数据。

检索历史退件运货单(Return Shipment)数据： 使用列出退件运货单(Return Shipment)按日期范围检索历史退件运货单(Return Shipment)。 检索历史退货库存(Return Inventory)数据： 使用列出退货库存(Return Inventory)按日期范围检索历史退货库存(Return Inventory)记录。 FBA 历史数据，请参阅上方的检索历史 FBA 数据章节。检索完所有历史数据后，之后请通过常规 API 调用和 Webhook 事件获取数据，而非持续轮询历史记录。

响应结构

每个 API 响应都包含一个 meta 对象，用于指示请求结果状态。 成功响应（status: 200）：

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

失败响应（例如无效的 warehouseId）：

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

status 值不为 200 表示请求未成功完成。errorCode 和 error 字段提供详细信息。

​集成前准备

​双方分工

​卖家检查清单

​退货流程概览

​端到端 Recipes

​Recipe 1 — 创建退货面单

​Recipe 2 — 接收仓库到达事件

​Recipe 3 — 下发处理指令

​申请退货面单

​RMA（退货授权码）

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

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

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

​库存图片

​处理指令

​销毁(Dispose)

​暂扣(Hold)

​重寄(Resend)

​回收(Recall)

​增值服务(VAS)

​自定义字段

​FBA（亚马逊配送）退货

​检索历史数据

​响应结构

集成前准备

双方分工

卖家检查清单

退货流程概览

端到端 Recipes

Recipe 1 — 创建退货面单

Recipe 2 — 接收仓库到达事件

Recipe 3 — 下发处理指令

申请退货面单

RMA（退货授权码）

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

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

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

库存图片

处理指令

销毁(Dispose)

暂扣(Hold)

重寄(Resend)

回收(Recall)

增值服务(VAS)

自定义字段

FBA（亚马逊配送）退货

检索历史数据

响应结构