Operator Lookup — 倉庫スタッフ向け照会
ピッキングアプリ（picking-ios）が倉庫オペレーションで使う read 専用の照会 API です。ラベルの追跡番号から shipment・注文・明細・配送先・状態を引く、バーコードから商品情報を引く、追跡番号 / ステータスで売越しケースを検索する、の 3 種です。いずれも書き込みは行いません。
Base URL
https://api.lmile.io· 認証 operator JWT（Authorization: Bearer）（詳細） ·shopは query に含めます
エンドポイント
GET
/api/operator/shipments/by-tracking
追跡番号 → shipment + 注文 + 明細（棚番号付き）+ 配送先 + 状態
lm_fulfillment_shipments / lm_routing_orders / lm_fulfillment_units / products / locations / lm_shelf_inventory
GET
/api/operator/products/by-barcode
バーコード → 商品の基本情報
products
GET
/api/operator/oversell-cases
追跡番号 / ステータスで売越しケースを検索
lm_oversell_cases / lm_routing_orders / lm_fulfillment_units / products / locations
レスポンスは camelCase（routing 系と同じ）。
shopは query で受け取り、スタッフに束縛された shop に含まれることを確認します（含まれなければ403 shop_not_authorized）。/api/operator/*の認証系統は 認証 を参照してください。倉庫スタッフの棚運用（ユニットQR でのユニット照会・棚コード照会・ピック）は Shelf Lookup（
/api/operator/shelf/*）に、ユニットQR での在庫確保は Secure Scan（/api/operator/secure-scan）にあります。
GET /api/operator/shipments/by-tracking
ラベルの追跡番号をスキャンし、その追跡番号を持つ shipment（出荷元単位の梱包）と、属する注文ヘッダ・unit 明細・配送先・出荷元別の状態を返します。同一追跡番号が複数 shipment（別注文 / 再発行）に当たりうるため配列（created_at 降順）で返します。
リクエスト
GET https://api.lmile.io/api/operator/shipments/by-tracking?shop=demo-store.myshopify.com&trackingNumber=4912345678901
Authorization: Bearer {OPERATOR_JWT}shop
string
✓
店舗ドメイン（スタッフの束縛 shop 内）
trackingNumber
string
✓
ラベルの追跡番号（最大 100 文字）
レスポンス
count / shipments[]
該当 shipment 件数 / 配列（created_at 降順）
status
出荷元ヘッダの状態（allocated → secured → … → shipped ＋ 売越し系）
fromLocationLabel
出荷元ロケーションの表示名（解決できなければ null）
labelVoidedAt / labelVoidReason
配送ラベルの void 情報（住所修正等での再発行時に旧ラベルへ記録）。picking-ios の出荷完了が陳腐化ラベルのスキャンを弾くのに使う
consolidationShelfCode
集約棚（ラベル発行前に 1 注文ぶんの商品を集める置き場。追跡番号 → この棚にラベルを貼りに行く）。未確定は null。shelfLink / units[].shelfCode とは別概念
consolidationLabelPlacedAt
「③ ラベルを置く」（POST /api/operator/shipment/place-label）の配置完了時刻。null = 未配置
consolidationGroupId
同一 MFC 複数店舗分割の集約グループ id（= head shipment の id。1 箱 = 1 ラベル）。非集約は null。追跡番号は head のみが持つため、ヒット時の units[] はグループ全 shipment の union（箱全体の明細）
order.orderNumber
注文番号（sot.lm_routing_orders.external_order_ref）
order.orderName
表示用の注文番号（order_name。例 BJP1001。無ければ null）。UI の注文番号表示にはこちらを使う
order.shipTo
配送先住所（PII。住所修正が反映された最新値）
order.serviceLines[]
非在庫の同梱品（ショッパーバッグ等、products.is_non_inventory=true の明細）。在庫引き当て対象外で unit を持たないため、注文単位で {barcode, sku, productName, variantName, quantity} を明示する。梱包スタッフはこのリストの品を自拠点ストックから箱に同梱する（同梱漏れ防止）。無い注文は空配列。注文が複数出荷元に分割されている場合は各 shipment に同じ内容が付く（同梱は箱単位で 1 回）
shelfLink
shipment のアクティブな棚紐付け（Shelf Link の sot.lm_shelf_links）。未紐付けは null。units[].shelfCode（引き当て在庫棚）とは別物で、こちらは shipment の置き場所棚。棚紐付け画面の「既に棚 X に紐付け済み」案内・付け替え誘導に使う
units[]
unit 明細（lineInstanceNo 昇順）。barcode で解決した productName / variantName / imageUrl を enrich
units[].shelfCode
ユニットに割り当てられたピック元の保管棚（引当時に棚在庫へ FIFO 分配した sot.lm_fulfillment_units.shelf_code）。未割当の場合のみ引き当て先 (location, barcode) の棚から解決した値で補完。棚を持たない店舗 / 同期拠点は null
units[].giftWrap
ギフトラッピング要否（boolean）。line_properties.isGiftWrapping = "true" または SKU に GIFT を含む場合 true。出荷時のギフト確認に使う。line_properties の生値は PII のため返さず、導出した真偽値のみ
挙動
該当 shipment が無ければ
404 shipment_not_found。shipment が指す注文ヘッダが引けない不整合は隠さず
500 data_inconsistencyで表面化します（nullで誤魔化しません）。
GET /api/operator/products/by-barcode
バーコードをスキャンし、該当商品の基本情報（名前 / SKU / 画像 / カテゴリ / 価格 等）を返します。(shop, barcode) は一意運用です。
リクエスト
shop
string
✓
店舗ドメイン（スタッフの束縛 shop 内）
barcode
string
✓
商品バーコード（最大 100 文字）
レスポンス
productName / variantName / brand / categoryL1–L3
商品名・バリアント名・ブランド・カテゴリ階層
currentPrice / currency
販売価格 / 通貨
isNonInventory
非在庫サービス品フラグ（true はルーティング引き当て対象外）
lifecycleStatus
商品ライフサイクル状態
原価（
current_cost）・参考価格（current_compare_at_price）・自由メモ（notes）は倉庫オペレーションに不要な機微情報のため返しません。
挙動
該当バーコードが無ければ
404 product_not_found。
GET /api/operator/oversell-cases
倉庫が追跡番号で受け取った荷物などから、sot.lm_oversell_cases の該当ケースを検索します（売越し入庫の入口）。trackingNumber / status はどちらも任意で、両方なしのときは shop の全件をページサイズ内（既定 50・最大 200・updated_at 降順）で返します。
リクエスト
shop
string
✓
店舗ドメイン（スタッフの束縛 shop 内）
trackingNumber
string
指定時のみ追跡番号で完全一致フィルタ（最大 100 文字）
status
string
指定時のみステータスでフィルタ（下記 9 値のいずれか）
limit
number
1 ページの件数。正整数・既定 50・最大 200
status に指定できる値: case_opened / locating / contacted / stock_secured / dispatch_requested / dispatched / tracking_reported / warehouse_received / wont_do
レスポンス
count / cases[]
該当ケース件数 / 配列（updated_at 降順）
status
売越しケースの現ステップ（上記 9 値）
foundLocationId / foundLocationLabel
確保元ロケーションの ID / 表示名（未確保は null）
product
barcode で解決した商品情報（未登録は null）
order / unit
紐づく注文ヘッダ / フルフィルメント単位（解決できなければ null）
contactedAt–wontDoAt
各ステップの遷移日時（未遷移は null）
挙動
statusが 9 値以外なら400 invalid_status（許可値をallowedに同梱）。enrich（注文 / 単位 / 商品 / ロケーション）が解決できない要素は隠さず
nullを返します（検索一覧のため500にはしません）。
エラー
エンドポイント固有:
404
追跡番号に該当 shipment なし（shipments/by-tracking）
{ "ok": false, "error_kind": "shipment_not_found", "error": "shipment not found" }
404
バーコードに該当商品なし（products/by-barcode）
{ "ok": false, "error_kind": "product_not_found", "error": "product not found" }
400
status が許可値外（oversell-cases）
{ "ok": false, "error_kind": "invalid_status", "error": "invalid status", "allowed": [...] }
500
shipment が指す注文ヘッダの欠落（shipments/by-tracking・データ異常）
{ "ok": false, "error_kind": "data_inconsistency", "error": "routing_order not found for shipment ..." }
共通エラー（401 / 400 / 403 / 405 / 500 / 503）は Error Codes を参照。
データモデル
sot.lm_fulfillment_shipments/sot.lm_fulfillment_units— Units の出荷元ヘッダ・単位明細。sot.lm_routing_orders— 注文ヘッダ。配送先（ship_to_*）は PII で公開 view からは除外され、本 API は operator JWT 認証下で service_role により直接参照します。sot.lm_oversell_cases— 売越しケース。sot.products/sot.locations— 商品マスター / 拠点マスター（barcode・ロケーション ID の enrich）。sot.lm_shelf_inventory— 棚在庫（shipments/by-trackingのunits[].shelfCodeの解決元。qty>0優先・同点shelf_code昇順）。
Last updated
Was this helpful?