Webhookと通知 - Return Helper API

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

概要

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

Webhookエンドポイントの設定

エンドポイントの要件

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

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

エンドポイントの登録

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

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

メールテンプレート（フォームを使用できない場合）

メールで連絡する場合は、support@returnhelper.comに以下を送信し、paco@returnhelper.com、tingfung@returnhelper.com、roy@returnhelper.comにCCしてください：

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

To: support@returnhelper.com
CC: paco@returnhelper.com, tingfung@returnhelper.com, roy@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>

イベント配信

タイミング — イベントはトリガーアクションの数秒後に届く場合があり、まれに数分後になることがあります。 重複イベント — エンドポイントが同じイベントを複数回受信する場合があります。冪等性(Idempotency)のある処理を実装してください（例：処理済みのeventTime + notificationIdの組み合わせを追跡する）。 イベントの順序 — 配信順序は保証されていません。任意の順序でイベントを処理できるようにハンドラーを設計してください。たとえば、inventoryCreatedがwarehouseMarkShipmentArrivedV2より前に届く場合があります。順序外で受信したイベントで参照されているオブジェクトを取得するには、APIを使用してください。各イベントにはISO 8601形式のeventTimeフィールドが含まれています。

通知ヘッダー

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

ヘッダー	タイプ	説明
`timestamp`	string	ISO 8601タイムスタンプ
`returnhelper-signature`	string	検証用HMAC-SHA256署名

署名の検証

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

署名キーはReturn Helperから提供されます（Base64エンコードされています）。安全に保管し、公開しないでください。

詳細な例

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

{
  "content-type": "application/json; charset=utf-8",
  "returnhelper-signature": "gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=",
  "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 — ヘッダーから署名を抽出する（最後の比較用）：

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

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

2024-01-12T09:23:08.4863561Z

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

HTTPメソッド：POST
通知エンドポイントURL：https://s2024-01-12.free.beeceptor.com
ステップ2のタイムスタンプ
生の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 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);
  }
}

再試行メカニズム

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

共通ボディフィールド

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

フィールド	タイプ	説明
`category`	string	通知カテゴリ（以下の表を参照）
`action`	string	特定のイベントアクション
`eventTime`	string	イベントのISO 8601タイムスタンプ
`version`	string	通知スキーマバージョン
`notificationId`	string	一意の通知ID（新しい通知に存在）

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

通知	`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が更新された
統合注文完了	`consolidateShippingOrderCompleted`	`consolidateShippingOrderCompleted`	統合注文のすべての配送が発送された
統合注文キャンセル	`consolidateShippingOrderCancelled`	`consolidateShippingOrderCancelled`	統合注文が倉庫によって強制キャンセルされた

通知ペイロード

ラベル結果

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

ラベルをシステム内の配送にマッチさせるには必ず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へのマップ

成功例：

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

失敗例：

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

倉庫配送到着（v2）

倉庫が配送を受領済みとしてマークしたときに送信されます。常に1つ以上の在庫作成済みイベントが続きます。 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つの配送で複数のイベントが生成される場合があります。 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",
    "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"
}

画像更新済み

返品在庫(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://example.com/return-image-1.png"
  ],
  "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"
}

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

返品リクエストのない配送が識別され、販売者に割り当てられたときに送信されます。 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`	最終変更タイムスタンプ

リコールステータス更新

リコール追跡番号が更新されるか、集荷ステータスが変更されたときに送信されます。 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	再送注文の詳細（以下を参照）
`trackingNumber`	string	追跡番号（利用可能な場合）
`failureReason`	string	失敗理由（再送が失敗した場合）

resendの主要フィールド：

フィールド	説明
`resendId`	一意の再送注文識別子
`apiId`	販売者API ID
`resendNumber`	再送注文番号
`resendStatusCode`	現在のステータス：`1` — 保留中、`2` — 処理中、`3` — 完了、`4` — 失敗
`description`	注文の説明
`remarks`	販売者の備考
`warehouseRemarks`	倉庫の備考

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

3 — 完了（trackingNumberを確認）
4 — 失敗（failureReasonを確認）

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": 1468,
      "vasResult": "VAS result details",
      "weight": 500.0,
      "weightUom": "g",
      "dimension1": 10.0,
      "dimension2": 20.0,
      "dimension3": 30.0,
      "dimensionUom": "cm",
      "vasStatusCode": 1,
      "imageUrlList": null
    }
  ],
  "category": "rrliv",
  "action": "vasUpdated",
  "eventTime": "2021-07-06T12:15:55.9038524Z"
}

在庫処理完了

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

統合配送発送済み

倉庫が統合配送をキャリアに発送したときに送信されます。 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フィールドを含む、統合配送発送済みと同じ構造に従います。

統合注文完了

統合注文のすべての配送が発送されたときに送信されます。 category: consolidateShippingOrderCompleted / action: consolidateShippingOrderCompleted orderオブジェクトは、boxListと在庫詳細を含む完全なshipmentListを含む、統合配送すべて梱包済みと同じ構造に従います。

統合注文キャンセル

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

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

イベント

​概要

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

​エンドポイントの要件

​エンドポイントの登録

​イベント配信

​通知ヘッダー

​署名の検証

​詳細な例

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

​サンプルコード

​再試行メカニズム

​共通ボディフィールド

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

​通知ペイロード

​ラベル結果

​倉庫配送到着（v2）

​在庫作成済み

​画像更新済み

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

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

​再送ステータス更新

​VAS更新

​在庫処理完了

​在庫再校正済み

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

​RMA更新済み

​SKU更新済み

​ラインアイテム分割

​倉庫備考更新済み

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

​Shopify購入者返品作成済み

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

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

​統合配送発送済み

​統合配送AWB更新済み

​統合注文完了

​統合注文キャンセル

概要

Webhookエンドポイントの設定

エンドポイントの要件

エンドポイントの登録

イベント配信

通知ヘッダー

署名の検証

詳細な例

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

サンプルコード

再試行メカニズム

共通ボディフィールド

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

通知ペイロード

ラベル結果

倉庫配送到着（v2）

在庫作成済み

画像更新済み

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

リコールステータス更新

再送ステータス更新

VAS更新

在庫処理完了

在庫再校正済み

在庫メタデータ更新済み

RMA更新済み

SKU更新済み

ラインアイテム分割

倉庫備考更新済み

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

Shopify購入者返品作成済み

統合配送コスト更新済み

統合配送すべて梱包済み

統合配送発送済み

統合配送AWB更新済み

統合注文完了

統合注文キャンセル