Fulfillment Status — 出荷ステータス通知

Fulfillment のステータス報告・確保フロー（在庫確保 / 確保スキャン）で各出荷元（shipment）のステータスが変わったとき（allocated → secured → in_transit_to_mfc → packing → shipped ＋ 売越サブ状態、初回報告を含む）に通知します。出荷ステータス・追跡番号を Shopify 等の EC や外部 OMS へ反映する用途を想定しています。

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

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

エンドポイント

Method	Path	用途
POST	/api/routing/status-webhook-config	shop 単位（任意で取込元 sourceSystem ごと）の出荷ステータス変動 webhook 送信先設定を登録 / 更新（upsert）

---

POST /api/routing/status-webhook-config

shop 単位（任意で取込元 sourceSystem ごと）で設定を upsert します。

リクエスト

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

{
  "shop": "demo-store.myshopify.com",
  "destinationUrl": "https://sync.example.com/fulfillment/status",
  "authType": "bearer",
  "authSecret": "sync-api-token-xxxxx",
  "payloadTemplate": {
    "order": "{{externalOrderRef}}",
    "status": "{{status}}",
    "tracking": "{{trackingNumber}}"
  },
  "isActive": true
}

設定後は、/api/routing/fulfillment で各出荷元の status が変わるたび（初回報告含む）に、status / previousStatus / trackingNumber / shipmentId / lines（出荷明細の barcode 単位集約）等を宛先へ自動 POST します（注文レスポンスは待たせずバックグラウンド送信）。

ボディパラメータ

共通パラメータに加えて:

パラメータ	型	必須	説明
sourceSystem	string		設定を適用する取込元（イベントの sourceSystem と一致させる値）。省略（または空文字）するとその shop の既定宛先の設定になります

ペイロードテンプレート

利用可能な変数:

変数	説明
shop	店舗ドメイン
routingOrderId	ルーティング注文 id（sot.lm_routing_orders.id）
shipmentId	出荷元ヘッダ id（sot.lm_fulfillment_shipments.id。受信側の冪等キーに使えます）
externalOrderRef / sourceSystem	外部注文参照 / 取込元（注文ヘッダ由来。相関用）
fromLocationId	出荷元（在庫ロケーション）id
status	遷移後ステータス
previousStatus	直前ステータス（初回報告は null）
trackingNumber / carrierCode	遷移時点の追跡番号 / キャリア（確保時に採番。未採番は null）
trackingCompany / trackingUrl	出荷済みにするときに手入力された配送業者の名前 / 追跡ページの URL（指定が無ければ null）
tag	ディスパッチ先選択タグ
transitionedAt	遷移検知時刻（ISO8601）
changedAt	通知生成時刻（ISO8601）
lines	この shipment の出荷明細（sot.lm_fulfillment_units を barcode 単位に集約した [{ "barcode", "sku", "quantity" }]。単一変数 "{{lines}}" で配列のまま描画）。shipped 遷移では注文の非在庫サービス品（ショッパーバッグ等の同梱品）の barcode / 数量も合流する（下記「挙動」参照）

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

{
  "event": "fulfillment_shipment_status_changed",
  "shop": "{{shop}}",
  "routingOrderId": "{{routingOrderId}}",
  "shipmentId": "{{shipmentId}}",
  "externalOrderRef": "{{externalOrderRef}}",
  "sourceSystem": "{{sourceSystem}}",
  "fromLocationId": "{{fromLocationId}}",
  "status": "{{status}}",
  "previousStatus": "{{previousStatus}}",
  "trackingNumber": "{{trackingNumber}}",
  "carrierCode": "{{carrierCode}}",
  "trackingCompany": "{{trackingCompany}}",
  "trackingUrl": "{{trackingUrl}}",
  "tag": "{{tag}}",
  "transitionedAt": "{{transitionedAt}}",
  "changedAt": "{{changedAt}}",
  "lines": "{{lines}}"
}

lines の描画例（barcode 単位に集約。1 行 = 1 barcode、quantity はその shipment 内の単位数）:

"lines": [
  { "barcode": "4900000000011", "sku": "TSHIRT-WH-M", "quantity": 2 },
  { "barcode": "4900000000028", "sku": "TSHIRT-WH-L", "quantity": 1 }
]

レスポンス

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

フィールド	説明
id	設定行 id（sot.lm_fulfillment_status_webhook_config.id）
source_system	この設定が適用される取込元（既定宛先の設定は null）
has_secret	認証 secret が保存済か（secret 値そのものは返しません）

挙動

• 遷移検知: /api/routing/fulfillment で各 shipment（routing_order × from_location）の status を更新する際、直前の値と異なる shipment だけイベントを起票します（初回報告 = previousStatus: null も対象）。同じ status の再報告では送信しません
• 取込元（sourceSystem）ごとの宛先: 取込元ごとに宛先を分けられます。sourceSystem 指定なしの設定はその shop の既定宛先です。イベントは自分の取込元と一致する設定があればそちらへ、なければ既定宛先へ届きます（どちらも無い場合は送信せず skipped を記録します）
• 確保（secured）遷移も対象: 確保フロー（在庫確保 /api/routing/secure・確保スキャン /api/operator/secure-scan・追跡番号で確保 /api/operator/secure-by-tracking）でヘッダが secured に遷移したときも、同じペイロード形・同じ outbox でイベントを起票・配信します（status: "secured"・previousStatus は遷移前のヘッダ status）。secured 以外のステータスだけを処理する受け手には新しい status 値が届くだけで後方互換です
• 絶対状態の送信: ペイロードは遷移後の絶対状態（status / previousStatus / trackingNumber）と出荷明細（shipmentId / lines）です。受け手は shipmentId を冪等キーに同一 shipment の再送を弾きつつ、該当明細だけを冪等に反映できます
• 明細（lines）の組み立て: 送信時に shipment 配下の sot.lm_fulfillment_units を barcode 単位に集約して同梱します。units の取得に失敗した場合・0 件の場合は lines 無しのまま送信せず delivery_status: failed（last_error: units_fetch_error / no_units_for_shipment）として outbox に残し、再送で回収します
• shipped は非在庫サービス品も lines に含む: 注文に非在庫サービス品（products.is_non_inventory = true。ショッパーバッグ等の同梱品・刻印等のサービス行）がある場合、shipped 遷移の lines にはその barcode / 数量も合流します（在庫引き当て対象外で unit を持たないため、適用中 routing decision から補完）。routing に送られた明細は出荷済み反映の対象、という契約です。受け手が明細を残数ベースで冪等に反映していれば、複数出荷元に分割された注文でも最初の出荷 1 回だけに反映されます。shipped 以外の遷移の lines は従来どおり unit 由来のみです
• 配信タイミング: /api/routing/fulfillment / 確保フローの成功直後にバックグラウンド送信

エラー

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

データモデル

• sot.lm_fulfillment_status_webhook_config — shop × 取込元単位の送信設定（UNIQUE NULLS NOT DISTINCT (shop, source_system)。source_system が NULL の行 = その shop の既定宛先）
• sot.lm_fulfillment_status_events — status 遷移イベント outbox + 送信ログ（status_before / status_after / tracking_number を記録）
• 遷移の元: sot.lm_fulfillment_shipments（出荷元ヘッダ = 梱包単位 / 注文 × from_location）の status 列