Webhookと通知 - Return Helper API

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

概要

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

フィールドは予告なく追加されます。 Return Helper は、事前の通知なく Webhook ペイロードにフィールドを追加します。ペイロードのスキーマを厳密に検証せず、認識できないフィールドは無視したうえで、通常どおり 2xx を返してください。

Webhookエンドポイントの設定

エンドポイントの要件

エンドポイントを登録する前に、以下の要件を満たしていることを確認してください：

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

エンドポイントの登録

Webhook エンドポイントは、API を使ってお客様ご自身で登録・管理できます：

目的	呼び出し
エンドポイントを登録する	Notification Endpoint を追加
登録済みのエンドポイントを確認する	Notification Endpoint を一覧取得
エンドポイントを削除する	Notification Endpoint を削除

登録する前にハンドラーをデプロイしてください。Return Helper はその URL に署名付きの検証リクエストを送信し、30 秒以内に 2xx ステータスが返された場合にのみエンドポイントが保存されます。登録した各エンドポイントは、アカウントのすべてのイベントを受信します。category と action フィールドを使って、お客様側でフィルタリングしてください。サンドボックスと本番環境は別々に登録します。通知を受け取りたい各環境で、その環境の認証情報を使って API を呼び出してください。

イベント配信

タイミング — イベントはトリガーアクションの数秒後に届く場合があり、まれに数分後になることがあります。 重複イベント — エンドポイントが同じイベントを複数回受信する場合があります。処理済みの notificationId を追跡して重複を排除してください。notificationId はイベントごとに一意で、すべてのウェブフック通知に含まれるため、それ単体で安定した冪等キーとして使用できます。 イベントの順序 — 配信順序は保証されていません。任意の順序でイベントを処理できるようにハンドラーを設計してください。たとえば、inventoryCreatedがwarehouseMarkShipmentArrivedV2より前に届く場合があります。順序外で受信したイベントで参照されているオブジェクトを取得するには、APIを使用してください。各イベントにはISO 8601形式のeventTimeフィールドが含まれています。

通知ヘッダー

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

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

旧ヘッダー

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

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

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

署名の検証

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

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

詳細な例

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

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

ステップバイステップの検証

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

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

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

2024-01-12T09:23:08.4863561Z

ステップ3 — string_to_signを構築する 以下の4つの値を順番に連結します（区切り文字なし）：

HTTPメソッド：POST
通知エンドポイントURL：https://s2024-01-12.free.beeceptor.com
ステップ2で取得した RETURNHELPER-TRIGGERED-AT の値
生の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==

操作：

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

期待される結果：

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

ステップ5 — 署名の比較 ステップ4で計算した署名とステップ1で抽出した署名を比較します。タイミング攻撃を防ぐため、定数時間文字列比較を使用してください。 追加のセキュリティ： eventTimeがシステムクロックと15分以上異なるイベントを拒否してください（リプレイ攻撃保護）。

サンプルコード

// 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);
  }
}

// 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);

// 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();

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);
    }
}

再試行メカニズム

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

共通ボディフィールド

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

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

通知イベントリファレンス

通知	`category`	`action`	説明
ラベル結果	`labelGenerated`	`labelGenerated`	ラベル生成結果（成功または失敗）
倉庫配送到着（v2）	`rsl`	`markShipmentArrive`	倉庫での配送受領（現在のバージョン）
在庫作成済み	`newInventoryCreated`	`newInventoryCreated`	新しい返品在庫(Return Inventory)が作成された
画像更新済み	`rrli`	`changeLineItemImage`	ラインアイテム画像が追加、変更、または削除された
不明な配送が割り当てられた	`rsl`	`assignUnknown`	不明な配送が販売者に割り当てられた
リコールステータス更新	`recall`	`recallUpdateStatus`	リコール追跡または集荷ステータスが変更された
再送ステータス更新	`resend`	`updateResendStatus`	再送追跡またはステータスが変更された
VAS更新	`rrliv`	`vasUpdated`	付加価値サービス(VAS)が完了または更新された
在庫処理完了	`rinv`	`completeInventoryHandling`	処理指示が完了した
在庫再校正済み	`completeRecalibrate`	`completeRecalibrate`	倉庫が在庫の寸法/重量を更新した
在庫メタデータ更新済み	`updateReturnInventoryMeta`	`updateReturnInventoryMeta`	倉庫またはユーザーがメタデータを追加/更新した
RMA更新済み	`notifyUserRmaSwapped`	`notifyUserRmaSwapped`	倉庫がRMAの割り当てを修正した
SKU更新済み	`userUpdateReturnInventorySku`	`userUpdateReturnInventorySku`	販売者が在庫のSKUを更新した
ラインアイテム分割	`lineItemVasReturnInventoryLineItem`	`splitLineItem`	VASが荷物を複数の在庫に分割した
倉庫備考更新済み	`warehouseUpdateWarehouseRemarks`	`warehouseUpdateWarehouseRemarks`	倉庫が返品リクエストの備考を更新した
購入者返品ラベル生成済み	`buyerReturnRrLabel`	`buyerReturnLabelGenerated`	ブランド返品ポータルのラベルが購入者向けに生成された
Shopify購入者返品作成済み	`shopifyBuyerCreateReturn`	`shopifyBuyerCreateReturn`	購入者がShopify連携を通じて返品を作成した
統合配送コスト更新済み	`consolidateShippingOrderShippingFeeUpdated`	`consolidateShippingOrderShippingFeeUpdated`	統合配送注文のコストが更新された
統合配送すべて梱包済み	`consolidateShippingOrderInventoryAllPacked`	`consolidateShippingOrderInventoryAllPacked`	統合注文のすべての在庫が梱包された
統合配送発送済み	`consolidateShippingShipmentSent`	`consolidateShippingShipmentSent`	統合配送がキャリアに発送された
統合配送AWB更新済み	`consolidateShippingShipmentShipped`	`consolidateShippingShipmentShipped`	統合配送のAWBが更新された
統合配送到着済み	`consolidateShippingShipmentArrived`	`consolidateShippingShipmentArrived`	RH 倉庫宛ての Shipment が到着し、請求された
統合注文完了	`consolidateShippingOrderCompleted`	`consolidateShippingOrderCompleted`	統合注文のすべての明細が出荷された
統合注文キャンセル	`consolidateShippingOrderCancelled`	`consolidateShippingOrderCancelled`	統合注文が倉庫によって強制キャンセルされた
取引追加済み	`transaction`	`addTransaction`	お客様のアカウントに課金、返金、またはトップアップが計上された

通知ペイロード

ラベル結果

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

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

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（地域コードをキーとする）。地域別ラベルURLを参照。

地域別ラベルURL

regionsは、labelUrlと同じラベルファイルの別のURLを提供します。その地域でラベルをダウンロードまたは印刷する場合に使用してください。

キー	ホスト	使用する場面
`RHCN`	`label.returnhelperchina.com`	中国本土でラベルをダウンロードまたは印刷する場合

各値はlabelUrlと同じPDFを指します。異なるのはホストのみです。
すべてのアカウントに含まれます。設定は不要です。
labelGeneratedイベントにのみ含まれます。APIレスポンスや他のWebhookイベントに含まれるラベルURLは、labelUrlのホストのみを使用します。地域別URLが必要な場合は、このイベントから保存してください。
labelUrlがnullの場合（ラベルリクエストが失敗した場合）、regionsは{}になります。
認識できないキーは無視してください。必要なキーがない場合はlabelUrlを使用してください。

成功例：

{
  "label": {
    "regions": {
      "RHCN": "https://label.returnhelperchina.com/label/202109/example-S210904-0000202.pdf"
    },
    "labelId": 11345,
    "shipmentId": 10825,
    "apiId": 21,
    "refKey": "S210904-0000202",
    "labelRequestStatusCode": "success",
    "serviceType": "usps",
    "trackingNumber": "9201994884299101443342",
    "labelUrl": "https://label.returnhelpercentre.com/label/202109/example-S210904-0000202.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"
}

失敗例：

{
  "label": {
    "regions": {},
    "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"
}

倉庫配送到着（v2）

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

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

category: rsl / action: markShipmentArrive / version: 202407 shipmentの主要フィールド：

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

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

在庫作成済み

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

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

category: newInventoryCreated / action: newInventoryCreated returnInventoryの主要フィールド：

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

{
  "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",
    "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"
}

画像更新済み

返品在庫(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`	カスタムフィールド

{
  "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: []。

不明な配送が割り当てられた

返品リクエストのない配送が識別され、販売者に割り当てられたときに送信されます。 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
`imageList`	受領時にキャプチャされた画像

unknownShipmentの主要フィールド：

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

リコールステータス更新

Recall はまもなく終了します。Return Helper の香港倉庫へ在庫を送るには、destinationType: RH_WAREHOUSE で Consolidate Shipping Order を作成してください。

リコール追跡番号が更新されるか、集荷ステータスが変更されたときに送信されます。 category: recall / action: recallUpdateStatus recallUpdateTypeStatusの値：

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

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

再送ステータス更新

再送追跡番号が更新されるか、再送が完了または失敗したときに送信されます。 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`	エラーメッセージ（配送が失敗した場合）

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

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

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

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

{
  "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 を保存しなくてもイベントをお客様自身の注文レコードと突き合わせられます。

sellerReferenceNumber に値が入るのは、Enterprise アカウントが SKU で Resend を作成で参照番号を指定して作成した resend のみです。それ以外の resend では null になります。この値で resend を随時参照するには、Seller Reference Number で Resend を検索を使用してください。

VAS更新

付加価値サービス(VAS)が完了したときに送信されます。 category: rrliv / action: vasUpdated updateVasListの各アイテム：

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

{
  "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 のみ空配列となります）。

在庫処理完了

処理指示（廃棄、再送、リコールなど）が倉庫によって完了されたときに送信されます。 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`	完了

在庫再校正済み

倉庫が返品在庫(Return Inventory)の測定された寸法または重量を更新したときに送信されます。 category: completeRecalibrate / action: completeRecalibrate recalibrateSupplementの主要フィールド：

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

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

在庫メタデータ更新済み

倉庫またはユーザーが返品在庫(Return Inventory)にメタデータを追加または更新したときに送信されます。 category: updateReturnInventoryMeta / action: updateReturnInventoryMeta ペイロードには、更新されたreturnInventoryMetaListを含む、在庫作成済みと同じ構造のreturnInventoryが含まれています。 metaTypeの値：

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

RMA更新済み

倉庫が誤ったRMAの割り当てを修正したときに送信されます。 category: notifyUserRmaSwapped / action: notifyUserRmaSwapped payloadの主要フィールド：

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

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

SKU更新済み

販売者が返品在庫(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フィールドを含む、在庫処理完了と同じ構造に従います。

ラインアイテム分割

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	新しい在庫レコード（在庫処理完了と同じ構造）
`returnRequestLineItemSupplement`	object	新しいラインアイテムの寸法と重量を含む補足

倉庫備考更新済み

倉庫が返品リクエストの備考を更新したときに送信されます。 category: warehouseUpdateWarehouseRemarks / action: warehouseUpdateWarehouseRemarks ペイロードには3つのオブジェクトが含まれています：

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

購入者返品ラベル生成済み

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

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

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`	カスタムフィールド

Shopify購入者返品作成済み

購入者が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`	カスタムフィールド

統合配送コスト更新済み

統合配送注文の配送コストが更新されたときに送信されます。 category: consolidateShippingOrderShippingFeeUpdated / action: consolidateShippingOrderShippingFeeUpdated orderの主要フィールド：

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

統合配送すべて梱包済み

倉庫が統合注文のすべての在庫をボックスに梱包したときに送信されます。 category: consolidateShippingOrderInventoryAllPacked / action: consolidateShippingOrderInventoryAllPacked orderの主要フィールド：

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

shipmentListの各アイテム：

フィールド	説明
`consolidateShippingShipmentId`	配送識別子
`consolidateShippingShipmentNumber`	配送番号
`consolidateShippingShipmentStatus`	配送ステータス
`boxList`	この配送のボックスリスト

boxListの各アイテム：

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

consolidateShippingInventoryListの各アイテム：

フィールド	説明
`consolidateShippingInventoryId`	明細識別子
`itemType`	`RMA` または `FNSKU`
`returnInventoryId` / `rma`	`RMA` 明細のみ。それ以外は `null`
`fnsku`	`FNSKU` 明細のみ。それ以外は `null`
`quantity`	この箱の中の明細の個数。`RMA` 明細は常に `1`
`consolidateShippingInventoryStatus`	明細のステータス

箱には RMA 明細、FNSKU 明細、またはその両方が入ります。RMA 明細のない箱も一覧に含まれます。

統合配送発送済み

倉庫が統合配送をキャリアに発送したときに送信されます。 category: consolidateShippingShipmentSent / action: consolidateShippingShipmentSent shipmentの主要フィールド：

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

統合配送AWB更新済み

統合配送の航空貨物運送状番号が更新されたときに送信されます。 category: consolidateShippingShipmentShipped / action: consolidateShippingShipmentShipped shipmentオブジェクトは、更新されたawbフィールドを含む、統合配送発送済みと同じ構造に従います。 RH_WAREHOUSE の注文では、倉庫が AWB を記録したときにこのイベントが送信されます。consolidateShippingShipmentStatus は IN_TRANSIT で、この時点ではまだ請求されません。Shipment は到着時に請求され、統合配送到着済みで通知されます。

統合配送到着済み

RH_WAREHOUSE 注文の Shipment が Return Helper 倉庫に到着し、送料が請求されたときに、Shipment ごとに 1 回送信されます。 category: consolidateShippingShipmentArrived / action: consolidateShippingShipmentArrived / version: 202609

バージョン 202609 はオプトインです。受信するには Return Helper カスタマーサービスにお問い合わせください。

フィールド	説明
`order`	注文。`order.shipmentList` には到着した Shipment のみが含まれます。
`arrivedShipmentCount`	この注文の明細を含む Shipment のうち、到着済みの数（今回の Shipment を含む）
`totalShipmentCount`	この注文の明細を含む Shipment の数。空の Shipment は数えません。

明細を含む Shipment が 3 件ある注文では、1/3、2/3、3/3 の 3 件のイベントが送信されます。 order のフィールド：

フィールド	説明
`consolidateShippingOrderId` / `consolidateShippingOrderNumber`	注文の識別子
`apiId`	お客様のアカウント ID
`consolidateShippingOrderStatus`	注文ステータス
`outboundWarehouseId`	出荷元倉庫
`destinationType`	`RH_WAREHOUSE`
`destinationWarehouseId`	宛先倉庫
`shippingFee` / `currencyCode`	これまでの注文の送料
`customFieldMap` / `deliveryInstructions`	注文に設定された値
`shipmentList`	到着した Shipment（下記参照）

バージョン 202609 には shippingMethod は含まれません。 shipmentList の各項目：

フィールド	説明
`consolidateShippingShipmentId` / `consolidateShippingShipmentNumber`	Shipment の識別子
`consolidateShippingShipmentStatus`	`READY_TO_PICKUP`
`awb`	Air Waybill 番号
`chargeableWeight`	請求重量（グラム）
`boxList`	この Shipment の箱。各箱に `consolidateShippingShipmentBoxId`、`boxNumber`、`consolidateShippingShipmentBoxStatus`、`consolidateShippingInventoryList` が含まれます

consolidateShippingInventoryList の各項目：

フィールド	説明
`consolidateShippingInventoryId`	明細識別子
`itemType`	`RMA` または `FNSKU`
`returnInventoryId` / `rma`	`RMA` 明細のみ。それ以外は `null`
`fnsku`	`FNSKU` 明細のみ。それ以外は `null`
`quantity`	この箱の中の個数
`consolidateShippingInventoryStatus`	明細のステータス

{
  "category": "consolidateShippingShipmentArrived",
  "action": "consolidateShippingShipmentArrived",
  "eventTime": "2026-10-05T03:12:45Z",
  "version": "202609",
  "notificationId": "01K6X2M8Q4R7T9V1W3Y5Z7B9C1",
  "order": {
    "consolidateShippingOrderId": "01K6RA4F7H9J2K5M8N1P3Q6S8T",
    "consolidateShippingOrderNumber": "CNS260928-0000123",
    "apiId": 12345,
    "consolidateShippingOrderStatus": "PARTIALLY_SHIPPED",
    "outboundWarehouseId": 101,
    "destinationType": "RH_WAREHOUSE",
    "destinationWarehouseId": 1,
    "shippingFee": 27.0,
    "currencyCode": "usd",
    "customFieldMap": {},
    "deliveryInstructions": null,
    "shipmentList": [
      {
        "consolidateShippingShipmentId": "01K6T1B3D5F7H9K2M4P6R8T0V2",
        "consolidateShippingShipmentNumber": "CNSS260930-0000045",
        "consolidateShippingShipmentStatus": "READY_TO_PICKUP",
        "awb": "TRACK123456789",
        "chargeableWeight": 2400,
        "boxList": [
          {
            "consolidateShippingShipmentId": "01K6T1B3D5F7H9K2M4P6R8T0V2",
            "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
            "boxNumber": "1",
            "consolidateShippingShipmentBoxStatus": "SHIPPED",
            "consolidateShippingInventoryList": [
              {
                "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
                "consolidateShippingInventoryId": "01K6RB2C4E6G8J1L3N5Q7S9U1W",
                "itemType": "RMA",
                "returnInventoryId": 987654,
                "rma": "USE-2-260915-D00003-30",
                "fnsku": null,
                "quantity": 1,
                "consolidateShippingInventoryStatus": "SHIPPED"
              },
              {
                "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
                "consolidateShippingInventoryId": "01K6RB3D5F7H9K2M4P6R8T0V2X",
                "itemType": "FNSKU",
                "returnInventoryId": null,
                "rma": null,
                "fnsku": "X00EXAMPLE1",
                "quantity": 6,
                "consolidateShippingInventoryStatus": "SHIPPED"
              }
            ]
          }
        ]
      }
    ]
  },
  "arrivedShipmentCount": 1,
  "totalShipmentCount": 2
}

統合注文完了

統合注文のすべての明細が出荷されたときに送信されます。RH_WAREHOUSE の注文では、明細を含むすべての Shipment も到着している必要があり、このイベントは注文の最後の統合配送到着済みの後に送信されます。 category: consolidateShippingOrderCompleted / action: consolidateShippingOrderCompleted orderオブジェクトは、boxListと在庫詳細を含む完全なshipmentListを含む、統合配送すべて梱包済みと同じ構造に従います。

統合注文キャンセル

倉庫が統合配送注文を強制キャンセルしたときに送信されます。 category: consolidateShippingOrderCancelled / action: consolidateShippingOrderCancelled orderの主要フィールド：

フィールド	説明
`consolidateShippingOrderId`	注文識別子
`consolidateShippingOrderNumber`	注文番号
`consolidateShippingOrderStatus`	`CANCELED`
`outboundWarehouseId`	出荷倉庫
`shippingMethod`	常に `null`
`shippingFee`	配送料
`deliveryInstructions`	配送指示
`customFieldMap`	カスタムフィールド

取引追加済み

お客様のアカウントに取引が計上されるたびに 1 回送信されます。対象は課金、返金、再課金、トップアップです。

apiTransaction.notes には通常、その取引の対象となった操作の説明が含まれるため、headId を解決しなくても取引の内容を把握できます。

category: transaction / action: addTransaction / version: 202610 apiTransactionの主要フィールド：

フィールド	タイプ	説明
`apiTransactionId`	long	取引識別子
`transactionNumber`	string	取引番号（例：`T2600012345`）。取引ごとに一意です。
`apiId`	long	お客様の API アカウント ID
`currencyCode`	string	通貨コード、小文字（例：`usd`）
`transactionType`	string	取引タイプコード。名称は取引タイプをすべて取得を参照
`headId`	string	取引の計上先となったレコードの ID。`transactionType` によって異なります。headId が指すものを参照してください。
`amount`	number	符号付きの金額。負の値は課金、正の値は返金またはトップアップです。
`notes`	string	人が読むための説明。文言は変更される場合があるため、解析しないでください。
`createOn`	string	取引が計上された日時（UTC、ISO 8601）
`createBy`	string

apiBalanceの主要フィールド：

フィールド	タイプ	説明
`apiBalanceId`	long	残高レコード識別子
`apiId`	long	お客様の API アカウント ID
`currencyCode`	string	通貨コード、小文字
`balance`	number	この取引が計上された直後の、`currencyCode` での残高

balance はこの取引が計上された時点の値であり、現在の残高ではありません。イベントは順不同で届く場合があります。現在の残高は API アカウント残高を取得で取得してください。

{
  "apiTransaction": {
    "apiTransactionId": 100245,
    "transactionNumber": "T2600012345",
    "apiId": 21,
    "currencyCode": "usd",
    "transactionType": "csl",
    "headId": "11345",
    "amount": -12.960,
    "notes": "charge for shipment:30385",
    "createOn": "2026-10-12T03:29:11.180251",
    "createBy": "21"
  },
  "apiBalance": {
    "apiBalanceId": 7,
    "apiId": 21,
    "currencyCode": "usd",
    "balance": 1520.350
  },
  "category": "transaction",
  "action": "addTransaction",
  "eventTime": "2026-10-12T03:29:11.2396605Z",
  "version": "202610",
  "notificationId": "01J8HV4X54S8AV4FY0SJKVM7QW"
}

headId が指すもの

下表で transactionType を探し、記載のイベントまたはレスポンスで取得済みの ID と headId を照合してください。headId は常に文字列です。返金または再課金の headId は、調整対象の課金と同じです。

`headId` の内容	`transactionType`	この ID の取得元
お客様の `apiId`	`chr`, `top`, `acs`, `acf`, `rtp`	`RETURNHELPER-API-ID` ヘッダー、または API アカウント情報を取得
`labelId`	`csl`, `rcl`, `RECHARGE_SHIPPING_LABEL`, `rsl`¹	ラベル結果の `label.labelId`
`returnRequestId`	`bps`, `brt`, `sps`, `REFUND_CANCEL_BUYER_RETURN_LABEL`, `REFUND_CANCEL_SHOPIFY_RETURN_LABEL`, `rsl`¹	購入者返品ラベル生成済み、Shopify購入者返品作成済み
`returnInventoryId`	`bbc`, `brc`, `fbr`, `cup`, `dis`, `soh`, `swh`, `CANCELED_LABEL_ARRIVED`, `CANCELED_LABEL_PENALTY`, `CONSOLIDATE_SHIPPING_OUTBOUND`	在庫作成済み、倉庫配送到着（v2）
`returnInventoryId`	`REFUND_` / `RECHARGE_` + `CLAIM_UNKNOWN`, `BUYER_RETURN`, `BOUNCE_BACK`, `FBA_RESTOCK`, `CANCELED_LABEL_ARRIVED`, `CANCELED_LABEL_PENALTY`	同上
`returnRequestLineItemVasId`	`rpk`, `tpc`, `pin`	VAS更新
`resendId`	`rmh`, `rlr`	Resend Order を作成のレスポンス、再送ステータス更新
再送在庫レコード ID	`rsh`	どの API レスポンスや Webhook でも返されません
`fbaInstructionId`	`fbd`, `frh`	FBA Instructions を作成のレスポンス
`fbaShipmentId`	`fih`, `fch`	FBA Shipment を作成のレスポンス
`consolidateShippingShipmentBoxId`	`CONSOLIDATE_SHIPPING_MERGE`	統合配送すべて梱包済みの `boxList`
`consolidateShippingInventoryId`	`CONSOLIDATE_SHIPPING_OUTBOUND_FNSKU`	統合配送すべて梱包済みの `consolidateShippingInventoryList`
`consolidateShippingShipmentId`	`CONSOLIDATE_SHIPPING_SHIPMENT`	統合配送発送済み

¹ rsl は生成に失敗したラベルの返金です。headId は labelId ですが、失敗したラベルが購入者返品ラベルの場合は returnRequestId です。

すべての取引が送信されます。個別のタイプのみを購読することはできません。transactionType と amount の符号で処理を分岐してください。
新しい transactionType の値が追加される場合があります。認識できないタイプでも amount と balance は記録し、イベントを拒否しないでください。
1 つの配送に複数のラベルが存在することがあるため、csl も複数になる場合があります。labelId と shipmentId の対応付けにはラベル結果を使用してください。
createOn は取引が計上された日時、eventTime は通知が送信された日時です。

​概要

​Webhookエンドポイントの設定

​エンドポイントの要件

​エンドポイントの登録

​イベント配信

​通知ヘッダー

​旧ヘッダー

​署名の検証

​詳細な例

​ステップバイステップの検証

​サンプルコード

​再試行メカニズム

​共通ボディフィールド

​通知イベントリファレンス

​通知ペイロード

​ラベル結果

​地域別ラベルURL

​倉庫配送到着（v2）

​在庫作成済み

​画像更新済み

​不明な配送が割り当てられた

​リコールステータス更新

​再送ステータス更新

​VAS更新

​在庫処理完了

​在庫再校正済み

​在庫メタデータ更新済み

​RMA更新済み

​SKU更新済み

​ラインアイテム分割

​倉庫備考更新済み

​購入者返品ラベル生成済み

​Shopify購入者返品作成済み

​統合配送コスト更新済み

​統合配送すべて梱包済み

​統合配送発送済み

​統合配送AWB更新済み

​統合配送到着済み

​統合注文完了

​統合注文キャンセル

​取引追加済み

​headId が指すもの

概要

Webhookエンドポイントの設定

エンドポイントの要件

エンドポイントの登録

イベント配信

通知ヘッダー

旧ヘッダー

署名の検証

詳細な例

ステップバイステップの検証

サンプルコード

再試行メカニズム

共通ボディフィールド

通知イベントリファレンス

通知ペイロード

ラベル結果

地域別ラベルURL

倉庫配送到着（v2）

在庫作成済み

画像更新済み

不明な配送が割り当てられた

リコールステータス更新

再送ステータス更新

VAS更新

在庫処理完了

在庫再校正済み

在庫メタデータ更新済み

RMA更新済み

SKU更新済み

ラインアイテム分割

倉庫備考更新済み

購入者返品ラベル生成済み

Shopify購入者返品作成済み

統合配送コスト更新済み

統合配送すべて梱包済み

統合配送発送済み

統合配送AWB更新済み

統合配送到着済み

統合注文完了

統合注文キャンセル

取引追加済み

headId が指すもの