Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Fulfillment — 出荷ステータス遷移・ラベル

Routing で各在庫ロケーションへ引き当てた後の、引き当てロケーション（from-location）単位の進捗を報告するエンドポイント。状態が 確保済（secured） へ遷移した shipment については、注文の出荷元（fulfillment source location）の action: "label" 設定（Dispatch Config）を使ってラベルを生成し、応答から追跡番号とラベル PDF を取り込みます。

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

/api/routing/fulfillment は機械間 secret（x-ingest-secret）と倉庫スタッフの operator JWT のどちらでも呼べます（系統はヘッダの有無で明示判別。詳細）。operator JWT 経由は操作スタッフを記録します。

取り込んだラベル PDF は Supabase Storage に保存され、出荷元に action: "print" 設定（Dispatch Config）があれば生成直後に出荷元の print server へ自動印刷されます（LM-605）。印刷の手動再実行は Print Label。

ライフサイクル状態

/api/routing/orders で引き当て・dispatch されると、各出荷元は allocated で作成されます。以降の遷移を本 API で報告します。

status
業務上の意味

unallocated

1: 未引当

allocated

引当・出荷指示済 / 未確保（routing 直後の初期状態）

secured

2: 確保済 → ラベル生成トリガー

oversell_pending

売越発生中

oversell_secured

売越在庫確保済 → ラベル生成トリガー

oversell_returning

売越返送中

oversell_warehouse_received

売越商品倉庫受付完了

in_transit_to_mfc

3: 引当店舗から MFC センターへ移動中

packing

4: 梱包作業開始

shipped

5: 出荷完了

cancelled

注文取消による終端（Cancel / Update。shipped は保護され遷移しない）

注文全体の確保状況（一部確保済みを含む）は public.lm_v_routing_order_fulfillment で集計参照できます（secured / partially_secured / allocated / shipped / cancelled）。

エンドポイント

Method
Path
用途

POST

/api/routing/fulfillment

出荷元単位の状態遷移を報告（確保済でラベル生成）

POST /api/routing/fulfillment

リクエスト

パラメータ
型
必須
説明

shop

string

✓

店舗ドメイン（API キーで呼ぶ場合は省略できます）

routingOrderId

string (uuid)

△

対象注文。無ければ sourceSystem + externalOrderRef で特定

sourceSystem / externalOrderRef

string

△

routingOrderId 未指定時に必須

tag

string

ラベル設定解決の tag 条件（省略時は注文 / 出荷指示の tag を使用）

shipments

array

✓

出荷元ごとの状態更新（1〜1000 件）

shipments[].fromLocationId

string (uuid)

✓

対象の在庫ロケーション（引き当て先）

shipments[].status

string

✓

上記ライフサイクル状態のいずれか

shipments[].targetMfcLocationId

string (uuid)

△

status='in_transit_to_mfc' のとき必須。移動先 MFC ロケーション（MFC でなければ 422）。単位の現在在庫ロケーションを更新

挙動

  • 各出荷元の状態を更新し、状態に応じたタイムスタンプ（secured_at / in_transit_at / packing_started_at / shipped_at）を記録します。

  • secured / oversell_secured への遷移時のみ（既に確保系だった場合は再生成しない）、その location の action: "label" 設定でラベルを生成し、tracking_number / carrier_code / label_pdf_path を書き戻します。

  • ラベル設定の無い location は labelStatus: "skipped" を返し、確保状態は維持します。

  • ラベル生成に失敗しても確保状態は巻き戻しません（last_label_error に記録、labelStatus: "failed"）。

  • ラベル生成成功時、出荷元の action: "print" 設定があれば PDF を出荷元の print server へ自動印刷します（label_printed_at を記録）。印刷失敗してもラベル生成・確保は維持され last_print_error に記録します（printStatus: "failed"）。print 設定の無い出荷元は printStatus: "skipped"。

  • ヘッダの状態は配下の単位（Units）へ cascade します。in_transit_to_mfc のときは targetMfcLocationId を単位の現在在庫ロケーション（current_inventory_location_id）に設定します（引当店舗→MFC 移動を状態で表現。在庫数量 inventory_levels は変更しません）。

  • 在庫確保（status 2）は単位ごとに行う /api/routing/secure が主経路です。本 API に secured を直接送った場合もヘッダ + 単位へ反映します。

  • status が遷移した shipment は Fulfillment Status Webhook で外部へ通知されます（設定時のみ）。

  • operator JWT で呼んだ場合、報告した出荷元ヘッダに操作スタッフ（検証済の auth.users.id）を記録します。x-ingest-secret（機械間）経由の挙動は不変です。

レスポンス

フィールド
説明

labelStatus

generated（生成・保存済）/ skipped（label 設定なし or 明細未解決）/ failed（生成失敗）/ none（ラベル非対象の状態）

printStatus

printed（出荷元 print server へ送信成功）/ skipped（print 設定なし）/ failed（印刷失敗。last_print_error に記録）/ none（ラベル未生成）

labelPdfPath

Supabase Storage shipping-labels バケット内のパス

エラー

エンドポイント固有:

Status
条件
レスポンス例

400

注文特定情報なし / status 不正 / in_transit_to_mfc で targetMfcLocationId 欠落

{ "ok": false, "error": "invalid_input" }

422

targetMfcLocationId が MFC ロケーションでない

{ "ok": false, "error_kind": "not_an_mfc_location", "error": "targetMfcLocationId is not an MFC location for this shop" }

404

注文が存在しない

{ "ok": false, "error_kind": "order_not_found", "error": "routing order not found" }

409

shipped 報告のヘッダに出荷可能な unit が無く、注文配下に倉庫間移動（出荷元変更）フロー中の unit がある（刻印の倉庫返送等。旧ヘッダの顧客向けラベルで出荷完了しようとした場合）

{ "ok": false, "error_kind": "transfer_required", "units": [...] }

共通エラー（401 / 400 / 403 / 405 / 500 / 503）は Error Codes を参照。

データモデル

  • sot.lm_fulfillment_shipments — 出荷元（UNIQUE shop + routing_order_id + from_location_id）単位の状態 + 追跡番号 + ラベル PDF パス + 印刷結果（label_printed_at / last_print_error）+ 各遷移タイムスタンプ。読み取り view: public.lm_v_fulfillment_shipments

  • public.lm_v_routing_order_fulfillment — 注文単位の確保状況集計（secured / partially_secured / allocated / shipped / cancelled。cancelled_count 列あり）

  • sot.lm_location_dispatch_config.action = 'label' + response_mapping — ラベル送信先と応答マッピング、action = 'print' — 出荷元 print server（Dispatch Config）

  • Supabase Storage shipping-labels（private バケット）— ラベル PDF 本体

PreviousInventory Adjustments — 外部システムへの在庫調整
NextUnits — 単位ステータス・在庫確保

Last updated

Was this helpful?