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

Return Helper API

Return Helper 提供一套完整的 API，用于端到端管理电商产品退货——从退货申请(Return Request)创建，到退件运货单(Return Shipment)跟踪、面单生成，以及仓库处理。

该 API 仅适用于服务器到服务器的集成。请勿在客户端代码中直接调用这些接口。

公告

速率限制：每秒 1 个请求

2026 年 11 月 1 日起API 每秒最多接受一个请求。请在旺季前检查您的调用频率。

创建 Resend Order 支持 Seller Reference Number

如您设置了 resendNumber，需采取行动所有账户均可搜索 Resend。resendNumber 将变为只读。

新 Webhook 事件：交易已添加

2026 年 10 月 5 日起每笔扣费、退款和充值都会推送到您的 Webhook 端点。

API 速率限制：每秒 1 个请求

自 2026 年 11 月 1 日起，Return Helper 将对 API 实施每秒 1 个请求的速率限制，以在旺季期间提升所有集成的服务稳定性。

请控制调用频率，每秒不超过一个请求。
请使用 Webhooks 接收运货单、库存和补寄的更新，而不是轮询列表接口。

创建 Resend Order 支持 Seller Reference Number

创建 Resend Order（User API）将与按 SKU 创建 Resend 一样，接受选填的 sellerReferenceNumber。届时所有账户（不限 Enterprise）都可以使用按 Seller Reference Number 搜索 Resend 查找补寄。 sellerReferenceNumber 为选填，现有集成可照常运行。但有一项破坏性变更：resendNumber 将变为由 Return Helper 生成的只读值。

如果您的集成在创建 Resend Order 时设置 resendNumber（例如填入您的发票或订单 ID），需要采取行动：请在里程碑 2 之前，将该值改为设置在 sellerReferenceNumber。如果您从未设置 resendNumber，则无需任何操作。

里程碑	日期	变更内容
里程碑 1	待公布	创建 Resend Order 接受 `sellerReferenceNumber`。您仍可设置 `resendNumber`。如果您设置了 `resendNumber` 但未设置 `sellerReferenceNumber`，Return Helper 会将您的 `resendNumber` 复制到 `sellerReferenceNumber`，因此无需您做任何修改即可搜索该补寄。
里程碑 2	里程碑 1 之后 3 个月	设置了 `resendNumber` 的请求将被拒绝。`resendNumber` 始终由 Return Helper 生成。

请在里程碑 1 与里程碑 2 之间完成迁移：

将您自己的参考编号改为通过 sellerReferenceNumber 发送，而不是 resendNumber。
如果您以 resendNumber 匹配重寄状态更新 webhook 或您自己的记录，请改为以 sellerReferenceNumber 匹配。

与 resendNumber 不同，sellerReferenceNumber 不是唯一值——Return Helper 不会拒绝重复的值。为避免重试时重复创建补寄，请发送 x-returnhelper-idempotency-key 请求头。我们将在此处及更新日志公布里程碑 1 的日期。

新 Webhook 事件：交易已添加

自 2026 年 10 月 5 日起，每当有交易记入您的账户，Return Helper 都会向每个已注册的 Webhook 端点推送交易已添加事件。您无需额外注册。2026 年 10 月 5 日之前记入的交易不会推送。

如果您的端点对无法识别的事件返回非 2xx 状态码，需要采取行动。推送失败会重试；连续失败 10 次后，向您端点的推送将暂停 24 小时，其他所有事件也包括在内。请对您不处理的事件返回 2xx。

更新日志

公告

交易已添加 Webhook

公告：交易已添加 Webhook 事件，自 2026 年 10 月 5 日起推送。详见公告。

新功能

取消退货面单

您现在可以通过取消退货面单取消退货面单。如需修正运货单，请先取消其面单，再创建新的 Return Shipment。

公告

速率限制与创建 Resend 功能升级

公告：API 速率限制为每秒 1 个请求，自 2026 年 11 月 1 日起生效。
公告：创建 Resend Order 支持 sellerReferenceNumber；resendNumber 将变为只读。

新功能

自助管理 Webhook 端点

您现在可以通过添加 Notification Endpoint、列出 Notification Endpoints 和删除 Notification Endpoint 自行管理 webhook 通知端点。

可用 API

User API — 供商家和合作伙伴使用的认证接口，用于管理退货申请(Return Request)、退件运货单(Return Shipment)、面单、库存和账户设置。 Public API — 提供参考数据的接口，包括服务类型、仓库列表、状态码和支持的国家等查询数据。

认证

所有 API 请求都需要在请求头中传入 API Key 和 Token：

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json

获取您的凭证：

登录 Return Helper 用户门户。
前往 设置 → 签名密钥和 API Token。
您现有的密钥-Token 对会在此列出。您也可以生成新的密钥对。

同一界面也会显示您的签名密钥（上图中已标示）。这是一组独立的 Base64 编码密钥——它不用于验证 API 请求，而是用来验证传入的 webhook 通知确实来自 Return Helper。您也可以使用获取 Signing Key以程序方式读取。使用方式请参阅 Webhooks → 签名验证。

您的 API Token 与签名密钥均属私密信息。请勿共享或在客户端代码中暴露它们。

基础 URL

沙箱环境

接口	基础 URL
User API	`https://api.returnshelper.com/uat/user`
Public API	`https://api.returnshelper.com/uat/public`

生产环境

接口	基础 URL
User API	`https://api.returnhelpercentre.com/v1/user`
User API（中国）	`https://api.returnhelperchina.com/user`
Public API	`https://api.returnhelpercentre.com/v1/public`

幂等性(Idempotency)

以下端点接受 x-returnhelper-idempotency-key 请求头，确保重试的请求只处理一次。

x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY

为每个独立的请求生成一个新的 UUID（或类似的唯一字符串），并仅在重试同一请求时发送相同的键。该请求头为选填。不带该请求头的请求会正常处理，但不具备防重复的保护。重复使用已完成请求之键的请求会被拒绝，而不会再次处理——请参阅幂等键失败。

端点	路由
创建 Return Shipment	`POST /api/ReturnShipment/createReturnShipment`
取消退货面单	`POST /api/Label/CancelLabel`
创建 Resend Order	`POST /api/Resend/createResend`
按 SKU 创建 Resend	`POST /api/Resend/createResendBySku`
取消 Resend Order	`POST /api/Resend/cancelResend`
为 Return Inventory 分配 SKU	`POST /api/ReturnInventory/assignReturnInventorySku`
添加 Notification Endpoint	`POST /api/Notification/Add`
删除 Notification Endpoint	`POST /api/Notification/Delete`

其他端点会忽略该请求头。

User-Agent 请求头

请附带 User-Agent 请求头，以便 Return Helper 支持团队在排查问题时识别您的集成：

User-Agent: {app name}/{app version} (Platform={os version}; Runtime={runtime version}; Language={language})

示例：

User-Agent: CompanyABCApi/2024.16.0 (Platform=Unix/13.4.0; Runtime=8.0.2; Language=CSharp12)

完整请求头示例：

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
User-Agent: YourApp/1.0.0 (Platform=Linux/5.15; Runtime=8.0.2; Language=CSharp12)

OpenAPI 规范

完整的 API 规范以 OpenAPI 3.1 文档格式提供。您可以下载后直接导入 Postman 或 Insomnia 等 API 客户端，或使用 OpenAPI Generator 等工具生成客户端 SDK。

下载 OpenAPI 规范

openapi.json — OpenAPI 3.1

错误处理

每个响应（无论成功或失败）都使用统一的信封格式：

{
  "correlationId": "0HNL9S3BA31VM:00000001",
  "meta": {
    "status": 200,
    "data": {},
    "errorCode": null,
    "error": {}
  }
}

成功响应会将业务数据作为顶级字段（与 correlationId 和 meta 同级）一并返回，例如 getAllCountries 返回 { correlationId, meta, countries: [...] }。在读取业务数据前，请始终检查 meta.errorCode——本 API 采用「软错误」约定，验证失败时会以 HTTP 200 返回，并在 meta.status 中标记为 400，同时填充 meta.errorCode。

失败类型

失败	实际 HTTP	响应体
缺少或无效的 `x-rr-apikey` / `x-rr-apitoken`	401	`meta.status: 401`，`meta.error.message` 描述鉴权失败原因
验证失败（缺少字段、类型错误、业务规则违规）	200	`meta.status: 400`，`meta.errorCode: "VALIDATION_FAILED"`，`meta.error` 以请求字段为键
成功	200	`meta.status: 200`，`meta.errorCode: null`，业务数据位于顶层

验证失败示例

{
  "correlationId": "0HNLB2U6T1QG1:00000001",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "returnInventoryId": "'return Inventory Id' must not be empty."
    }
  }
}

请勿仅根据实际 HTTP 状态码判断成功与否。200 OK 仍可能代表逻辑失败——务必检查 meta.status 和 meta.errorCode。

集成时，请记录每个响应的 correlationId。Return Helper 客服会在排查问题时使用该 ID 追溯请求。

通用说明

所有 dateTime 参数必须符合 ISO 8601 格式，否则 API 无法解析。
日期字符串参数（如 createToStr、createFromStr）也必须符合 ISO 8601 格式；时间部分将被忽略。
API 返回的所有时间戳均为 UTC 时间。

Webhooks

面单结果及仓库事件（退件运货单(Return Shipment)到达、库存创建、图片上传等）均通过 Webhook 通知以异步方式推送。您必须注册一个通知接收端点来接收这些事件。请参阅 Webhooks 章节，了解完整的通知事件类型及其数据结构。

联系技术支持

如有技术问题或集成问题，请发送电子邮件至 support@returnhelper.com。为便于我们排查，请提供以下信息：

响应中的 correlationId
所用环境（沙箱环境或生产环境）及调用的接口
请求时间（含时区）
请求体及收到的响应

请勿在邮件中提供您的 API token 或 signing key。

概览

简介

Return Helper API

公告

速率限制：每秒 1 个请求

创建 Resend Order 支持 Seller Reference Number

新 Webhook 事件：交易已添加

API 速率限制：每秒 1 个请求

创建 Resend Order 支持 Seller Reference Number

新 Webhook 事件：交易已添加

更新日志

可用 API

认证

基础 URL

沙箱环境

生产环境

幂等性(Idempotency)

User-Agent 请求头

OpenAPI 规范

下载 OpenAPI 规范

错误处理

失败类型

验证失败示例

通用说明

Webhooks

联系技术支持

​Return Helper API

​公告

速率限制：每秒 1 个请求

创建 Resend Order 支持 Seller Reference Number

新 Webhook 事件：交易已添加

​API 速率限制：每秒 1 个请求

​创建 Resend Order 支持 Seller Reference Number

​新 Webhook 事件：交易已添加

​更新日志

​可用 API

​认证

​基础 URL

​沙箱环境

​生产环境

​幂等性(Idempotency)

​User-Agent 请求头

​OpenAPI 规范

下载 OpenAPI 规范

​错误处理

​失败类型

​验证失败示例

​通用说明

​Webhooks

​联系技术支持

Return Helper API

公告

API 速率限制：每秒 1 个请求

创建 Resend Order 支持 Seller Reference Number

新 Webhook 事件：交易已添加

更新日志

可用 API

认证

基础 URL

沙箱环境

生产环境

幂等性(Idempotency)

User-Agent 请求头

OpenAPI 规范

错误处理

失败类型

验证失败示例

通用说明

Webhooks

联系技术支持