Oversell Status — 売越しケース受付完了通知

Oversell Cases（/api/routing/oversell-case）で売越しケースが MFC 倉庫で受付完了（warehouse_received）に遷移したときに通知します。1 ケース = 1 販売単位（fulfillment unit）なので 1 遷移 = 1 通です。確保元ロケーション（found_location_id）からの出庫分が MFC センターで受付完了したことを外部システムへ伝え、スマレジ等への入庫処理を実行する用途を想定しています（商品解決は barcode 経由）。

Base URL https://api.lmile.io · 認証 x-ingest-secret ヘッダー（詳細） · shop はリクエストボディに含めます（省略するとキーのアカウント）

配信・リトライ・暗号化など共通の仕組みは Webhooks 概要を参照。

エンドポイント

Method	Path	用途
POST	/api/routing/oversell-status-webhook-config	shop 単位の売越しケース受付完了 webhook 送信先設定を登録 / 更新（upsert）

---

POST /api/routing/oversell-status-webhook-config

shop 単位で設定を upsert します。

リクエスト

POST https://api.lmile.io/api/routing/oversell-status-webhook-config
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json

{
  "shop": "demo-store.myshopify.com",
  "destinationUrl": "https://sync.example.com/oversell/warehouse-received",
  "authType": "bearer",
  "authSecret": "sync-api-token-xxxxx",
  "payloadTemplate": {
    "order": "{{externalOrderRef}}",
    "case": "{{oversellCaseId}}",
    "receivedLocation": "{{foundLocationId}}",
    "items": "{{lines}}"
  },
  "isActive": true
}

設定後は、/api/routing/oversell-case でケースが warehouse_received に遷移するたびに、oversellCaseId / foundLocationId / lines（barcode 単位）等を宛先へ自動 POST します（操作レスポンスは待たせずバックグラウンド送信）。

ボディパラメータ

共通パラメータのみです（固有パラメータなし）。

ペイロードテンプレート

利用可能な変数:

変数	説明
shop	店舗ドメイン
routingOrderId	ルーティング注文 id（sot.lm_routing_orders.id）
oversellCaseId	売越しケース id（sot.lm_oversell_cases.id。受信側の冪等キーに使えます）
fulfillmentUnitId	対象の販売単位 id（sot.lm_fulfillment_units.id）
externalOrderRef / sourceSystem	外部注文参照 / 取込元（注文ヘッダ由来。相関用）
foundLocationId	確保元（出庫元）= 受領（入庫）元ロケーション id（sot.lm_oversell_cases.found_location_id。未設定は null）
status	常に warehouse_received（本 webhook は受付完了の 1 種別のみ）
tag	ディスパッチ先選択タグ
warehouseReceivedAt	ケースの受付完了時刻（ISO8601）
changedAt	通知生成時刻（ISO8601）
lines	このケースの明細 [{ "barcode", "sku", "productName", "quantity" }]。1 ケース = 1 単位のため 1 行（quantity は常に 1）。商品情報（sku / productName）は sot.products を barcode で解決（未登録は null）。単一変数 "{{lines}}" で配列のまま描画

省略時の既定テンプレート:

{
  "event": "oversell_case_warehouse_received",
  "shop": "{{shop}}",
  "routingOrderId": "{{routingOrderId}}",
  "oversellCaseId": "{{oversellCaseId}}",
  "fulfillmentUnitId": "{{fulfillmentUnitId}}",
  "externalOrderRef": "{{externalOrderRef}}",
  "sourceSystem": "{{sourceSystem}}",
  "foundLocationId": "{{foundLocationId}}",
  "status": "{{status}}",
  "tag": "{{tag}}",
  "warehouseReceivedAt": "{{warehouseReceivedAt}}",
  "changedAt": "{{changedAt}}",
  "lines": "{{lines}}"
}

lines の描画例（1 ケース = 1 単位 = 1 行、quantity は常に 1）:

"lines": [
  { "barcode": "4900000000011", "sku": "TSHIRT-WH-M", "productName": "コットンTシャツ ホワイト M", "quantity": 1 }
]

レスポンス

{ "ok": true, "id": "c0ffee00-...", "shop": "demo-store.myshopify.com",
  "is_active": true, "has_secret": true }

フィールド	説明
id	設定行 id（sot.lm_oversell_status_webhook_config.id）
has_secret	認証 secret が保存済か（secret 値そのものは返しません）

挙動

• 発火タイミング: /api/routing/oversell-case でケースが warehouse_received（8 ステップ目の MFC 倉庫受付完了）に遷移した直後にバックグラウンド送信します。他のステップ遷移（locating / contacted / stock_secured 等）では発火しません
• 絶対状態の送信: status は常に warehouse_received です。受け手は oversellCaseId を冪等キーに、確保元（foundLocationId）からの出庫分の入庫を冪等に反映できます
• 明細（lines）の snapshot: 明細は起票時点の barcode に商品情報（sku / productName）を付与して outbox に snapshot し、送信時に再取得しません。1 ケース = 1 販売単位のため常に 1 行・quantity: 1 です
• 冪等性: outbox は UNIQUE (oversell_case_id) のため、同一ケースのイベントは 1 件しか起票しません（二重発行を防止）。warehouse_received は終端ステップで再遷移できないため、通常は 1 ケースにつき 1 通だけ届きます

エラー

エンドポイント固有のエラーはありません。共通エラーは Webhooks 概要 / Error Codes を参照。

データモデル

• sot.lm_oversell_status_webhook_config — shop 単位の送信設定（UNIQUE (shop)）
• sot.lm_oversell_status_events — ケース受付完了イベント outbox + 送信ログ（oversell_case_id / found_location_id / lines snapshot / warehouse_received_at を記録。UNIQUE (oversell_case_id)）
• 遷移の元: sot.lm_oversell_cases（売越し 8 ステップ管理）の status 列が warehouse_received になった瞬間