MFC Inventory — MFC 入庫（棚付き）

大阪 MFC などの出荷元の自己ロケーションに、棚番号付きの在庫を入庫します。1 リクエストで、棚ごとの在庫と、商品ごとの販売可能在庫（全棚の合算）が同時に更新されます。商品は barcode、棚は shelfCode、ロケーションは出荷元ロケーション id で解決します。

Base URL https://api.lmile.io · 認証 x-ingest-secret ヘッダー または operator JWT（Authorization: Bearer）（詳細） · shop はリクエストボディに含めます（API キーで呼ぶ場合は省略できます）

/api/ingest/mfc-inventory は機械間 secret（x-ingest-secret）と倉庫スタッフの operator JWT のどちらでも呼べます（系統はヘッダの有無で明示判別。詳細）。operator JWT 経由では、誰が入庫したかが棚在庫の増減ログに記録されます（機械間経由では記録されません）。

エンドポイント

Method	Path	用途	テーブル
POST	/api/ingest/mfc-inventory	出荷元ロケーションへ棚付き在庫を入庫（mode=absolute 絶対値 / adjust 差分）	lm_shelf_inventory / inventory_levels

この入庫在庫は受注ルーティングで優先的に引き当てられ、MFC 引き当て時は Star ラベルに棚番号が印字されます。

---

POST /api/ingest/mfc-inventory

「この出荷元ロケーションの、この棚に、この商品が何個あるか」を送信します。mode=absolute（既定）は qty をその棚の在庫数そのものとして、mode=adjust は qty を符号付きの増減量として反映します。棚ごとの反映と同時に、その商品の販売可能在庫（受注の引き当てに使われる数）も自動で更新されます。

リクエスト

POST https://api.lmile.io/api/ingest/mfc-inventory
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json

mode=absolute（既定。棚の在庫数を絶対値で確定する棚卸し的な入庫）:

{
  "shop": "demo-store.myshopify.com",
  "fulfillmentSourceLocationId": "343ff919-1234-5678-9abc-def012345678",
  "mode": "absolute",
  "lines": [
    { "barcode": "4912345678901", "shelfCode": "SA-A-13", "qty": 3 },
    { "barcode": "4912345678918", "shelfCode": "SA-B-02", "qty": 0 }
  ]
}

mode=adjust（現在庫に対する差分。+ で入庫、- で減算）:

{
  "shop": "demo-store.myshopify.com",
  "fulfillmentSourceLocationId": "343ff919-1234-5678-9abc-def012345678",
  "mode": "adjust",
  "lines": [
    { "barcode": "4912345678901", "shelfCode": "SA-A-13", "qty": 2 },
    { "barcode": "4912345678918", "shelfCode": "SA-B-02", "qty": -1 }
  ]
}

ボディパラメータ

パラメータ	型	必須	説明
shop	string	✓	店舗ドメイン（API キーで呼ぶ場合は省略できます）
fulfillmentSourceLocationId	string (uuid)	✓	入庫先の出荷元ロケーション id（shop に実在が必須）
mode	string		absolute（既定）= qty を絶対値で set / adjust = qty を符号付き差分で加減算。省略時は absolute（後方互換）
lines	array	✓	入庫行の配列

lines[] オブジェクト

パラメータ	型	必須	説明
barcode	string	✓	商品 barcode（事前に Products で登録）
shelfCode	string	✓	棚コード（最大 32 文字）。形式 ^[A-Z0-9]+(-[A-Z0-9]+)+$ かつ英字を 1 文字以上含む。大文字へ正規化してから照合します
qty	integer	✓	absolute ではその棚の在庫数（絶対値・≥0。0 で棚を空にする）。adjust では符号付き差分（+ 入庫 / - 減算）。adjust で結果が負になる行はバッチ全体を 409 insufficient_shelf_qty で reject します

レスポンス

{
  "ok": true,
  "applied": 2,
  "mode": "absolute"
}

フィールド	説明
applied	処理した入庫行（lines[]）の件数
mode	適用したモード（absolute / adjust。リクエストで省略した場合は absolute）

挙動・冪等性

• 引き当て済みの数を下回る減らし方は断ります: absolute（0 を含む）や adjust の - で、ある商品の棚の合計が注文に引き当て済みの数を上回る状態から下回る状態に変わると 409 shelf_qty_below_active でバッチ全体を中断し、何も変えません。同じ商品を別の棚へ動かす -1 / +1 は合計が変わらないので通ります。すでに下回っている在庫を減らす操作は止めません。
• 棚在庫は店舗 × 出荷元ロケーション × 棚 × 商品ごとに 1 行で管理されます。
• mode:

  • absolute（既定）— 送った qty がその棚の在庫数そのものになります（0 で棚を空にできます）。棚卸しや定期的な再報告向け。
  • adjust — 送った qty のぶん増減します（+3 で 3 個入庫 / -2 で 2 個減）。
• 棚と販売可能在庫は同時に更新されます: 棚ごとの反映と、その商品の全棚合算にもとづく販売可能在庫の更新が 1 つのトランザクションで行われます（部分適用はありません）。同じ商品を複数の棚に分けて送っても正しく合算されます。
• 販売可能在庫は「棚の合計」そのものではありません: 既に受注へ引き当て済みでまだ出荷していない分を差し引いた「いま売れる数」に自動補正されます。入庫直後の販売可能在庫が棚合計と一致しないのは正常です（引き当て済み分が引かれています。負になる場合は 0）。
• ピッキングで棚在庫は自動で減ります: 倉庫スタッフが商品を棚から取った時点で該当棚の qty が 1 減り、ピック取り消しで 1 戻ります。その後 mode=absolute で棚を再報告すれば、棚在庫は実数に上書きされて整合します（増減の積算ではないため二重に減ることはありません）。
• 再送の安全性: absolute は同じリクエストを何度再送しても安全です（冪等）。adjust は再送すると二重に増減します — タイムアウト等で結果が不明なときは、そのまま再送せず適用済みかを確認してください。
• バッチ全体で成功か失敗か: 未登録の barcode や、adjust で在庫が負になる行が 1 行でもあると、リクエスト全体が反映されません（部分適用や黙ったスキップはしません。→ エラー）。

---

エラー

エンドポイント固有:

Status	条件	レスポンス例
422	fulfillmentSourceLocationId が shop に存在しない	{ "ok": false, "error_kind": "location_unresolved", "error": "fulfillmentSourceLocationId not found for shop" }
422	棚コード形式不正	{ "ok": false, "error_kind": "invalid_shelf_code", "error": "shelfCode must match ...", "shelfCode": "SA_A_13", "index": 0 }
422	barcode が商品マスター未登録（その行でバッチ全体を中断）	{ "ok": false, "error_kind": "product_not_found", "error": "product not found for barcode ...", "barcode": "...", "index": 1 }
409	減らした結果、ある商品の棚の合計が注文に引き当て済みの数を下回る（バッチ全体を中断・何も変えない）	{ "ok": false, "error_kind": "shelf_qty_below_active", "barcode": "...", "shelfTotal": 3, "shelfTotalAfter": 1, "active": 2 }
409	mode=adjust で在庫が負になる行（バッチ全体を中断）	{ "ok": false, "error_kind": "insufficient_shelf_qty", "shelfCode": "SA-A-13", "barcode": "...", "available": 3, "requestedDelta": -5, "index": 0 }

入庫はバッチ単位で atomic です。1 行でも上記に該当するとバッチ全体を reject し、部分適用しません（silent skip しません）。共通エラー（401 / 400 / 403 / 405 / 500 / 503）は Error Codes を参照。

データモデル

• sot.lm_shelf_inventory — 棚在庫の qty 集約行。UNIQUE (shop, location_id, shelf_code, barcode) / qty >= 0。商品参照は barcode のみ。読み取り view: public.lm_v_shelf_inventory（内部 service / 管理用途。agent_read.* には露出しません）
• sot.lm_shelf_inventory_logs — 棚在庫の増減ログ（append-only）。delta / qty_after / reason / operator
• sot.inventory_levels — 現在庫マスター（shop + product_id + location_id で一意）。本 API は出荷元ロケーションの available_qty を全棚合算から引き当て済み未出荷数を差し引いた値（max(0, 棚合計 − 引当済未出荷)）に更新します。read は agent_read.inventory_levels（safe view）経由
• sot.lm_fulfillment_units — 1 単位 1 行のフルフィルメント明細。「引き当て済み未出荷数」はこのテーブルの status（allocated / secured / in_transit_to_mfc / packing）かつ未ピック（picked_at IS NULL）から数えます