> ## 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の主要なコンセプトと一般的な連携ワークフロー このページはAIによって自動翻訳されています。不明点や相違がある場合は、英語版を正式版として参照してください。

連携を始める前に

連携作業は Return Helper とお客様のチームで分担します。Return Helper が認証情報の発行とお客様の Webhook エンドポイント接続を担当し、お客様のエンジニアリングチームがリクエスト署名側と Webhook 受信側を実装します。下表「担当範囲」で役割分担を示し、その後に非エンジニアのプロジェクト担当者がエンジニアリングチームと一緒にたどれるチェックリストを記載します。

担当範囲

| ステップ | Return Helper | お客様のチーム | | ----------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | API key と token | User Portal の **Settings → Signing Key and API Token** で発行 | 安全に保管し、サーバー設定に読み込む | | Sandbox アクセス | Sandbox の base URL は [Base URLs](/ja/introduction#base-urls) を参照 | 連携テストはすべて sandbox で先に実施 | | Webhook 受信側 | 署名検証に使う signing key を提供 | HTTPS エンドポイントを構築し、生 body を解析、署名を検証、`200` を速やかに返す | | Webhook エンドポイント登録 | 申請フォーム提出後にこちらでエンドポイントを接続 | エンドポイントが公開ネットワークから到達可能になった時点で [Webhook Setup Request Form](https://forms.gle/iBVkRZvfLQ8o1Nqg8) を提出 | | 冪等性 | — | `notificationId` で重複を除去（[Webhooks](/ja/webhooks#event-delivery) を参照） | | 本番稼働 | Sandbox 検証完了後に本番認証情報を発行し、登録済みエンドポイントを本番環境へ切替 | Sandbox テスト完了・本番トラフィック受け入れ準備が整い次第 support に連絡 |

セラー向けチェックリスト

状態を変更するエンドポイントを呼び出す前に、以下を順番に完了してください： 1. **API 認証情報の取得。** User Portal にログインし、**Settings → Signing Key and API Token** から API key と API token をコピーします。同じ画面に、webhook 署名検証に使う **signing key** も表示されます。 2. **環境の選択。** まず sandbox（UAT）で開始します。本番 base URL は sandbox 検証完了後にのみ有効になります — [Base URLs](/ja/introduction#base-urls) を参照。 3. **Webhook 受信側の構築。** HTTPS エンドポイントを立ち上げ、生 POST body を解析し、signing key で `returnhelper-signature` ヘッダーを検証し、`notificationId` で重複を除去し、`200 OK` を速やかに返します。サンプルコードは [Webhooks → Signature Verification](/ja/webhooks#signature-verification) にあります。 4. **エンドポイントを当社に登録。** エンドポイントが公開ネットワークから到達可能になったら、[Webhook Setup Request Form](https://forms.gle/iBVkRZvfLQ8o1Nqg8) を提出します。接続作業は当社で行います — 現時点ではセルフサーブ登録 API はありません。 5. **Sandbox でエンドツーエンド検証。** 本ガイドの残りの章に沿って、ラベル作成、倉庫到着、到着後処理のフローを実行し、対応する webhook イベントが受信側に届くことを確認します。 6. **本番稼働申請。** Sandbox テスト完了後、support に連絡して認証情報と登録済みエンドポイントを本番環境へ切り替えます。 ステップ 4 が完了するまで、ラベル結果と倉庫イベントの配信先がありません。Webhook エンドポイントが未登録の場合、API はリクエストを受け付けますが、生成されたラベルを取得することも、貨物がいつ到着したかを知ることもできません。

返品フローの概要

典型的な返品には3つの段階があります： 1. **倉庫到着前** — 返品配送(Return Shipment)を作成し、配送ラベルを受け取ります。 2. **倉庫到着** — 荷物がスキャンされ、画像がアップロードされ、配送が返品在庫(Return Inventory)レコードになります。 3. **到着後の処理** — 在庫をどのように処理するかを倉庫に指示します（廃棄、再送、リコール、付加価値サービス(VAS)など）。 ***

エンドツーエンド Recipes

3 つのコンパクトな recipe で、ライフサイクルの各ポイントに対して、呼び出す API、待ち受ける Webhook イベント、その後の動作を対応づけます。各 recipe は下の詳細セクションへリンクします。

Recipe 1 — 返品ラベルを作成する

| ステップ | あなたの操作 | Webhook（`action`） | 次の動作 | | ----- | ----------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 1 | `POST /api/ReturnShipment/createReturnShipment` | — | 同期レスポンスから `shipmentId` と `labelRequestStatusCode: queued` を読み取る。 | | 2（成功） | （待機） | `labelGenerated` | Webhook payload から `labelUrl` と `trackingNumber` を取り出し、ラベルを購入者へ届ける。突合には `shipmentId` を使い、`labelId` は使わない。 | | 2（失敗） | （待機） | `labelGenerated`、`labelRequestStatusCode: failed` 付き | `failReasons` と `errorMessages` を確認し、失敗を CS／オペレーションチームに通知する。 | 詳細フロー：[返品ラベルのリクエスト](#requesting-a-return-label)。

Recipe 2 — 倉庫到着イベントを受け取る

外向きの API 呼び出しは不要 — 倉庫からのイベント配信を待ちます。 | ステップ | Webhook（`action`） | 次の動作 | | ------------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 1 | `markShipmentArrive` | `shipmentId` で、先に作成した Return Shipment と突合する。 | | 2 | `newInventoryCreated` — 生成された Return Inventory ごとに 1 イベント（1 件の配送から複数生まれる場合あり） | 新しい `returnInventoryId` を、システム上の該当 shipment に紐付ける。 | | 3 | 倉庫が画像を追加・差し替えるたびに `changeLineItemImage` | その `returnInventoryId` の画像 URL リストキャッシュを更新する。 | | バリアント — Unknown Shipment | セラー作成の Return Shipment が無い状態で荷物が到着した場合、ステップ 1+2 の代わりに `assignUnknown` が配信される | 新規 Return Inventory として扱う。payload には `returnInventoryId`、`shipmentId`、`returnRequestId`、および割当前の画像が含まれている。 | 詳細フロー：[倉庫到着時の返品在庫(Return Inventory)](#return-inventory-at-warehouse-arrival)。

Recipe 3 — 処理指示を発行する

実行したい操作に対応する行を選んでください。操作ごとに API 呼び出しと待ち受ける Webhook が異なります。 | 操作 | API 呼び出し | Webhook（`action`） | 次の動作 | | ----------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------ | | Dispose / On-hold | `POST /api/ReturnInventory/UpdateReturnInventoryHandling`、dispose または on-hold handling code を指定 | `completeInventoryHandling` | 在庫はクローズ。以降の動作は不要。 | | Resend | `POST /api/Resend/createResend`、1 つ以上の `returnInventoryId` を参照 | `updateResendStatus` | resend の外向き配送を、購入者へ届くまで追跡する。 | | Recall | `POST /api/Recall/createRecallByReturnInventoryId`、最大 100 件の `returnInventoryId` | `recallUpdateStatus` | 香港集約倉庫に在庫が到着するまで配送を追跡する。 | | VAS | `POST /api/Vas/CreateByReturnInventoryId`、`returnInventoryId` と必要な VAS タイプを指定 | `vasUpdated`（VAS が在庫を分割する場合は `splitLineItem` も） | 在庫レコードを再読込する。VAS により分割が発生した場合、各分割品は固有の `returnInventoryId` と固有の RMA を持つ。 | 処理前に handling 指示を取り消す場合は、対応する操作のキャンセル端点（例：`POST /api/ReturnInventory/CancelReturnInventoryHandling`）を呼び出します。 詳細フロー：[処理指示](#handling-instructions)。 ***

返品ラベルのリクエスト

ラベルの作成は**非同期**です。フローは以下の通りです： 1. [**返品配送(Return Shipment)の作成**](/ja/api-reference/returnshipment/create-return-shipment)を呼び出して、返品配送(Return Shipment)レコードを作成し、ラベルリクエストをキューに入れます。 2. Return Helperがラベルを生成し、[**ラベル**通知イベント](/ja/webhooks#label-result)を通じてWebhook通知エンドポイントに結果を配信します。 ラベル結果を受信するには、Webhookエンドポイントを登録する必要があります。登録がない場合、生成されたラベルを取得する方法がありません。 ```mermaid theme={null} sequenceDiagram participant S as 販売者システム participant RH as Return Helper (RH) participant W as 販売者Webhookエンドポイント S->>RH: createReturnShipment(request) RH->>RH: リクエストを検証 alt 検証エラーなし RH-->>S: 200 OK（リクエストが正常に送信されました） RH->>RH: ラベル生成プロセスをキューに追加 RH->>W: POST /label-notification（結果ペイロード） Note over W: [ラベル生成成功]
ペイロードにlabelUrlが含まれます Note over W: [ラベル生成失敗]
ペイロードにfailReasons + errorMessagesが含まれます else 検証エラー RH-->>S: 4xx エラー（検証エラーメッセージ） end ``` ***

RMA（返品商品承認）

配送がReturn Helper倉庫に入ると、グローバルに一意なRMAが割り当てられます。Return Helperは、以下の2つの理由から、配送追跡番号の代わりにRMAを主要な通信識別子として使用しています： * 追跡番号はキャリア間で重複する場合があります。または同じキャリア内でも重複することがあります。 * VASによって荷物が分割された場合、各結果の荷物は独自のRMAを受け取ります。 **通常のRMAフォーマット：** ``` <倉庫プレフィックス>-<倉庫ID>--<環境文字><最大5桁のシーケンス>-<チェックデジット> ``` 例：`TWN-20-230101-D12345-36` **分割RMAフォーマット**（VAS分割後）： ``` <倉庫プレフィックス>-<倉庫ID>--<環境文字><最大5桁のシーケンス>-<分割シーケンス2桁>-<チェックデジット> ``` 例：`TWN-20-230101-D12345-01-36` ***

倉庫到着時の返品在庫(Return Inventory)

返品配送(Return Shipment)が倉庫に到着すると、受領済みとしてマークされ、1つ以上の\*\*返品在庫(Return Inventory)\*\*レコードに変換されます。各レコードには一意の`returnInventoryId`が付与されます。

タイプ1 — 販売者が開始した配送

1. 販売者がAPIを通じて配送を作成し、ラベルを提供しました。 2. 倉庫が受領済みとしてマーク → [**warehouseMarkShipmentArrivedV2**](/ja/webhooks#warehouse-shipment-arrived-v2) Webhookが送信され、続いて[**inventoryCreated**](/ja/webhooks#inventory-created)（`returnInventoryId`を含む）が送信されます。 3. 単一のラベルが複数の荷物をカバーしている場合、各荷物は同じ`shipmentId`と`returnRequestId`を共有する別々の返品在庫(Return Inventory)レコードになります。在庫ごとに1つの[**inventoryCreated**](/ja/webhooks#inventory-created)イベントが送信されます。 4. 在庫画像は次にアップロードされ、[**changeLineItemImage**](/ja/webhooks#image-updated)を通じて配信されます。

タイプ2 — 販売者に割り当てられた不明な配送

1. 販売者が作成したレコードなしに配送が到着しましたが、販売者のものとして識別されました。 2. [**assignUnknown**](/ja/webhooks#unknown-shipment-assigned) Webhookが送信され、返品在庫(Return Inventory)ペイロード、`returnInventoryId`、`shipmentId`、`returnRequestId`が含まれます。 3. 荷物に複数のアイテムが含まれている場合、複数の[**inventoryCreated**](/ja/webhooks#inventory-created)イベントが続く場合があります。 4. 割り当て前にキャプチャされた画像は[**assignUnknown**](/ja/webhooks#unknown-shipment-assigned)に含まれています；その後の変更は[**changeLineItemImage**](/ja/webhooks#image-updated)を通じて届きます。 ***

在庫画像

画像がアップロードされた（または画像リストが変更された）場合、[**changeLineItemImage**](/ja/webhooks#image-updated) Webhookが送信され、画像URLリストが含まれます。 ***

処理指示

返品在庫(Return Inventory)レコードが存在したら、倉庫にどのように処理するかを指示します：

廃棄(Dispose)

廃棄処理タイプで[**返品在庫(Return Inventory)処理の更新**](/ja/api-reference/returninventory/update-return-inventory-handling)を呼び出します。指示を取り消すには[**返品在庫(Return Inventory)処理のキャンセル**](/ja/api-reference/returninventory/cancel-return-inventory-handling)を使用します。

保留(Hold)

保留処理タイプで[**返品在庫(Return Inventory)処理の更新**](/ja/api-reference/returninventory/update-return-inventory-handling)を呼び出します。

再送(Resend)

1. `returnInventoryId`値のリストで[**再送の作成**](/ja/api-reference/resend/create-resend-order)を呼び出します。 2. [**resend**](/ja/webhooks#resend-status-update) Webhook通知を通じて再送追跡番号を受け取ります。 3. 再送が不要になった場合は[**再送のキャンセル**](/ja/api-reference/resend/cancel-resend-order)を呼び出します。

リコール

1. 最大100個の`returnInventoryId`値で[**返品在庫(Return Inventory)IDによるリコールの作成**](/ja/api-reference/recall/create-recall-by-return-inventory-ids)を呼び出します。 2. 追跡の更新と集荷ステータスの変更は[**recall**](/ja/webhooks#recall-status-update) Webhook通知を通じて配信されます。

付加価値サービス(VAS)

1. `returnInventoryId`と必要なVASタイプで[**VASの作成**](/ja/api-reference/vas/create-vas-by-return-inventory-id)を呼び出します。 2. 結果は[**UpdateVas**](/ja/webhooks#vas-update) Webhook通知を通じて配信されます。 ***

カスタムフィールド

カスタムフィールドを使用すると、返品に任意のキーと値のメタデータを付加できます。これらはReturn Helperによって保存されますが、処理はされません — 関連するWebhook通知でそのまま返されます。 * タイプ：`Dictionary` * 返品ごとに最大24個のカスタムフィールド。 ```json theme={null} { "customFieldMap": { "customerId": "buyer123", "dateOfPurchase": "2024-07-01" } } ``` カスタムフィールドは[**返品配送(Return Shipment)の作成**](/ja/api-reference/returnshipment/create-return-shipment)で使用可能で、[**warehouseMarkShipmentArrivedV2**](/ja/webhooks#warehouse-shipment-arrived-v2)通知でそのまま返されます。 ***

FBA（フルフィルメント by Amazon）返品

顧客はFBA商品をReturn Helper倉庫に送って処理（再入荷、補充、リコール、廃棄など）を受けることができます。 **一般的なFBAワークフロー：** 1. [**FBA配送の作成**](/ja/api-reference/fbashipment/create-fba-shipment)を呼び出してReturn Helperに通知し、商品を倉庫に送ります。 2. 配送が受け取られ、`fnsku`と`quantity`でFBA在庫として保管され、Webhookを通じて配信されます。 3. [**FNA倉庫在庫リストの取得**](/ja/api-reference/fbawarehouseinventory/get-fba-warehouse-inventory-list-by-fnsku)で既存のFBA在庫を確認します。 4. [**FBA指示の作成**](/ja/api-reference/fbainstruction/create-fba-instructions)を通じて指示を作成します（補充には現在APIで提供されていない追加の配送情報が必要です）。 5. Return Helperが指示を処理し、Webhookを通じて結果を通知します。 6. 関連するFBA指示詳細取得エンドポイント（リコール、廃棄、再入荷、その他）を通じて指示ステータスを確認します。 **歴史的なFBAデータの取得**（APIに移行している既存ポータルユーザー向け）： 1. [**FBA配送の一覧**](/ja/api-reference/fbashipment/list-fba-shipments-with-pagination)を使用して日付範囲内の過去の配送を取得し、`fbaShipmentId`値を収集します。 2. [**FBA配送アイテムリストの取得**](/ja/api-reference/fbashipmentitem/get-items-in-fba-shipment)を呼び出して、配送ごとのアイテム、FNSKU、数量を取得します。 3. FNSKUで[**FBA倉庫在庫リストの取得**](/ja/api-reference/fbawarehouseinventory/get-fba-warehouse-inventory-list-by-fnsku)を使用して現在の在庫を確認します。 4. [**FBA指示の一覧**](/ja/api-reference/fbainstruction/list-fba-instructions-with-pagination)を使用して過去の指示を検索します。 5. 指示ごとに[**FBA指示アイテムリストの取得**](/ja/api-reference/fbainstructionitem/get-items-in-fba-instruction)を使用してラインアイテムの詳細を取得します。 歴史的なデータを取得したら、履歴データをポーリングし続けるのではなく、定期的なAPI呼び出しとWebhookイベントに依存してください。 ***

歴史的なデータの取得

このセクションは、APIに移行している既存のReturn Helper Portalユーザー向けです。ゼロから連携している場合、必要なすべてのデータは通常のAPI呼び出しとWebhookイベントを通じて交換されます — 歴史的なデータを取得する必要はありません。 **歴史的な返品配送(Return Shipment)データの取得：** [**配送の一覧**](/ja/api-reference/shipment/list-shipments-with-pagination)を使用して、日付範囲内の過去の返品配送(Return Shipment)を取得します。 **歴史的な返品在庫(Return Inventory)データの取得：** [**返品在庫(Return Inventory)の一覧**](/ja/api-reference/returninventory/list-return-inventories-with-pagination)を使用して、日付範囲内の過去の返品在庫(Return Inventory)レコードを取得します。 FBAの歴史的なデータについては、上記の**歴史的なFBAデータの取得**セクションを参照してください。 すべての歴史的なデータを取得したら、履歴データを継続的にポーリングするのではなく、定期的なAPI呼び出しとWebhookイベントに依存してください。 ***

レスポンス構造

すべてのAPIレスポンスには、結果ステータスを示す`meta`オブジェクトが含まれています。 **成功レスポンス（`status: 200`）：** ```json theme={null} { "apiBalances": [ { "apiBalanceId": 7, "currencyCode": "usd", "balance": 2044.233 } ], "correlationId": "0HM9VIKSKH2CB:00000002", "meta": { "status": 200, "data": {}, "errorCode": null, "error": {} }, "totalNumberOfRecords": 1 } ``` **失敗レスポンス（例：無効な`warehouseId`）：** ```json theme={null} { "correlationId": "0HM9VIKSKH2CF:00000002", "meta": { "status": 400, "data": {}, "errorCode": "VALIDATION_FAILED", "error": { "warehouseId": "The value 'invalid' is not valid." } } } ``` `200`以外の`status`値は、リクエストが正常に完了しなかったことを意味します。`errorCode`と`error`フィールドが詳細を提供します。