此页面由 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
- 登录 Return Helper 用户门户。
- 前往 设置 → 签名密钥和 API Token。
- 您现有的密钥-Token 对会在此列出。您也可以生成新的密钥对。
您的 API Token 是私密的。请勿共享或在客户端代码中暴露它。
基础 URL
沙箱环境
| 接口 | 基础 URL |
|---|
| User API | https://api.returnshelper.com/uat/user/api |
| Public API | https://api.returnshelper.com/uat/public/api |
生产环境
| 接口 | 基础 URL |
|---|
| User API | https://api.returnhelpercentre.com/v1/user/api |
| User API（中国） | https://api.returnhelperchina.com/user/ |
| Public API | https://api.returnhelpercentre.com/v1/public/api |
幂等性(Idempotency)
对于改变状态的请求（如创建退件运货单(Return Shipment)、库存等），请附带幂等键(Idempotency Key)，以防止网络重试时产生重复操作。
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
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
通用说明
- 所有
dateTime 参数必须符合 ISO 8601 格式，否则 API 无法解析。
- 日期字符串参数（如
createToStr、createFromStr）也必须符合 ISO 8601 格式；时间部分将被忽略。
- API 返回的所有时间戳均为 UTC 时间。
Webhooks
面单结果及仓库事件（退件运货单(Return Shipment)到达、库存创建、图片上传等）均通过 Webhook 通知以异步方式推送。您必须注册一个通知接收端点来接收这些事件。
请参阅 Webhooks 章节，了解完整的通知事件类型及其数据结构。
