> ## 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 は、返品リクエストの作成から、配送追跡、ラベル生成、倉庫処理まで、Eコマースの商品返品をエンドツーエンドで管理するAPIスイートを提供しています。

<Note>
  このAPIは**サーバー間連携専用**です。クライアントサイドのコードからこれらのエンドポイントを直接呼び出さないでください。
</Note>

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

**User API** — 返品リクエスト、配送、ラベル、在庫、アカウント設定を管理するための、マーチャントおよびパートナー向け認証済みエンドポイントです。

**Public API** — サービスタイプ、倉庫一覧、ステータスコード、対応国などのルックアップ値を公開する参照データエンドポイントです。

<h2 id="authentication">
  認証
</h2>

すべてのAPIリクエストには、リクエストヘッダーとしてAPIキーとトークンが必要です：

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

**認証情報の取得方法：**

1. Return Helper ユーザーポータルにログインします。
2. **設定 → 署名キーとAPIトークン** に移動します。
3. 既存のキーとトークンのペアが一覧表示されます。新しいペアを生成することもできます。

<Frame caption="ユーザーポータルの署名キー、APIトークン、APIキー">
  <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トークン、APIキー" width="1398" height="721" data-path="images/api_key_token.png" />
</Frame>

同じ画面には**署名キー**も表示されます（上図でハイライトされています）。これは別個の Base64 エンコードされた秘密鍵で、API リクエストの認証には**使用しません**。代わりに、受信した webhook 通知が確かに Return Helper から送信されたものであることを検証します。[Signing Key を取得](/ja/api-reference/apiaccount/get-signing-key)でプログラムから読み取ることもできます。使用方法は [Webhooks → 署名の検証](/ja/webhooks#signature-verification) を参照してください。

<Warning>
  APIトークンと署名キーは秘密情報です。他者と共有したり、クライアントサイドのコードに公開しないでください。
</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>

問題を調査する際にReturn Helperサポートがあなたの連携を識別できるよう、`User-Agent`ヘッダーを含めてください：

```
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">
  Webhook
</h2>

ラベル結果および倉庫イベント（配送到着、在庫作成、画像アップロードなど）は、Webhook通知を通じて非同期で配信されます。これらのイベントを受信するには、通知エンドポイントを登録する必要があります。

通知イベントタイプとそのペイロードの完全な一覧については、**Webhook**セクションを参照してください。