> ## 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 金鑰和 Token：

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

**取得您的憑證：**

1. 登入 Return Helper 使用者入口網站。
2. 前往 **Settings → Signing Key and 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-Hant/api-reference/apiaccount/get-signing-key)以程式方式讀取。使用方式請參閱 [Webhooks → 簽章驗證](/zh-Hant/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** 章節，了解完整的通知事件類型列表及其 Payload。