> ## 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. # 快速开始 > 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](/zh-Hans/introduction#base-urls) | 所有集成测试先在 sandbox 完成 | | Webhook 接收方 | 提供用于签名校验的 signing key | 搭建 HTTPS 端点，解析原始 body，校验签名，及时返回 `200` | | Webhook 端点注册 | 在您提交申请表后由我们接入端点 | 端点对公网可达后提交 [Webhook Setup Request Form](https://forms.gle/iBVkRZvfLQ8o1Nqg8) | | 幂等处理 | — | 使用 `notificationId` 去重（见 [Webhooks](/zh-Hans/webhooks#event-delivery)） | | 上生产 | Sandbox 验收通过后，由我们发放生产凭证并将您注册的端点切换至生产环境 | Sandbox 测试完成、准备承接生产流量时告知 support |

卖家检查清单

调用任何会改变状态的接口前，请按顺序完成以下事项： 1. **获取 API 凭证。** 登录 User Portal，在 **Settings → Signing Key and API Token** 复制 API key 与 API token。同一页面也会显示用于校验 webhook 签名的 **signing key**。 2. **选定环境。** 先在 sandbox（UAT）开始。生产 base URL 在 sandbox 验收后再启用 — 见 [Base URLs](/zh-Hans/introduction#base-urls)。 3. **构建 Webhook 接收方。** 搭建一个 HTTPS 端点：解析原始 POST body，使用 signing key 校验 `returnhelper-signature` 头，按 `notificationId` 去重，并及时返回 `200 OK`。参考代码见 [Webhooks → Signature Verification](/zh-Hans/webhooks#signature-verification)。 4. **将端点注册到我们这边。** 端点对公网可达后，提交 [Webhook Setup Request Form](https://forms.gle/iBVkRZvfLQ8o1Nqg8)，由我们完成对接 — 当前不提供自助注册 API。 5. **在 sandbox 端到端验证。** 按指南其余章节走完面单创建、仓库到达、到仓后处理流程，确认对应的 webhook 事件能在您的接收方落地。 6. **申请上生产。** Sandbox 测试完成后，联系 support 将您的凭证与已注册端点切换至生产环境。 步骤 4 完成前，面单结果与仓库事件无处投递。在未注册 Webhook 端点的情况下，API 仍接受请求，但您无法取回生成的面单，也无从得知货件何时到仓。

退货流程概览

一次典型的退货包含三个阶段： 1. **到仓前** — 创建退件运货单(Return Shipment)并获取快递面单。 2. **到达仓库** — 包裹被扫描入库；图片上传；退件运货单(Return Shipment)转化为退货库存(Return Inventory)记录。 3. **到仓后处理** — 指示仓库如何处理该库存（销毁、重寄、回收、增值服务(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／运营团队。 | 详细流程：[申请退货面单](#requesting-a-return-label)。

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](#return-inventory-at-warehouse-arrival)。

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`）。 详细流程：[处理指令](#handling-instructions)。 ***

申请退货面单

面单创建是**异步**的。流程如下： 1. 调用[**创建退件运货单(Return Shipment)**](/zh-Hans/api-reference/returnshipment/create-return-shipment)，创建退件运货单(Return Shipment)记录并将面单请求加入队列。 2. Return Helper 生成面单后，通过 [**label** 通知事件](/zh-Hans/webhooks#label-result) 将结果推送至您的 Webhook 通知端点。 您必须注册 Webhook 端点才能接收面单结果。否则，您将无法获取已生成的面单。 ```mermaid theme={null} sequenceDiagram participant S as 卖家系统 participant RH as Return Helper (RH) participant W as 卖家 Webhook 端点 S->>RH: createReturnShipment(request) RH->>RH: 验证请求 alt 无验证错误 RH-->>S: 200 OK（请求提交成功） RH->>RH: 将面单生成任务加入队列 RH->>W: POST /label-notification（结果数据） Note over W: [面单生成成功]
数据包含 labelUrl Note over W: [面单生成失败]
数据包含 failReasons + errorMessages else 验证错误 RH-->>S: 4xx 错误（验证错误信息） end ``` ***

RMA（退货授权码）

当退件运货单(Return Shipment)进入 Return Helper 仓库时，系统会为其分配一个全局唯一的 RMA。Return Helper 使用 RMA 而非承运商追踪号作为主要通信标识符，原因如下： * 追踪号可能在不同承运商之间重复，甚至在同一承运商内部重复。 * 当包裹通过增值服务(VAS)进行拆分时，每个生成的包裹都会获得自己的 RMA。 **普通 RMA 格式：** ``` <仓库前缀>-<仓库ID>--<环境字母><最多5位序列号>-<校验位> ``` 示例：`TWN-20-230101-D12345-36` **拆分 RMA 格式**（增值服务(VAS)拆分后）： ``` <仓库前缀>-<仓库ID>--<环境字母><最多5位序列号>-<拆分序列2位>-<校验位> ``` 示例：`TWN-20-230101-D12345-01-36` ***

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

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

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

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

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

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

库存图片

当图片上传（或图片列表发生变化）时，系统会发送 [**changeLineItemImage**](/zh-Hans/webhooks#image-updated) Webhook，其中包含图片 URL 列表。 ***

处理指令

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

销毁(Dispose)

调用[**更新退货库存(Return Inventory)处理方式**](/zh-Hans/api-reference/returninventory/update-return-inventory-handling)，指定销毁处理类型。如需撤销指令，请调用[**取消退货库存(Return Inventory)处理**](/zh-Hans/api-reference/returninventory/cancel-return-inventory-handling)。

暂扣(Hold)

调用[**更新退货库存(Return Inventory)处理方式**](/zh-Hans/api-reference/returninventory/update-return-inventory-handling)，指定暂扣处理类型。

重寄(Resend)

1. 调用[**创建重寄订单**](/zh-Hans/api-reference/resend/create-resend-order)，附上 `returnInventoryId` 列表。 2. 通过 [**resend**](/zh-Hans/webhooks#resend-status-update) Webhook 通知接收重寄追踪号。 3. 如不再需要重寄，调用[**取消重寄订单**](/zh-Hans/api-reference/resend/cancel-resend-order)。

回收(Recall)

1. 调用[**按退货库存(Return Inventory) ID 创建回收**](/zh-Hans/api-reference/recall/create-recall-by-return-inventory-ids)，最多可传入 100 个 `returnInventoryId`。 2. 追踪更新和取件状态变更通过 [**recall**](/zh-Hans/webhooks#recall-status-update) Webhook 通知推送。

增值服务(VAS)

1. 调用[**创建增值服务(VAS)**](/zh-Hans/api-reference/vas/create-vas-by-return-inventory-id)，附上 `returnInventoryId` 和所需增值服务(VAS)类型。 2. 结果通过 [**UpdateVas**](/zh-Hans/webhooks#vas-update) Webhook 通知推送。 ***

自定义字段

自定义字段允许您为退货附加任意的键值对元数据。Return Helper 仅存储这些数据，不会对其进行处理——它们会在相关 Webhook 通知中原样返回给您。 * 类型：`Dictionary` * 每次退货最多 24 个自定义字段。 ```json theme={null} { "customFieldMap": { "customerId": "buyer123", "dateOfPurchase": "2024-07-01" } } ``` 自定义字段可在[**创建退件运货单(Return Shipment)**](/zh-Hans/api-reference/returnshipment/create-return-shipment)中使用，并会在 [**warehouseMarkShipmentArrivedV2**](/zh-Hans/webhooks#warehouse-shipment-arrived-v2) 通知中原样返回。 ***

FBA（亚马逊配送）退货

买家可将 FBA 商品发送至 Return Helper 仓库进行处理（补货、补充、回收、销毁等）。 **典型 FBA 工作流程：** 1. 调用[**创建 FBA 退件运货单(FBA Shipment)**](/zh-Hans/api-reference/fbashipment/create-fba-shipment)，通知 Return Helper 并将商品发往仓库。 2. 退件运货单(Return Shipment)收货后，作为 FBA 库存入库（包含 `fnsku` 和 `quantity`），并通过 Webhook 推送。 3. 通过[**按 FNSKU 获取 FBA 仓库库存列表**](/zh-Hans/api-reference/fbawarehouseinventory/get-fba-warehouse-inventory-list-by-fnsku)查询现有 FBA 库存。 4. 通过[**创建 FBA 指令**](/zh-Hans/api-reference/fbainstruction/create-fba-instructions)创建操作指令（补货操作需要额外的运输信息，目前 API 暂不支持）。 5. Return Helper 处理指令后，通过 Webhook 通知您结果。 6. 通过相关"获取 FBA 指令详情"接口（回收、销毁、补货、其他）查询指令状态。 **检索历史 FBA 数据**（适用于从门户迁移至 API 的现有用户）： 1. 使用[**列出 FBA 退件运货单(FBA Shipment)**](/zh-Hans/api-reference/fbashipment/list-fba-shipments-with-pagination)按日期范围检索历史退件运货单(Return Shipment)，收集 `fbaShipmentId` 值。 2. 调用[**获取 FBA 退件运货单(FBA Shipment)商品列表**](/zh-Hans/api-reference/fbashipmentitem/get-items-in-fba-shipment)获取每个退件运货单(Return Shipment)的商品、FNSKU 和数量。 3. 使用[**按 FNSKU 获取 FBA 仓库库存列表**](/zh-Hans/api-reference/fbawarehouseinventory/get-fba-warehouse-inventory-list-by-fnsku)查看当前库存。 4. 使用[**列出 FBA 指令**](/zh-Hans/api-reference/fbainstruction/list-fba-instructions-with-pagination)查找历史指令。 5. 使用[**获取 FBA 指令商品列表**](/zh-Hans/api-reference/fbainstructionitem/get-items-in-fba-instruction)按指令获取行项明细。 检索历史数据后，之后请通过常规 API 调用和 Webhook 事件获取数据，而非持续轮询历史记录。 ***

检索历史数据

本章节适用于正在从 Return Helper 门户迁移至 API 的现有用户。如果您是从零开始集成，所有必要数据均通过常规 API 调用和 Webhook 事件交换——无需检索历史数据。 **检索历史退件运货单(Return Shipment)数据：** 使用[**列出退件运货单(Return Shipment)**](/zh-Hans/api-reference/shipment/list-shipments-with-pagination)按日期范围检索历史退件运货单(Return Shipment)。 **检索历史退货库存(Return Inventory)数据：** 使用[**列出退货库存(Return Inventory)**](/zh-Hans/api-reference/returninventory/list-return-inventories-with-pagination)按日期范围检索历史退货库存(Return Inventory)记录。 FBA 历史数据，请参阅上方的**检索历史 FBA 数据**章节。 检索完所有历史数据后，之后请通过常规 API 调用和 Webhook 事件获取数据，而非持续轮询历史记录。 ***

响应结构

每个 API 响应都包含一个 `meta` 对象，用于指示请求结果状态。 **成功响应（`status: 200`）：** ```json theme={null} { "apiBalances": [ { "apiBalanceId": 7, "currencyCode": "usd", "balance": 2044.233 } ], "correlationId": "0HM9VIKSKH2CB:00000002", "meta": { "status": 200, "data": {}, "errorCode": null, "error": {} }, "totalNumberOfRecords": 1 } ``` **失败响应（例如无效的 `warehouseId`）：** ```json theme={null} { "correlationId": "0HM9VIKSKH2CF:00000002", "meta": { "status": 400, "data": {}, "errorCode": "VALIDATION_FAILED", "error": { "warehouseId": "The value 'invalid' is not valid." } } } ``` `status` 值不为 `200` 表示请求未成功完成。`errorCode` 和 `error` 字段提供详细信息。