Oversell Cases — 売越しケース
Units の単位が売越し（在庫が引き当て先に無く、別ロケーションから調達して出荷する）になったとき、その現場オペを 8 ステップで追うケース管理です。1 単位につき 1 ケースを起票し、単一の advance エンドポイントで状態を前進させます。
Base URL
https://api.lmile.io· 認証x-ingest-secretヘッダー または operator JWT（Authorization: Bearer）（詳細） ·shopはリクエストボディに含めます（API キーで呼ぶ場合は省略できます）
/api/routing/oversell-caseは機械間 secret（x-ingest-secret）と倉庫スタッフの operator JWT のどちらでも呼べます（系統はヘッダの有無で明示判別。詳細）。operator JWT 経由は起票者 / 前進操作者を記録します。
Oversell / Reallocate（LM-498）の同一出荷元内の自動再引き当てとは別経路です。売越しケースは「別ロケーションを探して連絡・確保・出庫・追跡番号・MFC 受付」という現場フローを追うもので、
lm_routing_decisions.oversoldフラグは触りません（両者は独立して共存）。
ステップ（status）
case_opened
1: 売越発生（起票）
unit → oversell_pending
locating
2: 在庫があるロケーションを探す
found_location_id（任意）
contacted
3: 在庫があるロケーションに連絡
contacted_at
stock_secured
4: 在庫確保（無ければ locating へ戻る）
secured_at / unit → oversell_secured
dispatch_requested
5: 出庫依頼を立てる
dispatch_requested_at
dispatched
6: 出庫処理を現場で行う
dispatched_at / unit → oversell_returning
tracking_reported
7: 追跡番号を現場が連絡
tracking_number（必須）
warehouse_received
8: MFC センターで受付完了
warehouse_received_at / unit → oversell_warehouse_received
wont_do
中止（確保不能等）
wont_do_at / wont_do_reason
遷移は 1 ステップ前進が基本。stock_secured → locating の戻り（再探索）と、warehouse_received 以外からの wont_do（中止）のみ追加で許可します。それ以外のジャンプは 409 invalid_transition。
エンドポイント
POST
/api/routing/oversell-case
売越しケースの起票 + 前進（単一 advance）
POST /api/routing/oversell-case
対象単位のケースが無ければ起票（case_opened）し、あれば指定 status へ前進します。toStatus 省略時は 1 ステップ前進。
リクエスト
ボディパラメータ
shop
string
✓
店舗ドメイン（API キーで呼ぶ場合は省略できます）
routingOrderId
string (uuid)
△
対象注文。無ければ sourceSystem + externalOrderRef で特定
sourceSystem / externalOrderRef
string
△
routingOrderId 未指定時に必須
fulfillmentUnitId
string (uuid)
△
対象単位。無ければ barcode + lineInstanceNo で特定
barcode / lineInstanceNo
string / number
△
fulfillmentUnitId 未指定時に必須
toStatus
string
目標 status（省略 = 1 ステップ前進）
fields.foundLocationId
string (uuid)
在庫が見つかった/確保した出庫元ロケーション
fields.trackingNumber
string
追跡番号（tracking_reported で必須）
fields.externalShipmentRef
string
出庫元の外部出荷 ID（smaregi 出荷 ID 等）
fields.wontDoReason
string
中止理由（wont_do 用）
fields.note
string
任意メモ
レスポンス
caseId
売越しケース id（sot.lm_oversell_cases.id）
status
更新後のケース status
unitStatus
連動して更新された単位の売越サブ状態（wont_do 時は変化なし）
opened
この呼び出しで起票したか
changed
状態が変化したか（同一 status への再呼び出しは false）
挙動・冪等性
初回呼び出しでケースが無ければ起票し、単位を
oversell_pendingにします。各ステップの timestamp / フィールドを自動記録し、対応する単位の売越サブ状態を更新します（
wont_doは単位を変更しません）。同一 status への再呼び出しは
changed: falseの no-op（timestamp 再設定なし）。tracking_reportedはfields.trackingNumber必須（無ければ400）。LM-498 の
oversoldフラグ・/api/routing/reallocateには影響しません（routing_decision_idは traceability のため保持するのみ）。
エラー
エンドポイント固有:
400
注文・単位の特定情報なし / tracking_reported で追跡番号欠落
{ "ok": false, "error_kind": "invalid_input", "error": "fields.trackingNumber required for tracking_reported" }
404
注文・単位が存在しない
{ "ok": false, "error_kind": "unit_not_found", "error": "fulfillment unit not found for order" }
409
不正なステップ遷移
{ "ok": false, "error_kind": "invalid_transition", "error": "cannot move oversell case from case_opened to dispatched" }
共通エラー（401 / 400 / 403 / 405 / 500 / 503）は Error Codes を参照。
データモデル
sot.lm_oversell_cases— 1 ケース = 1 単位（UNIQUE shop + fulfillment_unit_id）。status（8 ステップ +wont_do）/found_location_id/tracking_number/external_shipment_ref/wont_do_reason+ 各ステップ timestamp。fulfillment_unit_id（Units）とrouting_decision_idにリンク。読み取り view:public.lm_v_oversell_cases単位の売越サブ状態は
sot.lm_fulfillment_units.status（oversell_pending/oversell_secured/oversell_returning/oversell_warehouse_received）に反映
Last updated
Was this helpful?