> ## 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 文档

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

<h1 id="return-helper-api">
  Return Helper API
</h1>

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

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

<h2 id="available-apis">
  可用 API
</h2>

**User API** — 供商家和合作伙伴使用的认证接口，用于管理退货申请(Return Request)、退件运货单(Return Shipment)、面单、库存和账户设置。

**Public API** — 提供参考数据的接口，包括服务类型、仓库列表、状态码和支持的国家等查询数据。

<h2 id="authentication">
  认证
</h2>

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

```http theme={null}
x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json
```

**获取您的凭证：**

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

<Frame caption="用户门户中的签名密钥、API Token 和 API Key">
  <img src="https://mintcdn.com/returnhelper-bb7d6bb7/tE2X5xHsLafOOnHJ/images/api_key_token.png?fit=max&auto=format&n=tE2X5xHsLafOOnHJ&q=85&s=da2475e7149df465d7bbb71f3239883a" alt="用户门户中的签名密钥、API Token 和 API Key" width="1398" height="721" data-path="images/api_key_token.png" />
</Frame>

同一界面也会显示您的**签名密钥**（上图中已标示）。这是一组独立的 Base64 编码密钥——它**不**用于验证 API 请求，而是用来验证传入的 webhook 通知确实来自 Return Helper。您也可以使用[获取 Signing Key](/zh-Hans/api-reference/apiaccount/get-signing-key)以程序方式读取。使用方式请参阅 [Webhooks → 签名验证](/zh-Hans/webhooks#signature-verification)。

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

<h2 id="base-urls">
  基础 URL
</h2>

<h3 id="sandbox">
  沙箱环境
</h3>

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

<h3 id="production">
  生产环境
</h3>

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

<h2 id="idempotency">
  幂等性(Idempotency)
</h2>

对于改变状态的请求（如创建退件运货单(Return Shipment)、库存等），请附带幂等键(Idempotency Key)，以防止网络重试时产生重复操作。

```http theme={null}
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
```

为每个独立的事务请求生成一个新的 UUID（或类似的唯一字符串）。服务器会识别相同密钥的重复提交，并只执行一次操作，从而保证数据完整性。

<h2 id="user-agent-header">
  User-Agent 请求头
</h2>

请附带 `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)
```

完整请求头示例：

```http theme={null}
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)
```

<h2 id="openapi-specification">
  OpenAPI 规范
</h2>

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

<Card title="下载 OpenAPI 规范" icon="download" href="/openapi.json">
  `openapi.json` — OpenAPI 3.1
</Card>

<h2 id="error-handling">
  错误处理
</h2>

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

```json theme={null}
{
  "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`。

<h3 id="failure-modes">
  失败类型
</h3>

| 失败                                     | 实际 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`，业务数据位于顶层                            |

<h3 id="sample--validation-failure">
  验证失败示例
</h3>

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

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

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

<h2 id="general-remarks">
  通用说明
</h2>

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

<h2 id="webhooks">
  Webhooks
</h2>

面单结果及仓库事件（退件运货单(Return Shipment)到达、库存创建、图片上传等）均通过 Webhook 通知以异步方式推送。您必须注册一个通知接收端点来接收这些事件。

请参阅 **Webhooks** 章节，了解完整的通知事件类型及其数据结构。