はじめに

​

前提条件

1. API認証情報 — 認証セクションを参照してください。
2. Return Helperからの非同期イベントを受信するためのWebhook通知エンドポイント。通知エンドポイントが提供されていない場合、ラベル結果や倉庫イベントを受信できません。
3. このガイドを読み、主な返品フローを理解してください。

​

返品フローの概要

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

​

返品ラベルのリクエスト

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."
    }
  }
}