Operator Queues — 出荷作業キュー・引当不能一覧

ピッキングアプリ（picking-ios）が現場（店舗 / MFC）の作業量を把握するための read 専用の一覧 API です。出荷作業キュー（location × status × 期間で shipment を横断一覧 + 件数サマリ）、routing で引当不能（no_stock）のまま滞留している注文の一覧、出荷元変更（拠点間移動）ケースの一覧の 3 種です。いずれも書き込みは行いません。追跡番号 / バーコードでの 1 件照会は Operator Lookup を参照してください。

Base URL https://api.lmile.io · 認証 operator JWT（Authorization: Bearer）（詳細） · shop は query に含めます

エンドポイント

Method	Path	用途	テーブル
GET	/api/operator/shipments	出荷作業キュー一覧（location × status × 期間 + 件数サマリ）	lm_fulfillment_shipments / lm_fulfillment_source_members / lm_routing_orders / lm_fulfillment_units / products / locations
GET	/api/operator/unallocated-orders	引当不能（no_stock）注文の一覧	lm_routing_orders / lm_routing_decisions / products / locations
GET	/api/operator/source-changes	出荷元変更（拠点間移動）ケースの一覧	lm_fulfillment_source_changes / lm_routing_orders / lm_fulfillment_units / products / locations

レスポンスは camelCase（routing 系と同じ）。shop は query で受け取り、スタッフに束縛された shop に含まれることを確認します（含まれなければ 403 shop_not_authorized）。/api/operator/* の認証系統は 認証 を参照してください。

---

GET /api/operator/shipments

現場（店舗 / MFC）が「今日何件出荷しないといけないか」を pull で取得する出荷作業キューの一覧です。1 件照会（shipments/by-tracking）と対になる横断一覧で、shipment 一覧（status / 追跡番号 / ラベル有無 / 配送先 / unit 明細 / picked 進捗）に加え、フィルタ全体の status 別件数 + 未ラベル件数サマリを返します（例:「二子玉川MFC は今日 allocated 12 件・secured 5 件・未ラベル 3 件」）。

リクエスト

GET https://api.lmile.io/api/operator/shipments?shop=demo-store.myshopify.com&fromLocationId=b2c3d4e5-f6a7-8901-bcde-f23456789012&status=allocated,secured&dateFrom=2026-06-06T15:00:00.000Z&limit=50
Authorization: Bearer {OPERATOR_JWT}

クエリ	型	必須	説明
shop	string	✓	店舗ドメイン（スタッフの束縛 shop 内）
fromLocationId	string		指定時のみ単一の出荷元ロケーション（uuid）で fromLocationId 完全一致フィルタ
fulfillmentSourceLocationId	string		指定時のみ出荷元（MFC/倉庫）のメンバー在庫ロケーション集合（uuid）で from_location_id を絞る。fromLocationId とは排他（両方指定は 400）
status	string		指定時のみステータスでフィルタ（CSV で複数指定可・下記 11 値のいずれか）
dateFrom	string		指定時のみ createdAt >= dateFrom で絞る（ISO 8601 datetime）
dateTo	string		指定時のみ createdAt <= dateTo で絞る（ISO 8601 datetime・dateFrom <= dateTo）
labelErrorOnly	string		true / 1 のときラベル発行エラー中（住所不備等で lastLabelError あり）の shipment だけに絞る
limit	number		一覧の件数。正整数・既定 50・最大 200（超過分は 200 に丸め）

status に指定できる値: unallocated / allocated / secured / oversell_pending / oversell_secured / oversell_returning / oversell_warehouse_received / in_transit_to_mfc / packing / shipped / cancelled

レスポンス

{
  "ok": true,
  "count": 1,
  "totalCount": 1,
  "summary": {
    "byStatus": { "allocated": 1, "secured": 0 },
    "unlabeled": 1
  },
  "shipments": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "allocated",
      "trackingNumber": null,
      "carrierCode": null,
      "hasLabel": false,
      "hasLabelError": false,
      "labelGeneratedAt": null,
      "shelfLink": null,
      "fromLocationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "fromLocationLabel": "二子玉川MFC",
      "securedAt": null,
      "inTransitAt": null,
      "packingStartedAt": null,
      "shippedAt": null,
      "cancelledAt": null,
      "createdAt": "2026-06-07T01:23:45.000Z",
      "updatedAt": "2026-06-07T01:23:45.000Z",
      "order": {
        "id": "7b1f08a3-1234-4abc-9def-0123456789ab",
        "orderNumber": "1001",
        "sourceSystem": "shopify",
        "status": "routed",
        "shipTo": {
          "name": "山田 太郎",
          "company": null,
          "phone": "[phone]",
          "email": "[e-mail]",
          "country": "JP",
          "postalCode": "150-0001",
          "prefecture": "東京都",
          "city": "渋谷区",
          "address1": "道玄坂1-2-3",
          "address2": null
        }
      },
      "picking": { "totalUnits": 1, "pickedUnits": 0 },
      "units": [
        {
          "id": "uuuuuuuu-1111-2222-3333-444444444444",
          "barcode": "4912345678901",
          "sku": "SKU-001",
          "lineInstanceNo": 1,
          "status": "allocated",
          "secured": false,
          "pickedAt": null,
          "productName": "サンプル商品",
          "variantName": "M",
          "imageUrl": "https://.../image.jpg"
        }
      ]
    }
  ]
}

フィールド	説明
count / shipments[]	一覧の件数（limit まで）/ 配列（createdAt 昇順 = 作業キューとして古い順）
totalCount	フィルタ全体の該当件数（limit に関係なく数えます）
summary.byStatus	フィルタ全体の status 別件数。status フィルタ指定時はその値だけ、未指定時は全 11 値
summary.unlabeled	フィルタ全体の未ラベル（ラベル PDF 未生成）件数
hasLabel / labelGeneratedAt	ラベル PDF の有無 / 生成日時（PDF の保存パス自体は返しません）
hasLabelError	ラベル発行エラー中か（住所不備等）。エラー本文には住所断片が混ざりうるため一覧には出さず真偽値のみ返します（解消フローは Address Recovery → retry-label を参照）
shelfLink	この出荷のアクティブな棚紐付け（{ shelfCode, locationId, linkedAt }）。未紐付けは null。「棚紐付け待ち（secured・ラベルあり・shelfLink が null）」と「集荷待ち」を分けるのに使います
fromLocationLabel	出荷元ロケーションの表示名（解決できなければ null）
securedAt–cancelledAt	各ステップの遷移日時（未遷移は null）
order	注文ヘッダ（解決できなければ null）。shipTo は配送先住所（PII。住所修正が反映された最新値）
picking	picked 進捗。cancelled の unit は作業対象外として母数から除きます
units[]	unit 明細（lineInstanceNo 昇順）。barcode で解決した productName / variantName / imageUrl を enrich

挙動

• 一覧は createdAt 昇順（作業キューとして古い順）で limit 件。サマリ（totalCount / byStatus / unlabeled）は limit に関係なくフィルタ全体を数えます。
• fulfillmentSourceLocationId を指定すると、その出荷元の有効なメンバー在庫ロケーション集合（sot.lm_fulfillment_source_members の is_active=true な inventory_location_id）で from_location_id を絞り込みます。出荷元自身もメンバー行（self）として登録されているため集合に含まれ、出荷元自身の自己在庫 shipment も拾います。fromLocationId（単一ロケーション完全一致）とは用途が排他で、両方指定すると 400 です。メンバーが 0 件の出荷元は shop 全体に逃げず**空（該当 0 件）**を返します（フォールバックしません）。この絞り込みは一覧・サマリ（totalCount / byStatus / unlabeled）の双方に効きます。
• dateFrom / dateTo は shipment の createdAt 範囲（両端を含む）。未指定は全期間。
• enrich（注文 / 商品 / ロケーション）が解決できない要素は隠さず null を返します（検索一覧のため 500 にはしません）。
• labelErrorOnly=true はラベル発行エラー中（lm_fulfillment_shipments.last_label_error が非 null）の shipment だけに絞る「住所不備キュー」です。住所を Address Recovery で修正 → 同ページの retry-label で再発行が成功（labelStatus: "generated"）するとエラーはクリアされ、このフィルタから外れます（= 解消の判定）。この絞り込みは一覧・サマリの双方に効きます。
• 明細単位の付帯情報（properties 等の PII）・ラベル PDF の保存パス・ラベルエラー本文はレスポンスに含めません（ラベルは hasLabel / hasLabelError / labelGeneratedAt のみ）。

---

GET /api/operator/unallocated-orders

routing で全行引当不能（no_stock）になったまま滞留している注文を pull で一覧確認します。Routing Allocation Webhook の unallocated イベント（push）を見逃しても、この API で滞留に気づけます。再引当で解消された注文は status が routed に変わるため、常に「現在も引当不能」の注文だけが返ります。

リクエスト

GET https://api.lmile.io/api/operator/unallocated-orders?shop=demo-store.myshopify.com&barcode=4912345678901&limit=50
Authorization: Bearer {OPERATOR_JWT}

クエリ	型	必須	説明
shop	string	✓	店舗ドメイン（スタッフの束縛 shop 内）
barcode	string		指定時のみ「その barcode の引当不能行を持つ注文」に絞る（最大 100 文字）
limit	number		一覧の件数。正整数・既定 50・最大 200（超過分は 200 に丸め）

レスポンス

{
  "ok": true,
  "count": 1,
  "orders": [
    {
      "id": "7b1f08a3-1234-4abc-9def-0123456789ab",
      "orderNumber": "1002",
      "sourceSystem": "shopify",
      "status": "no_stock",
      "tag": null,
      "fulfillmentSource": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "label": "大阪MFC"
      },
      "unallocatedLines": [
        {
          "barcode": "4912345678901",
          "lineInstanceNo": 1,
          "product": {
            "sku": "SKU-001",
            "productName": "サンプル商品",
            "variantName": "M",
            "imageUrl": "https://.../image.jpg"
          }
        }
      ],
      "createdAt": "2026-06-07T01:23:45.000Z",
      "updatedAt": "2026-06-07T01:23:45.000Z"
    }
  ]
}

フィールド	説明
count / orders[]	該当注文件数（limit まで）/ 配列（createdAt 降順 = 新しい順）
status	常に no_stock（再引当で解消されると routed になり一覧から外れます）
tag	Routing リクエストで渡した注文タグ（未指定は null）
fulfillmentSource	注文の出荷元（routing リクエストの fulfillmentSourceLocationId）。label は表示名（解決できなければ null）。出荷元なしの注文は null
unallocatedLines[]	引当不能の行（判定の createdAt 昇順）。product は barcode で解決した商品情報（未登録は null）

挙動

• status='no_stock' の注文のみを createdAt 降順（新しい順）で limit 件返します。期間フィルタはありません。
• barcode 指定時は「その barcode の引当不能行を持つ注文」を行 → 注文の順で逆引きしてから絞り込むため、limit による取りこぼしはありません。該当なしは 200 + count: 0。
• 引当不能行は routing 判定結果（lm_routing_decisions）の在庫なし（no_stock）行です。非在庫サービス品（Products の is_non_inventory）の行は引当不能ではないため含まれません。
• 明細単位の付帯情報（properties 等の PII）はレスポンスに含めません。

---

GET /api/operator/source-changes

出荷元変更（/api/routing/change-source）で起票された「移動すべきもの」を pull で一覧確認します。送り側（旧出荷元 MFC）は fromSourceLocationId で「これから返送便に詰めるもの」（change_requested）を、受け側（流山等の新出荷元）は toSourceLocationId で「届くはずのもの」（return_in_transit）を、それぞれ同じ API で取得します。売越しケース検索（oversell-cases）と同形の read 専用検索です。

リクエスト

GET https://api.lmile.io/api/operator/source-changes?shop=demo-store.myshopify.com&status=change_requested,return_in_transit&fromSourceLocationId=b2c3d4e5-f6a7-8901-bcde-f23456789012&limit=50
Authorization: Bearer {OPERATOR_JWT}

クエリ	型	必須	説明
shop	string	✓	店舗ドメイン（スタッフの束縛 shop 内）
status	string		指定時のみステータスでフィルタ（CSV で複数指定可・change_requested / return_in_transit / return_received / cancelled）
fromSourceLocationId	string		指定時のみ旧出荷元（送り側）の uuid で絞る（梱包キュー）
toSourceLocationId	string		指定時のみ新出荷元（受け側）の uuid で絞る（入荷待ちキュー）。fromSourceLocationId と併用可
trackingNumber	string		指定時のみ返送便の追跡番号で完全一致（受け側の入荷照合。最大 100 文字）
batchId	string		指定時のみ倉庫間移動バルクの uuid で絞る（バルクの内容物一覧）
shipmentId	string		指定時のみ統合QR（barcode|shipmentId）の shipment uuid から注文を解決し、その注文のケースに絞る（relink 後の旧 shipment でも解決可）。指定時はレスポンスに resolvedRoutingOrderId を echo
limit	number		一覧の件数。正整数・既定 50・最大 200（超過分は 200 に丸め）

レスポンス

{
  "ok": true,
  "count": 1,
  "cases": [
    {
      "id": "cccccccc-dddd-eeee-ffff-000000000000",
      "status": "change_requested",
      "barcode": "4912345678901",
      "lineInstanceNo": 1,
      "reason": "刻印は流山のみ",
      "fromSourceLocationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "fromSourceLocationLabel": "大阪MFC",
      "toSourceLocationId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "toSourceLocationLabel": "流山倉庫",
      "fromInventoryLocationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "fromInventoryLocationLabel": "大阪MFC",
      "toInventoryLocationId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "toInventoryLocationLabel": "流山倉庫",
      "returnTrackingNumber": "SGW-1234-5678",
      "returnCarrierCode": "sagawa",
      "hasReturnLabel": true,
      "returnLabelGeneratedAt": "2026-06-12T01:23:45.000Z",
      "externalShipmentRef": null,
      "note": null,
      "cancelReason": null,
      "batchId": null,
      "collectedCheckedAt": null,
      "product": {
        "sku": "SKU-001",
        "productName": "サンプル商品",
        "variantName": "M",
        "imageUrl": "https://.../image.jpg"
      },
      "order": {
        "id": "7b1f08a3-1234-4abc-9def-0123456789ab",
        "orderNumber": "1001",
        "sourceSystem": "shopify",
        "status": "routed"
      },
      "unit": { "id": "uuuuuuuu-1111-2222-3333-444444444444", "status": "source_change_pending" },
      "requestedAt": "2026-06-12T01:23:45.000Z",
      "inTransitAt": null,
      "receivedAt": null,
      "cancelledAt": null,
      "createdAt": "2026-06-12T01:23:45.000Z",
      "updatedAt": "2026-06-12T01:23:45.000Z"
    }
  ]
}

フィールド	説明
count / cases[]	該当件数（limit まで）/ 配列（updatedAt 降順 = 動きがあった順）
status	ケースの段階。change_requested（返送手配中）→ return_in_transit（返送中）→ return_received（受領済 = 終端）。cancelled は中止
fromSource* / toSource*	旧出荷元（送り側）/ 新出荷元（受け側）。*InventoryLocation* はその配下の在庫ロケーション
returnTrackingNumber / returnCarrierCode	返送便（旧 → 新）の追跡番号 / キャリア
batchId	所属する倉庫間移動バルク。未所属（単体返送等）は null
collectedCheckedAt	集荷チェック（check-unit）記録日時。未チェックは null
hasReturnLabel / returnLabelGeneratedAt	返送ラベル PDF の有無 / 生成日時（PDF の保存パス・ラベルエラー本文は返しません）
product / order / unit	barcode で解決した商品情報 / 注文ヘッダ / 対象 unit の現在 status（解決できなければ null）
requestedAt–cancelledAt	各ステップの遷移日時（未遷移は null）

挙動

• 一覧は updatedAt 降順で limit 件。status は CSV 複数指定可で、移動の作業キューとしては status=change_requested,return_in_transit のように未完了だけをまとめて引けます。
• fromSourceLocationId（送り側の梱包キュー）と toSourceLocationId（受け側の入荷待ちキュー）はどちらも任意で併用可。trackingNumber は返送便の追跡番号での入荷照合（受け側がスキャンして該当ケースを特定する用途）です。
• ケースの起票・前進（返送中 → 受領）は POST /api/routing/change-source で行います。return_received で unit は allocated に戻り通常フロー（確保 → 出荷）に合流するため、このキューからは終端として外れます。
• shipmentId 指定時はレスポンス直下に resolvedRoutingOrderId（解決した注文の uuid。shipment がこの shop に無ければ null + 空一覧）を echo します。クライアントはこのフィールドが返った場合のみ shipmentId 解決を信頼してください（旧サーバーは未知パラメータを無視して全件を返すため）。
• enrich（注文 / 商品 / ロケーション）が解決できない要素は隠さず null を返します（検索一覧のため 500 にはしません）。
• 明細単位の付帯情報（properties 等の PII）・返送ラベル PDF の保存パス・ラベルエラー本文はレスポンスに含めません。

エラー

エンドポイント固有:

Status	条件	レスポンス例
400	status が許可値外（shipments / source-changes）	{ "ok": false, "error_kind": "invalid_status", "error": "invalid status: ...", "allowed": [...] }
400	fromSourceLocationId / toSourceLocationId が uuid でない（source-changes）	{ "ok": false, "error": "fromSourceLocationId must be a uuid" }
400	trackingNumber が 100 文字超（source-changes）	{ "ok": false, "error": "trackingNumber too long" }
400	fromLocationId が uuid でない（shipments）	{ "ok": false, "error": "fromLocationId must be a uuid" }
400	fulfillmentSourceLocationId が uuid でない（shipments）	{ "ok": false, "error": "fulfillmentSourceLocationId must be a uuid" }
400	fromLocationId と fulfillmentSourceLocationId を同時指定（shipments）	{ "ok": false, "error": "fromLocationId and fulfillmentSourceLocationId are mutually exclusive" }
400	dateFrom / dateTo が ISO 8601 でない・dateFrom > dateTo（shipments）	{ "ok": false, "error": "dateFrom must be <= dateTo" }
400	limit が正整数でない	{ "ok": false, "error": "limit must be a positive integer" }
400	barcode が 100 文字超（unallocated-orders）	{ "ok": false, "error": "barcode too long" }

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

データモデル

• sot.lm_fulfillment_shipments / sot.lm_fulfillment_units — Units の出荷元ヘッダ・単位明細（shipments の一覧・サマリ・picked 進捗）。
• sot.lm_fulfillment_source_members — 出荷元 → メンバー在庫ロケーションの紐付け（1:N）。fulfillmentSourceLocationId フィルタで is_active=true な inventory_location_id 集合を解決し from_location_id を絞り込みます。
• sot.lm_routing_orders — 注文ヘッダ。配送先（ship_to_*）は PII で公開 view からは除外され、本 API は operator JWT 認証下で service_role により直接参照します。
• sot.lm_routing_decisions — routing 判定結果（unallocated-orders の引当不能行）。
• sot.lm_fulfillment_source_changes — 出荷元変更（拠点間移動）ケース。旧/新出荷元・返送追跡番号・ライフサイクル（Source Change）。source-changes の一覧本体。
• sot.products / sot.locations — 商品マスター / 拠点マスター（barcode・ロケーション ID の enrich）。