はじめに

​

連携を始める前に

​

担当範囲

​

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

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 を参照。
3. Webhook 受信側の構築。 HTTPS エンドポイントを立ち上げ、生 POST body を解析し、signing key で returnhelper-signature ヘッダーを検証し、notificationId で重複を除去し、200 OK を速やかに返します。サンプルコードは Webhooks → Signature Verification にあります。
4. エンドポイントを当社に登録。 エンドポイントが公開ネットワークから到達可能になったら、Webhook Setup Request Form を提出します。接続作業は当社で行います — 現時点ではセルフサーブ登録 API はありません。
5. Sandbox でエンドツーエンド検証。 本ガイドの残りの章に沿って、ラベル作成、倉庫到着、到着後処理のフローを実行し、対応する webhook イベントが受信側に届くことを確認します。
6. 本番稼働申請。 Sandbox テスト完了後、support に連絡して認証情報と登録済みエンドポイントを本番環境へ切り替えます。

​

返品フローの概要

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

​

エンドツーエンド Recipes

​

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

​

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

​

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

​

返品ラベルのリクエスト

1. 返品配送(Return Shipment)の作成を呼び出して、返品配送(Return Shipment)レコードを作成し、ラベルリクエストをキューに入れます。
2. Return Helperがラベルを生成し、ラベル通知イベントを通じてWebhook通知エンドポイントに結果を配信します。

​

RMA（返品商品承認）

• 追跡番号はキャリア間で重複する場合があります。または同じキャリア内でも重複することがあります。
• VASによって荷物が分割された場合、各結果の荷物は独自のRMAを受け取ります。

<倉庫プレフィックス>-<倉庫ID>-<YYMMDD>-<環境文字><最大5桁のシーケンス>-<チェックデジット>

<倉庫プレフィックス>-<倉庫ID>-<YYMMDD>-<環境文字><最大5桁のシーケンス>-<分割シーケンス2桁>-<チェックデジット>

​

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

​

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

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

​

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

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

​

在庫画像

​

処理指示

​

廃棄(Dispose)

​

保留(Hold)

​

再送(Resend)

1. returnInventoryId値のリストで再送の作成を呼び出します。
2. resend Webhook通知を通じて再送追跡番号を受け取ります。
3. 再送が不要になった場合は再送のキャンセルを呼び出します。

​

リコール

1. 最大100個のreturnInventoryId値で返品在庫(Return Inventory)IDによるリコールの作成を呼び出します。
2. 追跡の更新と集荷ステータスの変更はrecall Webhook通知を通じて配信されます。

​

付加価値サービス(VAS)

1. returnInventoryIdと必要なVASタイプでVASの作成を呼び出します。
2. 結果はUpdateVas Webhook通知を通じて配信されます。

​

カスタムフィールド

• タイプ：Dictionary<string, string>
• 返品ごとに最大24個のカスタムフィールド。

{
  "customFieldMap": {
    "customerId": "buyer123",
    "dateOfPurchase": "2024-07-01"
  }
}

​

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

1. FBA配送の作成を呼び出してReturn Helperに通知し、商品を倉庫に送ります。
2. 配送が受け取られ、fnskuとquantityでFBA在庫として保管され、Webhookを通じて配信されます。
3. FNA倉庫在庫リストの取得で既存のFBA在庫を確認します。
4. FBA指示の作成を通じて指示を作成します（補充には現在APIで提供されていない追加の配送情報が必要です）。
5. Return Helperが指示を処理し、Webhookを通じて結果を通知します。
6. 関連するFBA指示詳細取得エンドポイント（リコール、廃棄、再入荷、その他）を通じて指示ステータスを確認します。

1. FBA配送の一覧を使用して日付範囲内の過去の配送を取得し、fbaShipmentId値を収集します。
2. FBA配送アイテムリストの取得を呼び出して、配送ごとのアイテム、FNSKU、数量を取得します。
3. FNSKUでFBA倉庫在庫リストの取得を使用して現在の在庫を確認します。
4. FBA指示の一覧を使用して過去の指示を検索します。
5. 指示ごとにFBA指示アイテムリストの取得を使用してラインアイテムの詳細を取得します。

​

歴史的なデータの取得

​

レスポンス構造

{
  "apiBalances": [
    {
      "apiBalanceId": 7,
      "currencyCode": "usd",
      "balance": 2044.233
    }
  ],
  "correlationId": "0HM9VIKSKH2CB:00000002",
  "meta": {
    "status": 200,
    "data": {},
    "errorCode": null,
    "error": {}
  },
  "totalNumberOfRecords": 1
}

{
  "correlationId": "0HM9VIKSKH2CF:00000002",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "warehouseId": "The value 'invalid' is not valid."
    }
  }
}