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

​
Return Helper API

Return Helper 提供一套完整的 API，用于端到端管理电商产品退货——从退货申请(Return Request)创建，到退件运货单(Return Shipment)跟踪、面单生成，以及仓库处理。
该 API 仅适用于服务器到服务器的集成。请勿在客户端代码中直接调用这些接口。

​
可用 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
获取您的凭证：
  1. 登录 Return Helper 用户门户。
  2. 前往 设置 → 签名密钥和 API Token。
  3. 您现有的密钥-Token 对会在此列出。您也可以生成新的密钥对。
用户门户中的签名密钥、API Token 和 API Key
您的 API Token 是私密的。请勿共享或在客户端代码中暴露它。

​
基础 URL

​
沙箱环境

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

​
生产环境

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

​
幂等性(Idempotency)

对于改变状态的请求（如创建退件运货单(Return Shipment)、库存等），请附带幂等键(Idempotency Key)，以防止网络重试时产生重复操作。 
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
为每个独立的事务请求生成一个新的 UUID（或类似的唯一字符串）。服务器会识别相同密钥的重复提交，并只执行一次操作，从而保证数据完整性。

​
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-apitoken401meta.status: 401，meta.error.message 描述鉴权失败原因
验证失败（缺少字段、类型错误、业务规则违规）200meta.status: 400，meta.errorCode: "VALIDATION_FAILED"，meta.error 以请求字段为键
成功200meta.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 章节，了解完整的通知事件类型及其数据结构。