> ## 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.

# Webhookと通知

> Return Helperからの非同期イベント通知の受信

<Warning>
  このページはAIによって自動翻訳されています。不明点や相違がある場合は、英語版を正式版として参照してください。
</Warning>

<h2 id="overview">
  概要
</h2>

Webhookは、Return Helperシステムでイベントが発生した際に非同期通知を配信します — たとえば、ラベルが生成されたときや、配送が倉庫に到着したときなど。これらのPOSTリクエストを受信するために、サーバーはHTTPSエンドポイントを公開する必要があります。

<h2 id="setting-up-your-webhook-endpoint">
  Webhookエンドポイントの設定
</h2>

<h3 id="endpoint-requirements">
  エンドポイントの要件
</h3>

セットアップリクエストを送信する前に、エンドポイントが以下の要件を満たしていることを確認してください：

* **公開アクセス可能** — URLはインターネットから到達可能でなければなりません（VPN、localhost、または内部専用アドレスは不可）
* **HTTPS** — エンドポイントは有効なTLS証明書を持つHTTPSで提供される必要があります
* **HTTP POST** — エンドポイントは`application/json`ボディを持つ`POST`リクエストを受け入れる必要があります
* **HTTP 200を返す** — サーバーはリクエストを受信した直後に`200 OK`ステータスを返す必要があります；その他のステータスコードやタイムアウトは配信失敗として処理されます
* **高速レスポンス** — 必要に応じてイベントを非同期で処理します；配信タイムアウトを避けるため、レスポンス前に重い処理を行わないでください

<h3 id="registering-your-endpoint">
  エンドポイントの登録
</h3>

Webhookエンドポイントを登録するには、[Webhookセットアップリクエストフォーム](https://forms.gle/iBVkRZvfLQ8o1Nqg8)にご記入ください。フォームにはセットアップを迅速に完了するために必要なすべての情報が含まれており、エンドポイントを有効にする最も速い方法です。

<Note>
  上記のフォームを使用することをお勧めします。これにより、必要なすべての詳細が一度に取得されます。フォームを使用できない場合は、メールでリクエストを送信することもできます — 以下のテンプレートを参照してください。
</Note>

<Accordion title="メールテンプレート（フォームを使用できない場合）">
  メールで連絡する場合は、[support@returnhelper.com](mailto:support@returnhelper.com)に以下を送信してください：

  ```
  Subject: Request webhook setup in Return Helper - <YOUR CLIENT CODE>

  To: support@returnhelper.com

  Dear Support Team,

  We would like to request webhook setup in Return Helper. Please find the details below:

  Email address: <YOUR EMAIL ADDRESS>
  Client code:   <YOUR CLIENT CODE>
  Endpoint:      https://your-server.example.com/webhook
  Environment:   <Sandbox / Production / Both>
  Comments:      <Any additional information, or leave blank>
  ```
</Accordion>

<h2 id="event-delivery">
  イベント配信
</h2>

**タイミング** — イベントはトリガーアクションの数秒後に届く場合があり、まれに数分後になることがあります。

**重複イベント** — エンドポイントが同じイベントを複数回受信する場合があります。処理済みの `notificationId` を追跡して重複を排除してください。`notificationId` はイベントごとに一意で、すべてのウェブフック通知に含まれるため、それ単体で安定した冪等キーとして使用できます。

**イベントの順序** — 配信順序は保証されていません。任意の順序でイベントを処理できるようにハンドラーを設計してください。たとえば、`inventoryCreated`が`warehouseMarkShipmentArrivedV2`より前に届く場合があります。順序外で受信したイベントで参照されているオブジェクトを取得するには、APIを使用してください。

各イベントにはISO 8601形式の`eventTime`フィールドが含まれています。

<h2 id="notification-headers">
  通知ヘッダー
</h2>

すべてのWebhookリクエストには以下のヘッダーが含まれています：

| ヘッダー                        | タイプ    | 説明                                                                                                   |
| --------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `RETURNHELPER-TRIGGERED-AT` | string | ISO 8601 形式の UTC タイムスタンプ（例：`2026-08-14T09:31:02.1234567Z`）。[署名の検証](#signature-verification)で使用する値です。 |
| `RETURNHELPER-API-ID`       | string | 通知が属するアカウントの `apiId`。ご自身の値は[API アカウント情報を取得](/ja/api-reference/account/get-api-info)で確認できます。          |
| `RETURNHELPER-API-NAME`     | string | そのアカウントの `apiName`。                                                                                  |
| `ReturnHelper-Signature`    | string | 検証用 HMAC-SHA256 署名——[署名の検証](#signature-verification)を参照してください。                                       |

<h3 id="legacy-headers">
  旧ヘッダー
</h3>

以下のヘッダーは引き続きすべての通知で送信され、削除される予定はありません。新規の連携では上表のヘッダーを読み取ってください。

| 旧ヘッダー                    | 置き換え先                                          |
| ------------------------ | ---------------------------------------------- |
| `Timestamp`              | `RETURNHELPER-TRIGGERED-AT` — 文字列として完全に同一の値です。 |
| `x-returnhelper-apiname` | `RETURNHELPER-API-NAME` — 同じ値です。               |

<Note>
  HTTP ヘッダー名は大文字・小文字を区別せず、フレームワークによっては正規化されます。上表は Return Helper が実際に送信する表記です。受信ヘッダー名が小文字化されるフレームワークをお使いの場合は、大文字・小文字を区別せずに照合してください。
</Note>

<h2 id="signature-verification">
  署名の検証
</h2>

<Warning>
  ペイロードを処理する前に必ず署名を検証してください。**生のリクエストボディ**を使用してください — フレームワークによるJSONの再シリアライズなどの変換は検証の失敗を引き起こします。
</Warning>

署名キーはReturn Helperから提供されます（Base64エンコードされています）。安全に保管し、公開しないでください。API キーおよびトークンと同じ画面（ユーザーポータル）で確認できます——[認証](/ja/introduction#authentication) のスクリーンショットを参照してください。また、[Signing Key を取得](/ja/api-reference/apiaccount/get-signing-key)でプログラムから読み取ることもできます。

<h3 id="worked-example">
  詳細な例
</h3>

以下の受信リクエストがあるとします：

**ヘッダー：**

```json theme={null}
{
  "content-type": "application/json; charset=utf-8",
  "ReturnHelper-Signature": "gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=",
  "RETURNHELPER-TRIGGERED-AT": "2024-01-12T09:23:08.4863561Z",
  "RETURNHELPER-API-ID": "12345",
  "RETURNHELPER-API-NAME": "Acme Returns",
  "Timestamp": "2024-01-12T09:23:08.4863561Z"
}
```

**ボディ（生のJSON、再シリアライズしてはいけません）：**

```
{"label":{"regions":{"RHCN":"https://label.returnhelperchina.com/label/202401/10595-S240112-0000001-pqk2pvydgxp.pdf"},"labelId":31033,"shipmentId":30385,"apiId":33,"refKey":"S240112-0000001","labelRequestStatusCode":"success","serviceType":"RETURN_ENDICIA_USPS_GROUND_ADVANTAGE_NJ","trackingNumber":"9434611899562082901137","labelUrl":"https://label-service-dev-files.returnshelper.com/label/202401/10595-S240112-0000001-pqk2pvydgxp.pdf","error":null,"qrcodeUrl":null,"qrcodeError":null,"correlationId":null,"cancelCutoffTime":"2024-02-11T09:21:24.0795","meta":null},"category":"labelGenerated","action":"labelGenerated","eventTime":"2024-01-12T09:23:08.4862743Z"}
```

<h3 id="step-by-step-verification">
  ステップバイステップの検証
</h3>

**ステップ1 — `ReturnHelper-Signature` ヘッダーから署名を抽出する**（最後の比較用）：

```
gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=
```

**ステップ2 — `RETURNHELPER-TRIGGERED-AT` ヘッダーからタイムスタンプを抽出する**：

```
2024-01-12T09:23:08.4863561Z
```

**ステップ3 — `string_to_sign`を構築する**

以下の4つの値を順番に連結します（区切り文字なし）：

1. HTTPメソッド：`POST`
2. 通知エンドポイントURL：`https://s2024-01-12.free.beeceptor.com`
3. ステップ2で取得した `RETURNHELPER-TRIGGERED-AT` の値
4. 生のJSONボディ

結果として連結された文字列：

```
POSThttps://s2024-01-12.free.beeceptor.com2024-01-12T09:23:08.4863561Z{"label":{"regions":...},...}
```

次に、連結された文字列全体を**Base64エンコード**します。結果が`string_to_sign`です：

```
UE9TVGh0dHBzOi8vczIwMjQtMDEtMTIuZnJlZS5iZWVjZXB0b3IuY29tMjAyNC0wMS0xMlQwOToyMzowOC40ODYzNTYxWnvigJxsYWJlbOKAnTp74oCccmVnaW9uc+KAnTp74oCcUkhDTuKAnTrigJxodHRwczovL2xhYmVsLnJldHVybmhlbHBlcmNoaW5hLmNvbS9sYWJlbC8yMDI0MDEvMTA1OTUtUzI0MDExMi0wMDAwMDAxLXBxazJwdnlkZ3hwLnBkZuKAnX0s4oCcbGFiZWxJZOKAnTozMTAzMyzigJxzaGlwbWVudElk4oCdOjMwMzg1LOKAnGFwaUlk4oCdOjMzLOKAnHJlZktleeKAnTrigJxTMjQwMTEyLTAwMDAwMDHigJ0s4oCcbGFiZWxSZXF1ZXN0SWTigJ06MTA1OTUs4oCcbGFiZWxSZXF1ZXN0U3RhdHVzQ29kZeKAnTrigJxzdWNjZXNz4oCdLOKAnHNlcnZpY2VUeXBl4oCdOuKAnFJFVFVSTl9FTkRJQ0lBX1VTUFNfR1JPVU5EX0FEVkFOVEFHRV9OSuKAnSzigJx0cmFja2luZ051bWJlcuKAnTrigJw5NDM0NjExODk5NTYyMDgyOTAxMTM3IizigJxsYWJlbFVybOKAnTrigJxodHRwczovL2xhYmVsLXNlcnZpY2UtZGV2LWZpbGVzLnJldHVybnNoZWxwZXIuY29tL2xhYmVsLzIwMjQwMS8xMDU5NS1TMjQwMTEyLTAwMDAwMDEtcHFrMnB2eWRneHAucGRm4oCdLOKAnGVycm9y4oCdOm51bGws4oCccXJjb2RlVXJs4oCdOm51bGws4oCccXJjb2RlRXJyb3LigJ06bnVsbCzigJxjb3JyZWxhdGlvbklk4oCdOm51bGws4oCcY2FuY2VsQ3V0b2ZmVGltZeKAnTrigJwyMDI0LTAyLTExVDA5OjIxOjI0LjA3OTUiLOKAnG1ldGHigJ06bnVsbH0s4oCcY2F0ZWdvcnnigJ064oCcbGFiZWxHZW5lcmF0ZWTigJ0s4oCcYWN0aW9u4oCdOuKAnGxhYmVsR2VuZXJhdGVk4oCdLOKAnGV2ZW50VGltZeKAnTrigJwyMDI0LTAxLTEyVDA5OjIzOjA4LjQ4NjI3NDNa4oCdfQ==
```

**ステップ4 — HMAC-SHA256署名を計算する**

サンプルの署名キーを使用します（実際のキーは異なります）：

```
PEnA0mzKb7fUlGfMgCGhXPjPmPGvW70UU8bkNKdG78WDrQRwzFa572e2JsFIE1e4PLaP9h/ZEvERSR0FBDYNlQ==
```

操作：

1. `string_to_sign`（ステップ3）をBase64からバイト配列にデコードする
2. 署名キーをBase64からバイト配列にデコードする
3. 署名キーバイトを使用して`string_to_sign`バイトに対してHMAC-SHA256を計算する → 署名バイト配列
4. 署名バイト配列をBase64エンコードする

期待される結果：

```
gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=
```

**ステップ5 — 署名の比較**

ステップ4で計算した署名とステップ1で抽出した署名を比較します。タイミング攻撃を防ぐため、**定数時間文字列比較**を使用してください。

**追加のセキュリティ：** `eventTime`がシステムクロックと15分以上異なるイベントを拒否してください（リプレイ攻撃保護）。

<h3 id="sample-code">
  サンプルコード
</h3>

<CodeGroup>
  ```java Java theme={null}
  // Required imports (add at the top of your file):
  //   import java.security.InvalidKeyException;
  //   import java.security.NoSuchAlgorithmException;
  //   import javax.crypto.Mac;
  //   import javax.crypto.spec.SecretKeySpec;
  //   import org.apache.commons.codec.binary.Base64;

  class Main {
    private static final String CHARACTER_ENCODING = "UTF-8";
    final static String ALGORITHM = "HmacSHA256";

    public static void main(String[] args) throws Exception {
      String payload   = "<body JSON string>";
      String action    = "<action>";           // always "POST"
      String url       = "<url>";              // your notification endpoint
      String timestamp = "<timestamp>";        // from RETURNHELPER-TRIGGERED-AT header

      String data = new String(
        Base64.encodeBase64((action + url + timestamp + payload).getBytes(CHARACTER_ENCODING))
      );

      String base64Key  = "<signing key>";
      String signature  = sign(data, base64Key);
      System.out.println(signature);
    }

    private static String sign(String data, String secretKey)
        throws NoSuchAlgorithmException, InvalidKeyException {
      Mac mac = Mac.getInstance(ALGORITHM);
      mac.init(new SecretKeySpec(Base64.decodeBase64(secretKey), ALGORITHM));
      byte[] signature = mac.doFinal(Base64.decodeBase64(data));
      return new String(Base64.encodeBase64(signature), CHARACTER_ENCODING);
    }
  }
  ```

  ```javascript Node.js theme={null}
  // Node.js built-in module. Import at the top of your file:
  //   import * as crypto from 'node:crypto';   // ESM
  //   const crypto = require('node:crypto');   // CommonJS

  function sign(data, secretKey) {
    const key        = Buffer.from(secretKey, 'base64');
    const hmac       = crypto.createHmac('sha256', key);
    const dataBuffer = Buffer.from(data, 'base64');
    hmac.update(dataBuffer);
    return hmac.digest('base64');
  }

  async function main() {
    const payload   = '<body JSON string>'; // raw request body
    const action    = '<action>';           // always "POST"
    const url       = '<url>';              // your notification endpoint
    const timestamp = '<timestamp>';        // from RETURNHELPER-TRIGGERED-AT header

    const encodedData = Buffer.from(action + url + timestamp + payload).toString('base64');
    const base64Key   = '<signing key>';
    const signature   = sign(encodedData, base64Key);

    console.log('Signature:', signature);
  }

  main().catch(console.error);
  ```

  ```typescript TypeScript theme={null}
  // Node.js built-in module. Import at the top of your file:
  //   import * as crypto from 'node:crypto';

  function sign(data: string, secretKey: string): string {
    const key         = Buffer.from(secretKey, 'base64');
    const hmac        = crypto.createHmac('sha256', key);
    const decodedData = Buffer.from(data, 'base64');
    hmac.update(decodedData);
    return hmac.digest('base64');
  }

  function main() {
    const payload   = '<body JSON string>'; // raw request body
    const action    = '<action>';           // always "POST"
    const url       = '<url>';              // your notification endpoint
    const timestamp = '<timestamp>';        // from RETURNHELPER-TRIGGERED-AT header

    const encodedData = Buffer.from(action + url + timestamp + payload, 'utf-8').toString('base64');
    const base64Key   = '<signing key>';
    const signature   = sign(encodedData, base64Key);

    console.log(signature);
  }

  main();
  ```

  ```apex Apex (Salesforce) theme={null}
  public class Main {
      private static final String ALGORITHM = 'HmacSHA256';

      public static void main() {
          String payload   = '<body JSON string>'; // raw request body
          String action    = '<action>';            // always 'POST'
          String url       = '<url>';               // your notification endpoint
          String timestamp = '<timestamp>';         // from RETURNHELPER-TRIGGERED-AT header

          Blob data        = EncodingUtil.base64Encode(
                                 Blob.valueOf(action + url + timestamp + payload));
          String base64Key = '<signing key>';
          String signature = sign(data, base64Key);
          System.debug(signature);
      }

      private static String sign(Blob data, String secretKey) {
          Blob macKey   = EncodingUtil.base64Decode(secretKey);
          Blob sigBytes = Crypto.generateMac(ALGORITHM, data, macKey);
          return EncodingUtil.base64Encode(sigBytes);
      }
  }
  ```
</CodeGroup>

<h2 id="retry-mechanism">
  再試行メカニズム
</h2>

受信を確認するために`2xx` HTTPステータスコードで応答してください。2xx以外のレスポンスは再試行をトリガーします。10回連続して失敗した後、エンドポイントへの通知配信は24時間停止されます。

<h2 id="common-body-fields">
  共通ボディフィールド
</h2>

すべての通知ボディはこれらのトップレベルフィールドを共有しています：

| フィールド            | タイプ    | 説明                            |
| ---------------- | ------ | ----------------------------- |
| `category`       | string | 通知カテゴリ（以下の表を参照）               |
| `action`         | string | 特定のイベントアクション                  |
| `eventTime`      | string | イベントのISO 8601タイムスタンプ          |
| `version`        | string | 通知スキーマバージョン                   |
| `notificationId` | string | すべての通知に含まれます。冪等キーとして使用してください。 |

***

<h2 id="notification-event-reference">
  通知イベントリファレンス
</h2>

| 通知                                                | `category`                                   | `action`                                     | 説明                              |
| ------------------------------------------------- | -------------------------------------------- | -------------------------------------------- | ------------------------------- |
| [ラベル結果](#label-result)                            | `labelGenerated`                             | `labelGenerated`                             | ラベル生成結果（成功または失敗）                |
| [倉庫配送到着（v2）](#warehouse-shipment-arrived-v2)      | `rsl`                                        | `markShipmentArrive`                         | 倉庫での配送受領（現在のバージョン）              |
| [在庫作成済み](#inventory-created)                      | `newInventoryCreated`                        | `newInventoryCreated`                        | 新しい返品在庫(Return Inventory)が作成された |
| [画像更新済み](#image-updated)                          | `rrli`                                       | `changeLineItemImage`                        | ラインアイテム画像が追加、変更、または削除された        |
| [不明な配送が割り当てられた](#unknown-shipment-assigned)       | `rsl`                                        | `assignUnknown`                              | 不明な配送が販売者に割り当てられた               |
| [リコールステータス更新](#recall-status-update)              | `recall`                                     | `recallUpdateStatus`                         | リコール追跡または集荷ステータスが変更された          |
| [再送ステータス更新](#resend-status-update)                | `resend`                                     | `updateResendStatus`                         | 再送追跡またはステータスが変更された              |
| [VAS更新](#vas-update)                              | `rrliv`                                      | `vasUpdated`                                 | 付加価値サービス(VAS)が完了または更新された        |
| [在庫処理完了](#inventory-handling-complete)            | `rinv`                                       | `completeInventoryHandling`                  | 処理指示が完了した                       |
| [在庫再校正済み](#inventory-recalibrated)                | `completeRecalibrate`                        | `completeRecalibrate`                        | 倉庫が在庫の寸法/重量を更新した                |
| [在庫メタデータ更新済み](#inventory-meta-updated)            | `updateReturnInventoryMeta`                  | `updateReturnInventoryMeta`                  | 倉庫またはユーザーがメタデータを追加/更新した         |
| [RMA更新済み](#rma-updated)                           | `notifyUserRmaSwapped`                       | `notifyUserRmaSwapped`                       | 倉庫がRMAの割り当てを修正した                |
| [SKU更新済み](#sku-updated)                           | `userUpdateReturnInventorySku`               | `userUpdateReturnInventorySku`               | 販売者が在庫のSKUを更新した                 |
| [ラインアイテム分割](#split-line-item)                     | `lineItemVasReturnInventoryLineItem`         | `splitLineItem`                              | VASが荷物を複数の在庫に分割した               |
| [倉庫備考更新済み](#warehouse-remarks-updated)            | `warehouseUpdateWarehouseRemarks`            | `warehouseUpdateWarehouseRemarks`            | 倉庫が返品リクエストの備考を更新した              |
| [購入者返品ラベル生成済み](#buyer-return-label-generated)     | `buyerReturnRrLabel`                         | `buyerReturnLabelGenerated`                  | ブランド返品ポータルのラベルが購入者向けに生成された      |
| [Shopify購入者返品作成済み](#shopify-buyer-return-created) | `shopifyBuyerCreateReturn`                   | `shopifyBuyerCreateReturn`                   | 購入者がShopify連携を通じて返品を作成した        |
| [統合配送コスト更新済み](#consolidate-shipping-cost-updated) | `consolidateShippingOrderShippingFeeUpdated` | `consolidateShippingOrderShippingFeeUpdated` | 統合配送注文のコストが更新された                |
| [統合配送すべて梱包済み](#consolidate-shipping-all-packed)   | `consolidateShippingOrderInventoryAllPacked` | `consolidateShippingOrderInventoryAllPacked` | 統合注文のすべての在庫が梱包された               |
| [統合配送発送済み](#consolidate-shipment-sent)            | `consolidateShippingShipmentSent`            | `consolidateShippingShipmentSent`            | 統合配送がキャリアに発送された                 |
| [統合配送AWB更新済み](#consolidate-shipping-awb-updated)  | `consolidateShippingShipmentShipped`         | `consolidateShippingShipmentShipped`         | 統合配送のAWBが更新された                  |
| [統合注文完了](#consolidate-order-completed)            | `consolidateShippingOrderCompleted`          | `consolidateShippingOrderCompleted`          | 統合注文のすべての配送が発送された               |
| [統合注文キャンセル](#consolidate-order-cancelled)         | `consolidateShippingOrderCancelled`          | `consolidateShippingOrderCancelled`          | 統合注文が倉庫によって強制キャンセルされた           |

***

<h2 id="notification-payloads">
  通知ペイロード
</h2>

<h3 id="label-result">
  ラベル結果
</h3>

返品ラベルリクエストが完了したとき（成功または失敗）に送信されます。

<Warning>
  ラベルをシステム内の配送にマッチさせるには必ず`shipmentId`を使用してください — **`labelId`を使用しないでください**。まれにキャリアの障害により、同じ`shipmentId`に対して新しいラベル（新しい`labelId`）が発行されることがあります。
</Warning>

`category: labelGenerated` / `action: labelGenerated`

`label`の主要フィールド：

| フィールド                    | 説明                              |
| ------------------------ | ------------------------------- |
| `labelId`                | ラベル識別子（マッチングには使用しない — 上記の警告を参照） |
| `shipmentId`             | 配送識別子（マッチングにこれを使用する）            |
| `apiId`                  | 販売者API ID                       |
| `refKey`                 | 配送参照キー                          |
| `labelRequestStatusCode` | `"success"`または`"fail"`          |
| `serviceType`            | 使用されたキャリアサービスタイプ                |
| `trackingNumber`         | キャリア追跡番号（成功時）                   |
| `labelUrl`               | ラベルPDFのダウンロードURL（成功時）           |
| `error`                  | エラーメッセージ（失敗時）                   |
| `qrcodeUrl`              | QRコードURL（該当する場合）                |
| `qrcodeError`            | QRコードエラー（該当する場合）                |
| `shipmentInstruction`    | 配送指示                            |
| `correlationId`          | リクエストトレース用の相関ID                 |
| `cancelCutoffTime`       | このラベルをキャンセルする期限                 |
| `meta`                   | 追加のメタデータ                        |
| `regions`                | 地域コードから地域ラベルURLへのマップ            |

**成功例：**

```json theme={null}
{
  "label": {
    "labelId": 11345,
    "shipmentId": 10825,
    "apiId": 21,
    "refKey": "S210904-0000202",
    "labelRequestStatusCode": "success",
    "serviceType": "usps",
    "trackingNumber": "9201994884299101443342",
    "labelUrl": "https://example.com/label.pdf",
    "qrcodeUrl": "https://example.com/qrcode.png",
    "qrcodeError": null,
    "error": null,
    "correlationId": null,
    "meta": null
  },
  "category": "labelGenerated",
  "action": "labelGenerated",
  "eventTime": "2021-09-04T17:03:15.8888073Z"
}
```

**失敗例：**

```json theme={null}
{
  "label": {
    "labelId": 11352,
    "shipmentId": 10833,
    "apiId": 21,
    "refKey": "S210906-0000085",
    "labelRequestStatusCode": "fail",
    "serviceType": "ap",
    "trackingNumber": null,
    "labelUrl": null,
    "error": "Your combination of suburb, state & postcode doesn't match.",
    "qrcodeUrl": null,
    "qrcodeError": null
  },
  "category": "labelGenerated",
  "action": "labelGenerated",
  "eventTime": "2021-09-06T08:16:33.4674332Z"
}
```

***

<h3 id="warehouse-shipment-arrived-v2">
  倉庫配送到着（v2）
</h3>

倉庫が配送を受領済みとしてマークしたときに送信されます。常に1つ以上の[在庫作成済み](#inventory-created)イベントが続きます。

<Note>
  このイベントは `sellerReferenceNumber` を返却し、お客様の注文レコードと Return Helper の識別子との主要な突合ポイントとなります。デフォルトの V202207 は 3 つのレイヤーすべての SRN を 1 つのバンドルペイロードで運びます。V202407 は Shipment レイヤーの SRN のみを運びます。完全な突合ワークフローとバージョンの差異については [Seller Reference Number](/ja/reference/seller-reference-number) を参照してください。
</Note>

`category: rsl` / `action: markShipmentArrive` / `version: 202407`

`shipment`の主要フィールド：

| フィールド                   | 説明                |
| ----------------------- | ----------------- |
| `shipmentId`            | 一意の配送識別子          |
| `returnRequestId`       | リンクされた返品リクエスト     |
| `trackingNumber`        | キャリア追跡番号          |
| `sellerReferenceNumber` | あなたの参照番号          |
| `serviceType`           | 使用された配送サービス       |
| `customFieldMap`        | 元の配送からのカスタムフィールド  |
| `shipToWarehouseId`     | 受領倉庫              |
| `receiveDate`           | ISO 8601受領タイムスタンプ |

```json theme={null}
{
  "shipment": {
    "shipmentId": "35732",
    "sellerReferenceNumber": "R240725-0000003",
    "returnRequestId": "66848",
    "trackingNumber": "TRACK123456",
    "referenceNumber": "R240725-0000003",
    "serviceType": "fedex",
    "customFieldMap": {
      "customerId": "buyer123"
    },
    "shipToWarehouseId": 2,
    "receiveDate": "2024-07-25T08:53:05.7827073Z"
  },
  "category": "rsl",
  "action": "markShipmentArrive",
  "eventTime": "2024-07-29T05:48:21.381658Z",
  "version": "202407"
}
```

***

<h3 id="inventory-created">
  在庫作成済み
</h3>

配送が受領された後（またはVAS分割が発生した後）、新しい返品在庫(Return Inventory)レコードが作成されたことを通知するために送信されます。在庫アイテムごとに1つのイベントが送信されます — 同じラベルの下で複数の荷物が受領された場合、1つの配送で複数のイベントが生成される場合があります。

<Note>
  **このペイロードには `sellerReferenceNumber` が含まれません。** `returnInventory` と `shipment` のいずれも `sellerReferenceNumber` を運びません。存在するのは `shipment.referenceNumber` のみで、このフィールドはお客様が指定した `orderNumber` を返却するだけで、SRN ではありません。`sellerReferenceNumber` に基づいて在庫を自社レコードと突合する場合、**`newInventoryCreated` 単独の購読は避けてください**。[Warehouse Shipment Arrived](#warehouse-shipment-arrived-v2)（V202207 では 3 レイヤーすべての SRN を運びます）または [Inventory Handling Complete](#inventory-handling-complete)（`returnInventory.sellerReferenceNumber` に Line Item レイヤーの SRN を運びます）と組み合わせて使用してください。完全な突合戦略については [Seller Reference Number](/ja/reference/seller-reference-number) を参照してください。
</Note>

`category: newInventoryCreated` / `action: newInventoryCreated`

`returnInventory`の主要フィールド：

| フィールド                     | 説明                         |
| ------------------------- | -------------------------- |
| `returnInventoryId`       | 一意の在庫識別子 — 処理の割り当てにこれを使用する |
| `warehouseId`             | 在庫が保管されている倉庫               |
| `rma`                     | 倉庫が割り当てたRMA値               |
| `handlingCode`            | 現在の処理指示                    |
| `handlingStatusCode`      | 現在の処理ステータス                 |
| `imageList`               | 受領時にキャプチャされた画像             |
| `returnInventoryMetaList` | 追加のメタデータ（例：配送からのカスタムフィールド） |

```json theme={null}
{
  "returnInventory": {
    "returnInventoryId": "19973",
    "warehouseId": 2,
    "apiId": 21,
    "description": "Item description",
    "quantity": 1,
    "dimension1": 20,
    "dimension2": 20,
    "dimension3": 22,
    "dimensionUom": "cm",
    "weight": 300,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 10,
    "handlingCode": "tbc",
    "handlingStatusCode": "pending",
    "completeOn": null,
    "warehouseRemarks": null,
    "handlingUpdatedOn": "2024-07-15T03:29:53.889398",
    "sku": null,
    "rma": "USE-2-240715-D00003-30",
    "modifyOn": "2024-07-15T03:29:53.903982",
    "createOn": "2024-07-15T03:29:53.88968",
    "imageList": [
      {
        "imageUrl": "https://example.com/image1.jpg",
        "imageKey": "images/returns/202407/image1.jpg"
      }
    ],
    "returnInventoryMetaList": [
      {
        "metaType": "shipmentCustomField",
        "metaMap": {
          "customerId": "buyer123"
        }
      }
    ]
  },
  "shipment": {
    "shipmentId": "9999",
    "returnRequestId": "1234",
    "trackingNumber": "TRACK123456",
    "referenceNumber": "",
    "serviceType": "fedex",
    "customFieldMap": {},
    "shipToWarehouseId": 2,
    "receiveDate": "2024-07-15T03:29:00.000000"
  },
  "category": "newInventoryCreated",
  "action": "newInventoryCreated",
  "eventTime": "2024-07-15T03:30:05.1984163Z",
  "version": "202207"
}
```

***

<h3 id="image-updated">
  画像更新済み
</h3>

返品在庫(Return Inventory)ラインアイテムの画像が追加、変更、または削除されたときに送信されます。

`category: rrli` / `action: changeLineItemImage`

トップレベルのペイロードフィールド：

| フィールド                   | タイプ    | 説明                   |
| ----------------------- | ------ | -------------------- |
| `imageUrlList`          | 文字列の配列 | このラインアイテムの現在の画像URL   |
| `returnRequestLineItem` | object | 影響を受けたラインアイテム（以下を参照） |

`returnRequestLineItem`の主要フィールド：

| フィールド                         | 説明                   |
| ----------------------------- | -------------------- |
| `returnRequestLineItemId`     | ラインアイテム識別子           |
| `apiId`                       | 販売者API ID            |
| `returnRequestId`             | リンクされた返品リクエストID      |
| `sellerReferenceNumber`       | 販売者の参照番号             |
| `description`                 | アイテムの説明              |
| `quantity`                    | アイテム数量               |
| `weight` / `weightUom`        | 重量と単位                |
| `valueCurrencyCode` / `value` | 価値と通貨                |
| `handlingCode`                | 処理指示                 |
| `isDeleted`                   | ラインアイテムが削除されているかどうか  |
| `rma`                         | RMA値                 |
| `isFraudulent`                | 不正フラグ                |
| `fraudReasonCode`             | 不正理由コード（フラグが立っている場合） |
| `customFieldMap`              | カスタムフィールド            |

```json theme={null}
{
  "imageUrlList": [
    "https://file.returnhelpercentre.com/img/returns/202606/27_1000040536_lmpiohbx.5n3.jpg",
    "https://file.returnhelpercentre.com/images/returns/202603/16209788537041243876_USE-21-260303-P00156-19_..._4290.jpg"
  ],
  "returnRequestLineItem": {
    "returnRequestLineItemId": 10759,
    "apiId": 21,
    "returnRequestId": 9237,
    "returnRequestLineItemNumber": "RL210706-0000020",
    "sellerReferenceNumber": "RL210706-0000020",
    "description": "Item description",
    "quantity": 1,
    "weight": 100.0,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 463.0,
    "handlingCode": 0,
    "isDeleted": false
  },
  "category": "rrli",
  "action": "changeLineItemImage",
  "eventTime": "2021-07-06T13:02:24.5575164Z"
}
```

`imageUrlList` の URL は公開アクセス可能、期限切れなし、クライアント側で安全にキャッシュ可能です。そのまま保持して使用してください。空状態：`imageUrlList: []`。

***

<h3 id="unknown-shipment-assigned">
  不明な配送が割り当てられた
</h3>

返品リクエストのない配送が識別され、販売者に割り当てられたときに送信されます。

`category: rsl` / `action: assignUnknown` / `version: 202407`

`returnInventory`の主要フィールド：

| フィールド                                      | 説明             |
| ------------------------------------------ | -------------- |
| `returnInventoryId`                        | 一意の在庫識別子       |
| `warehouseId`                              | 在庫が保管されている倉庫   |
| `apiId`                                    | 販売者API ID      |
| `description`                              | アイテムの説明        |
| `quantity`                                 | アイテム数量         |
| `dimension1` / `dimension2` / `dimension3` | 測定された寸法        |
| `dimensionUom`                             | 寸法の単位          |
| `weight`                                   | 測定された重量        |
| `weightUom`                                | 重量の単位          |
| `valueCurrencyCode`                        | 価値の通貨コード       |
| `value`                                    | 申告価値           |
| `handlingCode`                             | 現在の処理指示        |
| `handlingStatusCode`                       | 現在の処理ステータス     |
| `completeOn`                               | 処理完了タイムスタンプ    |
| `warehouseRemarks`                         | 倉庫の備考          |
| `handlingUpdatedOn`                        | 最終処理更新タイムスタンプ  |
| `sku`                                      | 販売者が割り当てたSKU   |
| `rma`                                      | 倉庫が割り当てたRMA    |
| `modifyOn` / `createOn`                    | 監査タイムスタンプ      |
| `imageList`                                | 受領時にキャプチャされた画像 |

`unknownShipment`の主要フィールド：

| フィールド                                      | 説明          |
| ------------------------------------------ | ----------- |
| `unknownShipmentId`                        | 一意の不明配送識別子  |
| `unknownShipmentNumber`                    | 不明配送参照番号    |
| `description`                              | 説明          |
| `unknownShipmentStatusCode`                | 現在のステータス    |
| `unknownShipmentCountryCode`               | 国コード        |
| `warehouseId`                              | 受領倉庫        |
| `unknownShipmentServiceType`               | 配送サービスタイプ   |
| `trackingNumber`                           | キャリア追跡番号    |
| `totalWeight` / `totalWeightUom`           | 合計重量と単位     |
| `dimension1` / `dimension2` / `dimension3` | 測定された寸法     |
| `dimensionUom`                             | 寸法の単位       |
| `totalValue` / `totalValueCurrency`        | 申告価値と通貨     |
| `modifyOn`                                 | 最終変更タイムスタンプ |

***

<h3 id="recall-status-update">
  リコールステータス更新
</h3>

リコール追跡番号が更新されるか、集荷ステータスが変更されたときに送信されます。

`category: recall` / `action: recallUpdateStatus`

`recallUpdateTypeStatus`の値：

| 値                      | リコール在庫ステータス        | 説明            |
| ---------------------- | ------------------ | ------------- |
| `updateTrackingNumber` | `in-transit`       | 追跡番号が割り当てられた  |
| `readyToPickUp`        | `ready-to-pick-up` | アイテムの集荷準備が完了  |
| `pickupBySelf`         | `picked-up`        | 顧客が自分で集荷した    |
| `pickupByCourier`      | `picked-up`        | ローカルクーリエが集荷した |
| `pickupByOthers`       | `picked-up`        | 別の当事者が集荷した    |

```json theme={null}
{
  "recall": {
    "apiId": 103,
    "recallId": 938,
    "recallNumber": "RCL240423-0000001",
    "recallStatusCode": "in-progress",
    "warehouseRemarks": null,
    "recallInventoryList": [
      {
        "recallInventoryId": 1145,
        "returnInventoryId": 18600,
        "recallInventoryStatusCode": "in-transit",
        "pickUpCode": "pending",
        "trackingNumber": "AWB-TRACKING-NUMBER",
        "listName": null,
        "weight": null,
        "amount": null,
        "pickUpOn": null,
        "courierTrackingNumber": null,
        "remarks": null,
        "recallServiceType": "dhl",
        "rma": "USE-1005-240523-D00001-25"
      }
    ]
  },
  "recallUpdateTypeStatus": "updateTrackingNumber",
  "category": "recall",
  "action": "recallUpdateStatus",
  "eventTime": "2024-04-23T07:50:49.2479819Z"
}
```

***

<h3 id="resend-status-update">
  再送ステータス更新
</h3>

再送追跡番号が更新されるか、再送が完了または失敗したときに送信されます。

`category: resend` / `action: updateResendStatus`

トップレベルのペイロードフィールド：

| フィールド                 | タイプ    | 説明                   |
| --------------------- | ------ | -------------------- |
| `resend`              | object | 再送注文の詳細（以下を参照）       |
| `returnInventoryList` | array  | 再送対象の在庫アイテム          |
| `resendShipmentList`  | array  | この再送に対応する再送配送（以下を参照） |

`resend`の主要フィールド：

| フィールド              | 説明                                                                                     |
| ------------------ | -------------------------------------------------------------------------------------- |
| `resendId`         | 一意の再送注文識別子                                                                             |
| `apiId`            | 販売者API ID                                                                              |
| `resendNumber`     | 再送注文番号                                                                                 |
| `resendStatusCode` | 現在のステータス：`0` — 保留中、`1` — キャンセル済み、`2` — 処理中、`3` — 完了、`4` — 失敗、`5` — キュー待ち、`6` — ラベル生成済み |
| `description`      | 注文の説明                                                                                  |
| `remarks`          | 販売者の備考                                                                                 |
| `warehouseRemarks` | 倉庫の備考                                                                                  |

`resendShipmentList`の各エントリの主要フィールド：

| フィールド                   | 説明                  |
| ----------------------- | ------------------- |
| `resendShipmentId`      | 再送配送の識別子            |
| `resendId`              | この配送が属する再送注文        |
| `resendShipmentNumber`  | 再送配送番号              |
| `trackingNumber`        | 運送会社の追跡番号（利用可能な場合）  |
| `sellerReferenceNumber` | この再送に対するお客様自身の参照番号  |
| `error`                 | エラーメッセージ（配送が失敗した場合） |

<Note>
  `resendShipmentList` には常に 1 件のエントリのみが含まれます——1 つの resend に対して resend shipment は必ず 1 つだけです。`resendShipmentList[0]` として読み取ってください。
</Note>

<Warning>
  `trackingNumber` はトップレベルのフィールドでは **ありません**。再送配送の中にあります：`resendShipmentList[0].trackingNumber`。
</Warning>

`resend.resendStatusCode`を確認してください：

* `3` — 完了（`resendShipmentList[0].trackingNumber` を確認）
* `4` — 失敗（`resendShipmentList[0].error` を確認）

```json theme={null}
{
  "resend": {
    "resendId": 2902,
    "apiId": 21,
    "resendNumber": "RSD221003-0000001",
    "resendStatusCode": 3
  },
  "returnInventoryList": [
    {
      "returnInventoryId": 14129,
      "rma": "SGP240101-0000001"
    }
  ],
  "resendShipmentList": [
    {
      "resendShipmentId": 2897,
      "resendId": 2902,
      "resendShipmentNumber": "RSDS221003-0000001",
      "trackingNumber": "9201994884299101443342",
      "sellerReferenceNumber": "ORDER-0001",
      "error": null
    }
  ],
  "category": "resend",
  "action": "updateResendStatus"
}
```

`resendShipmentList[0].sellerReferenceNumber` を使うと、Return Helper の `resendId` を保存しなくてもイベントをお客様自身の注文レコードと突き合わせられます。

<Note>
  `sellerReferenceNumber` に値が入るのは、**Enterprise** アカウントが [SKU で Resend を作成](/ja/api-reference/resend/create-resend-by-sku) で参照番号を指定して作成した resend のみです。それ以外の resend では `null` になります。この値で resend を随時参照するには、[Seller Reference Number で Resend を検索](/ja/api-reference/resend/search-resend-by-seller-reference-number)を使用してください。
</Note>

***

<h3 id="vas-update">
  VAS更新
</h3>

付加価値サービス(VAS)が完了したときに送信されます。

`category: rrliv` / `action: vasUpdated`

`updateVasList`の各アイテム：

| フィールド                                      | 説明          |
| ------------------------------------------ | ----------- |
| `returnRequestLineItemVasId`               | VASレコード識別子  |
| `vasResult`                                | VAS結果の説明    |
| `weight` / `weightUom`                     | VAS後の重量と単位  |
| `dimension1` / `dimension2` / `dimension3` | VAS後の寸法     |
| `dimensionUom`                             | 寸法の単位       |
| `vasStatusCode`                            | VASステータスコード |
| `imageUrlList`                             | VAS結果の画像    |

```json theme={null}
{
  "updateVasList": [
    {
      "returnRequestLineItemVasId": 65205,
      "vasResult": "VAS result details",
      "weight": 1000.0,
      "weightUom": "g",
      "dimension1": 25.0,
      "dimension2": 20.0,
      "dimension3": 10.0,
      "dimensionUom": "cm",
      "vasStatusCode": "SUCCESSFUL",
      "imageUrlList": [
        "https://file.returnhelpercentre.com/img/returns/202606/27_1000011051_eu4jjyfj.wth.jpg",
        "https://file.returnhelpercentre.com/img/returns/202606/27_1000011050_0nfetxuv.5hb.jpg"
      ]
    }
  ],
  "category": "rrliv",
  "action": "vasUpdated",
  "eventTime": "2021-07-06T12:15:55.9038524Z"
}
```

`imageUrlList` の URL は公開アクセス可能、期限切れなし、クライアント側で安全にキャッシュ可能です。そのまま保持して使用してください。空状態：`imageUrlList: []`（一部の VAS タイプは画像を生成しません。その場合もエントリは `updateVasList[]` に残り、`imageUrlList` のみ空配列となります）。

***

<h3 id="inventory-handling-complete">
  在庫処理完了
</h3>

処理指示（廃棄、再送、リコールなど）が倉庫によって完了されたときに送信されます。

`category: rinv` / `action: completeInventoryHandling`

`returnInventory`の主要フィールド：

| フィールド                                      | 説明               |
| ------------------------------------------ | ---------------- |
| `returnInventoryId`                        | 一意の在庫識別子         |
| `warehouseId`                              | 在庫が保管されている倉庫     |
| `returnRequestLineItemId`                  | リンクされたラインアイテムID  |
| `apiId`                                    | 販売者API ID        |
| `returnRequestId`                          | リンクされた返品リクエストID  |
| `sellerReferenceNumber`                    | 販売者の参照番号         |
| `description`                              | アイテムの説明          |
| `quantity`                                 | アイテム数量           |
| `dimension1` / `dimension2` / `dimension3` | 測定された寸法          |
| `dimensionUom`                             | 寸法の単位            |
| `weight`                                   | 測定された重量          |
| `weightUom`                                | 重量の単位            |
| `valueCurrencyCode`                        | 価値の通貨コード         |
| `value`                                    | 申告価値             |
| `handlingCode`                             | 処理指示（以下の表を参照）    |
| `handlingStatusCode`                       | 処理ステータス（以下の表を参照） |
| `completeBy`                               | 処理を完了したユーザー      |
| `completeOn`                               | 完了タイムスタンプ        |
| `warehouseRemarks`                         | 倉庫の備考            |
| `handlingUpdatedOn`                        | 最終処理更新タイムスタンプ    |
| `stopAgingOn`                              | エージング停止タイムスタンプ   |
| `sku`                                      | 販売者が割り当てたSKU     |
| `rma`                                      | 倉庫が割り当てたRMA      |
| `returnInventoryMetaList`                  | 追加のメタデータリスト      |

`handlingCode`の値：

| ID | コード   | 説明   |
| -- | ----- | ---- |
| 0  | `tbc` | 確認待ち |
| 1  | `rtn` | リコール |
| 2  | `dis` | 廃棄   |
| 3  | `rsd` | 再送   |
| 4  | `ohd` | 保留   |
| 5  | `oth` | その他  |

`handlingStatusCode`の値：

| ID | コード          | 説明  |
| -- | ------------ | --- |
| 0  | `pending`    | 保留中 |
| 1  | `inProgress` | 処理中 |
| 2  | `completed`  | 完了  |

***

<h3 id="inventory-recalibrated">
  在庫再校正済み
</h3>

倉庫が返品在庫(Return Inventory)の測定された寸法または重量を更新したときに送信されます。

`category: completeRecalibrate` / `action: completeRecalibrate`

`recalibrateSupplement`の主要フィールド：

| フィールド                                      | 説明                                            |
| ------------------------------------------ | --------------------------------------------- |
| `warehouseId`                              | 再校正を実施した倉庫                                    |
| `returnInventoryId`                        | 影響を受けた在庫ID                                    |
| `returnRequestLineItemId`                  | リンクされたラインアイテムID                               |
| `rma`                                      | RMA値                                          |
| `dimension1` / `dimension2` / `dimension3` | 更新された寸法                                       |
| `weight`                                   | 更新された重量                                       |
| `recalibratedOn`                           | 再校正タイムスタンプ                                    |
| `returnInventoryMetaList`                  | 更新されたメタデータリスト（各エントリには`metaType`と`metaMap`がある） |

```json theme={null}
{
  "recalibrateSupplement": {
    "warehouseId": 8,
    "returnInventoryId": 18191,
    "returnRequestLineItemId": 38320,
    "rma": "USE-1005-240523-D00001-25",
    "dimension1": 20.0,
    "dimension2": 20.0,
    "dimension3": 20.0,
    "weight": 310.0,
    "recalibratedOn": "2024-04-04T00:42:11.1325135Z"
  },
  "category": "completeRecalibrate",
  "action": "completeRecalibrate",
  "eventTime": "2024-04-04T00:54:29.4337417Z"
}
```

***

<h3 id="inventory-meta-updated">
  在庫メタデータ更新済み
</h3>

倉庫またはユーザーが返品在庫(Return Inventory)にメタデータを追加または更新したときに送信されます。

`category: updateReturnInventoryMeta` / `action: updateReturnInventoryMeta`

ペイロードには、更新された`returnInventoryMetaList`を含む、[在庫作成済み](#inventory-created)と同じ構造の`returnInventory`が含まれています。

`metaType`の値：

* `usr` — ユーザーが提供したメタ
* `whs` — 倉庫が提供したメタ

***

<h3 id="rma-updated">
  RMA更新済み
</h3>

倉庫が誤ったRMAの割り当てを修正したときに送信されます。

`category: notifyUserRmaSwapped` / `action: notifyUserRmaSwapped`

`payload`の主要フィールド：

| フィールド               | 説明           |
| ------------------- | ------------ |
| `userApiId`         | 販売者API ID    |
| `clientCode`        | クライアントコード    |
| `returnInventoryId` | 影響を受けた在庫ID   |
| `oldRma`            | 以前のRMA値      |
| `newRma`            | 新しい修正されたRMA値 |

```json theme={null}
{
  "payload": {
    "userApiId": 21,
    "clientCode": "RH21",
    "returnInventoryId": "19029",
    "oldRma": "USE-2-240517-D00026-56",
    "newRma": "USE-2-240520-D00001-35"
  },
  "category": "notifyUserRmaSwapped",
  "action": "notifyUserRmaSwapped",
  "eventTime": "2024-05-23T06:26:43.4416977Z"
}
```

***

<h3 id="sku-updated">
  SKU更新済み
</h3>

販売者が返品在庫(Return Inventory)のSKUを更新したときに送信されます。

`category: userUpdateReturnInventorySku` / `action: userUpdateReturnInventorySku`

ペイロードには`returnRequest`と`returnInventory`が含まれています。

`returnRequest`の主要フィールド：

| フィールド                               | 説明                   |
| ----------------------------------- | -------------------- |
| `returnRequestId`                   | 一意の返品リクエスト識別子        |
| `apiId`                             | 販売者API ID            |
| `sellerReferenceNumber`             | 販売者の参照番号             |
| `returnStatusCode`                  | 返品リクエストステータス         |
| `returnTitle`                       | 返品タイトル               |
| `totalValue` / `totalValueCurrency` | 合計申告価値と通貨            |
| `remarks`                           | 備考                   |
| `rma`                               | RMA値                 |
| `isArchived`                        | リクエストがアーカイブされているかどうか |
| `returnRequestSourceType`           | 返品リクエストのソースタイプ       |

`returnInventory`オブジェクトは、更新された`sku`フィールドを含む、[在庫処理完了](#inventory-handling-complete)と同じ構造に従います。

***

<h3 id="split-line-item">
  ラインアイテム分割
</h3>

VAS操作が荷物を複数の在庫に分割したときに送信されます。各結果の荷物の新しいラインアイテムと在庫レコードが含まれています。

`category: lineItemVasReturnInventoryLineItem` / `action: splitLineItem`

トップレベルのペイロードフィールド：

| フィールド                                 | タイプ     | 説明                        |
| ------------------------------------- | ------- | ------------------------- |
| `returnRequestId`                     | integer | リンクされた返品リクエストID           |
| `returnRequestLineItemId`             | long    | 元のラインアイテムID               |
| `returnRequestLineItemVasId`          | long    | 分割をトリガーしたVASレコードID        |
| `vasStatusCode`                       | string  | VASステータスコード               |
| `splitLineItemAndReturnInventoryList` | array   | 結果として分割されたアイテムのリスト（以下を参照） |

`splitLineItemAndReturnInventoryList`の各アイテムには以下が含まれます：

| フィールド                             | タイプ    | 説明                                                                                                                                                                                   |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `returnRequestLineItem`           | object | 新しいラインアイテムレコード（`returnRequestLineItemId`、`sellerReferenceNumber`、`description`、`quantity`、`weight`、`weightUom`、`valueCurrencyCode`、`value`、`handlingCode`、`rma`、`customFieldMap`を含む） |
| `returnInventory`                 | object | 新しい在庫レコード（[在庫処理完了](#inventory-handling-complete)と同じ構造）                                                                                                                               |
| `returnRequestLineItemSupplement` | object | 新しいラインアイテムの寸法と重量を含む補足                                                                                                                                                                |

***

<h3 id="warehouse-remarks-updated">
  倉庫備考更新済み
</h3>

倉庫が返品リクエストの備考を更新したときに送信されます。

`category: warehouseUpdateWarehouseRemarks` / `action: warehouseUpdateWarehouseRemarks`

ペイロードには3つのオブジェクトが含まれています：

* `returnRequest` — 返品リクエスト（[SKU更新済み → returnRequest](#sku-updated)と同じ構造）
* `shipment` — 完全な住所詳細、寸法、重量、コスト、`customFieldMap`を含む配送レコード
* `returnInventory` — 影響を受けた在庫（[在庫処理完了](#inventory-handling-complete)と同じ構造）、更新された`warehouseRemarks`フィールドを含む

***

<h3 id="buyer-return-label-generated">
  購入者返品ラベル生成済み
</h3>

購入者がブランド返品ポータルで返品を作成し、ラベルが生成されたときに送信されます。

<Info>
  Return Helperのブランド返品サービスに連携している顧客にのみ適用されます。
</Info>

`category: buyerReturnRrLabel` / `action: buyerReturnLabelGenerated`

`buyerReturn.labelRequestStatusCode`で`"success"`または`"fail"`を確認してください。

`buyerReturn`の主要フィールド：

| フィールド                                                       | 説明                             |
| ----------------------------------------------------------- | ------------------------------ |
| `buyerReturnId`                                             | 一意の購入者返品識別子                    |
| `apiId`                                                     | 販売者API ID                      |
| `sellerReferenceNumber`                                     | 販売者の参照番号                       |
| `returnRequestId`                                           | リンクされた返品リクエストID（作成された場合）       |
| `shipmentId`                                                | リンクされた配送ID（作成された場合）            |
| `returnRequestNumber`                                       | 返品リクエスト番号                      |
| `shipmentNumber`                                            | 配送番号                           |
| `totalValue` / `totalValueCurrency`                         | 申告価値と通貨                        |
| `remarks`                                                   | 備考                             |
| `labelId`                                                   | ラベルID                          |
| `labelRequestStatusCode`                                    | `"success"`または`"fail"`         |
| `trackingNumber`                                            | 追跡番号（成功時）                      |
| `labelFile`                                                 | `labelUrl`と`labelKey`を持つオブジェクト |
| `shipmentInstruction`                                       | 配送指示                           |
| `error`                                                     | エラーメッセージ（失敗時）                  |
| `warehouseId`                                               | 目的地の倉庫                         |
| `shipmentServiceType`                                       | 配送サービスタイプ                      |
| `shipmentCountryCode`                                       | 配送国                            |
| `shipmentName` / `shipmentPhone` / `shipmentEmail`          | 連絡先詳細                          |
| `shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`   | 住所行                            |
| `shipmentCity` / `shipmentState` / `shipmentPostalCode`     | 住所詳細                           |
| `costCurrencyCode` / `cost`                                 | 配送コスト                          |
| `sellerCostCurrencyCode` / `sellerCost`                     | 販売者コスト                         |
| `buyerCostCurrencyCode` / `buyerCost`                       | 購入者コスト                         |
| `boxType`                                                   | ボックスタイプ                        |
| `weight` / `weightUom`                                      | 重量と単位                          |
| `dimension1` / `dimension2` / `dimension3` / `dimensionUom` | 荷物の寸法                          |
| `customFieldMap`                                            | カスタムフィールド                      |
| `buyerReturnLineItemList`                                   | ラインアイテムのリスト（以下を参照）             |

`buyerReturnLineItemList`の各アイテム：

| フィールド                               | 説明           |
| ----------------------------------- | ------------ |
| `buyerReturnLineItemId`             | ラインアイテムID    |
| `sellerReferenceNumber`             | 販売者の参照       |
| `description`                       | アイテムの説明      |
| `quantity`                          | 数量           |
| `weight` / `weightUom`              | 重量と単位        |
| `value` / `valueCurrencyCode`       | 価値と通貨        |
| `returnReasonCode` / `returnReason` | 購入者が選択した返品理由 |
| `customFieldMap`                    | カスタムフィールド    |

***

<h3 id="shopify-buyer-return-created">
  Shopify購入者返品作成済み
</h3>

購入者がShopify連携を通じて返品リクエストを作成したときに送信されます。

`category: shopifyBuyerCreateReturn` / `action: shopifyBuyerCreateReturn`

`shopifyReturn`の主要フィールド：

| フィールド                                                        | 説明                              |
| ------------------------------------------------------------ | ------------------------------- |
| `shopifyReturnId`                                            | 一意のShopify返品識別子                 |
| `apiId`                                                      | 販売者API ID                       |
| `referenceNumber`                                            | 参照番号                            |
| `returnRequestId`                                            | リンクされた返品リクエストID（作成された場合）        |
| `shipmentId`                                                 | リンクされた配送ID（作成された場合）             |
| `returnRequestNumber` / `shipmentNumber`                     | 返品と配送の番号                        |
| `totalValue` / `totalValueCurrency`                          | 申告価値と通貨                         |
| `remarks`                                                    | 備考                              |
| `labelRequestStatusCode`                                     | ラベルステータス：`"success"`または`"fail"` |
| `trackingNumber`                                             | 追跡番号（成功時）                       |
| `labelUrl`                                                   | ラベルURL（成功時）                     |
| `error`                                                      | エラーメッセージ（失敗時）                   |
| `warehouseId`                                                | 目的地の倉庫                          |
| `shipmentServiceType` / `shipmentCountryCode`                | 配送サービスと国                        |
| `shipmentName` / `shipmentPhone` / `shipmentEmail`           | 連絡先詳細                           |
| `shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`    | 住所行                             |
| `shipmentCity` / `shipmentState` / `shipmentPostalCode`      | 住所詳細                            |
| `costCurrencyCode` / `cost`                                  | 配送コスト                           |
| `boxType`                                                    | ボックスタイプ                         |
| `weight` / `weightUom`                                       | 重量と単位                           |
| `dimension1` / `dimension2` / `dimension3` / `dimensionUom`  | 荷物の寸法                           |
| `shopifyShopId`                                              | Shopifyショップ識別子                  |
| `shopifyOrderId` / `shopifyOrderNumber` / `shopifyOrderName` | Shopify注文詳細                     |
| `shopifyReturnStatusCode`                                    | Shopify返品ステータス                  |
| `requestParty`                                               | 返品を開始した当事者                      |
| `customFieldMap`                                             | カスタムフィールド                       |

`shopifyReturnLineItemList`の各アイテム：

| フィールド                               | 説明           |
| ----------------------------------- | ------------ |
| `shopifyReturnLineItemId`           | ラインアイテムID    |
| `sellerReferenceNumber`             | 販売者の参照       |
| `description`                       | アイテムの説明      |
| `quantity`                          | 数量           |
| `sku`                               | 商品SKU        |
| `weight` / `weightUom`              | 重量と単位        |
| `value` / `valueCurrencyCode`       | 価値と通貨        |
| `returnReasonCode` / `returnReason` | 購入者が選択した返品理由 |
| `shopifyProductId`                  | Shopify商品ID  |
| `buyerNotes`                        | 購入者のメモ       |
| `customFieldMap`                    | カスタムフィールド    |

***

<h3 id="consolidate-shipping-cost-updated">
  統合配送コスト更新済み
</h3>

統合配送注文の配送コストが更新されたときに送信されます。

`category: consolidateShippingOrderShippingFeeUpdated` / `action: consolidateShippingOrderShippingFeeUpdated`

`order`の主要フィールド：

| フィールド                                                               | 説明          |
| ------------------------------------------------------------------- | ----------- |
| `consolidateShippingOrderId`                                        | 注文識別子       |
| `consolidateShippingOrderNumber`                                    | 注文番号        |
| `consolidateShippingOrderStatus`                                    | 現在のステータス    |
| `outboundWarehouseId`                                               | 出荷倉庫        |
| `shippingMethod`                                                    | 配送方法        |
| `shippingFee` / `currencyCode`                                      | 更新された配送料と通貨 |
| `shipToContactName` / `shipToPhone` / `shipToEmail`                 | 配送先連絡先      |
| `shipToCompanyName`                                                 | 配送先会社名      |
| `shipToStreet1` / `shipToStreet2` / `shipToStreet3`                 | 配送先住所行      |
| `shipToCity` / `shipToState` / `shipToPostalCode` / `shipToCountry` | 配送先住所       |
| `deliveryInstructions`                                              | 配送指示        |

***

<h3 id="consolidate-shipping-all-packed">
  統合配送すべて梱包済み
</h3>

倉庫が統合注文のすべての在庫をボックスに梱包したときに送信されます。

`category: consolidateShippingOrderInventoryAllPacked` / `action: consolidateShippingOrderInventoryAllPacked`

`order`の主要フィールド：

| フィールド                            | 説明            |
| -------------------------------- | ------------- |
| `consolidateShippingOrderId`     | 注文識別子         |
| `consolidateShippingOrderNumber` | 注文番号          |
| `consolidateShippingOrderStatus` | 現在のステータス      |
| `outboundWarehouseId`            | 出荷倉庫          |
| `shippingFee` / `currencyCode`   | 配送料と通貨        |
| `shippingMethod`                 | 配送方法          |
| `customFieldMap`                 | カスタムフィールド     |
| `deliveryInstructions`           | 配送指示          |
| `shipmentList`                   | 配送のリスト（以下を参照） |

`shipmentList`の各アイテム：

| フィールド                               | 説明             |
| ----------------------------------- | -------------- |
| `consolidateShippingShipmentId`     | 配送識別子          |
| `consolidateShippingShipmentNumber` | 配送番号           |
| `consolidateShippingShipmentStatus` | 配送ステータス        |
| `awb`                               | 航空貨物運送状番号      |
| `serviceProvider`                   | キャリアサービスプロバイダー |
| `shipDate`                          | 配送日            |
| `boxList`                           | この配送のボックスリスト   |

`boxList`の各アイテム：

| フィールド                                  | 説明        |
| -------------------------------------- | --------- |
| `consolidateShippingShipmentBoxId`     | ボックス識別子   |
| `boxNumber`                            | ボックス番号    |
| `consolidateShippingShipmentBoxStatus` | ボックスステータス |
| `consolidateShippingInventoryList`     | このボックスの在庫 |

`consolidateShippingInventoryList`の各アイテム：

| フィールド                                | 説明                             |
| ------------------------------------ | ------------------------------ |
| `consolidateShippingInventoryId`     | 在庫識別子                          |
| `returnInventoryId`                  | リンクされた返品在庫(Return Inventory)ID |
| `rma`                                | RMA値                           |
| `consolidateShippingInventoryStatus` | 在庫ステータス                        |

***

<h3 id="consolidate-shipment-sent">
  統合配送発送済み
</h3>

倉庫が統合配送をキャリアに発送したときに送信されます。

`category: consolidateShippingShipmentSent` / `action: consolidateShippingShipmentSent`

`shipment`の主要フィールド：

| フィールド                               | 説明                                                                  |
| ----------------------------------- | ------------------------------------------------------------------- |
| `consolidateShippingShipmentId`     | 配送識別子                                                               |
| `consolidateShippingShipmentNumber` | 配送番号                                                                |
| `consolidateShippingShipmentStatus` | 現在のステータス                                                            |
| `awb`                               | 航空貨物運送状番号                                                           |
| `serviceProvider`                   | キャリアサービスプロバイダー                                                      |
| `shipDate`                          | 配送日                                                                 |
| `boxList`                           | ボックスリスト（[すべて梱包済み → boxList](#consolidate-shipping-all-packed)と同じ構造） |
| `consolidateShippingOrderId`        | 親注文識別子                                                              |
| `consolidateShippingOrderNumber`    | 親注文番号                                                               |
| `consolidateShippingOrderStatus`    | 親注文ステータス                                                            |
| `outboundWarehouseId`               | 出荷倉庫                                                                |
| `customFieldMap`                    | カスタムフィールド                                                           |

***

<h3 id="consolidate-shipping-awb-updated">
  統合配送AWB更新済み
</h3>

統合配送の航空貨物運送状番号が更新されたときに送信されます。

`category: consolidateShippingShipmentShipped` / `action: consolidateShippingShipmentShipped`

`shipment`オブジェクトは、更新された`awb`フィールドを含む、[統合配送発送済み](#consolidate-shipment-sent)と同じ構造に従います。

***

<h3 id="consolidate-order-completed">
  統合注文完了
</h3>

統合注文のすべての配送が発送されたときに送信されます。

`category: consolidateShippingOrderCompleted` / `action: consolidateShippingOrderCompleted`

`order`オブジェクトは、`boxList`と在庫詳細を含む完全な`shipmentList`を含む、[統合配送すべて梱包済み](#consolidate-shipping-all-packed)と同じ構造に従います。

***

<h3 id="consolidate-order-cancelled">
  統合注文キャンセル
</h3>

倉庫が統合配送注文を強制キャンセルしたときに送信されます。

`category: consolidateShippingOrderCancelled` / `action: consolidateShippingOrderCancelled`

`order`の主要フィールド：

| フィールド                            | 説明                |
| -------------------------------- | ----------------- |
| `consolidateShippingOrderId`     | 注文識別子             |
| `consolidateShippingOrderNumber` | 注文番号              |
| `consolidateShippingOrderStatus` | 現在のステータス（キャンセル済み） |
| `outboundWarehouseId`            | 出荷倉庫              |
| `shippingMethod`                 | 配送方法              |
| `shippingFee`                    | 配送料               |
| `deliveryInstructions`           | 配送指示              |
| `customFieldMap`                 | カスタムフィールド         |

***