Shelf Lookup — 棚照会・ピック
倉庫スタッフのピッキングアプリ（picking-ios）向けの照会・ピック API です。ユニットラベルのユニットQR または棚コードをスキャンし、対象ユニット・棚番号・出荷/注文状態・picked 作業状態を引き、ピッキング完了を per-unit で記録します。
Base URL
https://api.lmile.io· 認証 operator JWT（Authorization: Bearer）。/api/operator/shelf/pickはx-ingest-secretでも可（詳細） · read API はshopを query、pick はshopをボディに含めます（pick を API キーで呼ぶ場合は省略できます）
operator 認証は倉庫スタッフ（picking-ios）専用の Bearer トークンで、スタッフに束縛された shop だけを操作できます（詳細は 認証）。read 系（
lookup/by-code）は Bearer のみ、pick は機械間連携も想定しx-ingest-secretでも呼べます。フィールドは camelCase（routing 系と同じ）。
ユニットQR 規格:
<barcode>|<shipmentId>（shipmentId=sot.lm_fulfillment_shipments.id。出荷指示ラベルの本番印字形式）。2 値は同一 barcode の複数ユニットを区別しないため、shipment 配下の barcode 一致ユニットから 未 picked のlineInstanceNo昇順先頭 1 件をサーバ側で解決します。旧規格（JAN|FulfillmentOrderId）は受理せず422 legacy_qr（ラベル再印刷を案内）。
エンドポイント
GET
/api/operator/shelf/lookup
ユニットQR → ユニット + 棚 + 出荷/注文 + picked 状態
lm_fulfillment_units / lm_shelf_links / lm_fulfillment_shipments / lm_routing_orders / products
GET
/api/operator/shelf/by-code
棚コード → アクティブ紐付け shipment + 棚在庫
lm_shelf_links / lm_shelf_inventory / lm_fulfillment_shipments / lm_routing_orders
POST
/api/operator/shelf/pick
ユニットQR スキャンで unit を picked / unpick
lm_fulfillment_units
GET /api/operator/shelf/lookup
ユニットQR から対象ユニットを解決し、紐付いている棚番号・出荷/注文の取消状態・picked 作業状態・商品情報を返します。unit は「次に pick 対象となるユニット」（未 picked の lineInstanceNo 昇順先頭。全て picked なら直近の対象 = 降順先頭）です。
リクエスト
GET https://api.lmile.io/api/operator/shelf/lookup?shop=demo-store.myshopify.com&qr=4912345678901%7Caaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
Authorization: Bearer {OPERATOR_JWT}shop
string
✓
店舗ドメイン（スタッフの束縛 shop 内）
qr
string
✓
ユニットQR（<barcode>|<shipmentId>。最大 200 文字）
レスポンス
unit
次に pick 対象となるユニット（未 picked の lineInstanceNo 昇順先頭。全て picked なら降順先頭）
unit.picked / pickedAt / pickedBy
picked 作業状態（picked_at の有無）/ 完了日時 / 操作者
units.total / units.picked
shipment 配下の barcode 一致ユニット総数 / うち picked 済（数量 >1 の進捗表示用）
shelf
アクティブな棚紐付け（未紐付けは null）
order.orderNumber
注文番号（sot.lm_routing_orders.external_order_ref）
cancelled
unit / shipment / 注文のいずれかが cancelled なら true（出荷済は Cancel で保護）
product
barcode で解決した商品情報（未登録は null）
挙動
QR 不正形式は
422 invalid_qr、旧規格は422 legacy_qr。shipmentIdの shipment が無ければ404 shipment_not_found、shipment 配下に barcode 一致 unit が無ければ404 unit_not_found。shipment が指す注文が引けない不整合は隠さず
500 data_inconsistencyで表面化します（fallback しません）。
GET /api/operator/shelf/by-code
棚コードをスキャンし、その棚にアクティブに紐付いている shipment（注文 / 出荷状態）と、棚在庫（barcode × qty）を返します。
リクエスト
shop
string
✓
店舗ドメイン（スタッフの束縛 shop 内）
shelfCode
string
✓
棚コード（最大 64 文字で受理し、大文字へ正規化してから規格照合）
レスポンス
link
アクティブ紐付け + enrich した shipment / 注文（紐付け無しは null）
inventory[]
棚在庫の qty 集約行（同一棚に複数 barcode がありうるので配列。空でも 200）
挙動
棚コード不正形式は
422 invalid_shelf_code。紐付けも在庫も無い棚は
404ではなく200でlink: null/inventory: []（「空」を正常応答で表現）。紐付けが指す shipment / 注文が引けない不整合は
500 data_inconsistencyで表面化します。
POST /api/operator/shelf/pick
ユニットQR から対象ユニットを解決し、picked 状態を更新します。picked は配送ライフサイクル status とは直交の作業状態で、sot.lm_fulfillment_units.picked_at / picked_by で表現します。
リクエスト
ボディパラメータ
shop
string
✓
店舗ドメイン（API キーで呼ぶ場合は省略できます）
qr
string
✓
ユニットQR（<barcode>|<shipmentId>。最大 200 文字）
action
string
pick（既定）/ unpick（picked 取り消し）
レスポンス
action
pick / unpick
unitId
今回対象になったユニット
picked
操作後の picked 状態
alreadyPicked / alreadyUnpicked
既にその状態だった（冪等な再スキャン）か
pickedAt / pickedBy
完了日時 / 操作者（operator JWT 経由のみ非 null = auth.users.id）
units.total / units.picked
shipment 配下の barcode 一致ユニット総数 / うち picked 済（操作後）
挙動・冪等性
順次 pick: 2 値QR は同一 barcode の複数ユニットを区別しないため、
pickはスキャンごとに「未 picked のlineInstanceNo昇順先頭 1 件」を picked にします（数量 2 なら 2 回のスキャンで全て picked）。冪等: barcode 一致ユニットが全て picked の状態での再
pickは200+alreadyPicked: true（上書きしません）。全て未 picked でのunpickも同様（alreadyUnpicked: true）。取り消し:
action=unpickは「picked のlineInstanceNo降順先頭 1 件」（= 直近の pick から LIFO）のpicked_at/picked_byをNULLに戻します。自己在庫の棚 qty 減算（LM-769）: 対象ユニットが自己在庫 MFC（
sot.lm_shelf_inventoryに棚在庫を持つ出荷元）に引き当てられている場合、pick（未 picked→picked の遷移）でそのユニットが置かれていた棚のqtyを −1（reason=pick） し、unpick（picked→未 picked の遷移）で +1（reason=receive） 復元します。減算する棚は star ラベルが作業者に提示する棚（同一(location, barcode)で qty>0 優先・同点はshelf_code昇順の 1 棚）です。続けて自己在庫のavailable_qtyを再計算し（MFC 入庫 LM-761 と同式）、変化分を源在庫 webhook（Webhooks）で販売面へ反映します。棚を持たない店舗 / 同期拠点のユニットは該当棚が無いため no-op です。減算/復元はpicked_atの遷移時のみ行うため、冪等な再pick/ 再unpickでは二重に増減しません。ベストエフォートで、棚操作が失敗してもpick自体は成功し、available_qtyは後続の再計算が冪等に整合させます。QR 不正形式は
422 invalid_qr、旧規格は422 legacy_qr。shipment 配下に barcode 一致 unit が無ければ404 unit_not_found。
エラー
エンドポイント固有（3 エンドポイント共通の error_kind）:
422
ユニットQR 形式不正
`{ "ok": false, "error_kind": "invalid_qr", "error": "unit QR must be
422
旧 mfc QR（受理せず再印刷を案内）
`{ "ok": false, "error_kind": "legacy_qr", "error": "legacy unit QR (JAN
422
棚コード形式不正（by-code）
{ "ok": false, "error_kind": "invalid_shelf_code", "error": "invalid shelf code format" }
404
shipment が存在しない（lookup）
{ "ok": false, "error_kind": "shipment_not_found", "error": "fulfillment shipment not found" }
404
barcode 一致 unit が存在しない（lookup / pick）
{ "ok": false, "error_kind": "unit_not_found", "error": "fulfillment unit not found" }
409
ユニットが倉庫間移動（出荷元変更）フロー中（pick。pick/unpick の対象外・行き先 / バルク所属を units[] に同梱）
{ "ok": false, "error_kind": "transfer_required", "units": [...] }
500
shipment / 紐付けが指す注文の欠落（データ異常）
{ "ok": false, "error_kind": "data_inconsistency", "error": "routing_order not found for shipment ..." }
共通エラー（401 / 400 / 403 / 405 / 500 / 503）は Error Codes を参照。
データモデル
sot.lm_fulfillment_units— Units の単位明細。picked_at/picked_by（MFC 内ピッキング完了 = 配送 status と直交の作業状態。旧 mfcready_for_pickup.status=picked相当）を本 API が更新します。sot.lm_shelf_links/sot.lm_shelf_inventory— Shelf Link / Shelf Inventory を参照。read 用 view:public.lm_v_shelf_links/public.lm_v_shelf_inventory（内部 service / 管理用途）。本 read API は service_role でsot.*を直接参照し、operator JWT の束縛 shop で絞り込みます。
Last updated
Was this helpful?