Return Helper API
Return Helper 提供一套完整的 API，用于端到端管理电商产品退货——从退货申请(Return Request)创建，到退件运货单(Return Shipment)跟踪、面单生成，以及仓库处理。该 API 仅适用于服务器到服务器的集成。请勿在客户端代码中直接调用这些接口。
可用 API
User API — 供商家和合作伙伴使用的认证接口，用于管理退货申请(Return Request)、退件运货单(Return Shipment)、面单、库存和账户设置。 Public API — 提供参考数据的接口，包括服务类型、仓库列表、状态码和支持的国家等查询数据。认证
所有 API 请求都需要在请求头中传入 API Key 和 Token：- 登录 Return Helper 用户门户。
- 前往 设置 → 签名密钥和 API Token。
- 您现有的密钥-Token 对会在此列出。您也可以生成新的密钥对。
用户门户中的签名密钥、API Token 和 API Key
基础 URL
沙箱环境
生产环境
幂等性(Idempotency)
对于改变状态的请求（如创建退件运货单(Return Shipment)、库存等），请附带幂等键(Idempotency Key)，以防止网络重试时产生重复操作。User-Agent 请求头
请附带User-Agent 请求头，以便 Return Helper 支持团队在排查问题时识别您的集成：
OpenAPI 规范
完整的 API 规范以 OpenAPI 3.1 文档格式提供。您可以下载后直接导入 Postman 或 Insomnia 等 API 客户端，或使用 OpenAPI Generator 等工具生成客户端 SDK。下载 OpenAPI 规范
openapi.json — OpenAPI 3.1错误处理
每个响应（无论成功或失败）都使用统一的信封格式：correlationId 和 meta 同级）一并返回，例如 getAllCountries 返回 { correlationId, meta, countries: [...] }。在读取业务数据前，请始终检查 meta.errorCode——本 API 采用「软错误」约定，验证失败时会以 HTTP 200 返回，并在 meta.status 中标记为 400，同时填充 meta.errorCode。
失败类型
验证失败示例
correlationId。Return Helper 客服会在排查问题时使用该 ID 追溯请求。
通用说明
- 所有
dateTime参数必须符合 ISO 8601 格式，否则 API 无法解析。 - 日期字符串参数（如
createToStr、createFromStr）也必须符合 ISO 8601 格式；时间部分将被忽略。 - API 返回的所有时间戳均为 UTC 时间。