> For the complete documentation index, see [llms.txt](https://lmile.gitbook.io/lmile-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lmile.gitbook.io/lmile-docs/operator-api/lookup.md).

# Operator Lookup — 倉庫スタッフ向け照会

ピッキングアプリ（picking-ios）が倉庫オペレーションで使う read 専用の照会 API です。ラベルの追跡番号から shipment・注文・明細・配送先・状態を引く、バーコードから商品情報を引く、追跡番号 / ステータスで売越しケースを検索する、の 3 種です。いずれも書き込みは行いません。

> **Base URL** `https://api.lmile.io` · **認証** operator JWT（`Authorization: Bearer`）（[詳細](/lmile-docs/getting-started/authentication.md)） · `shop` は query に含めます

## エンドポイント

| Method | Path                                  | 用途                                         | テーブル                                                                                                                        |
| ------ | ------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `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/*` の認証系統は [認証](https://lmile.gitbook.io/lmile-docs/operator-api/pages/7cB70I8yeRnMpvcdLkNu#operator-jwt-認証) を参照してください。
>
> 倉庫スタッフの棚運用（ユニットQR でのユニット照会・棚コード照会・ピック）は [Shelf Lookup](/lmile-docs/shelf-api/lookup.md)（`/api/operator/shelf/*`）に、ユニットQR での在庫確保は [Secure Scan](/lmile-docs/operator-api/secure-scan.md)（`/api/operator/secure-scan`）にあります。

***

## `GET` /api/operator/shipments/by-tracking

ラベルの追跡番号をスキャンし、その追跡番号を持つ shipment（出荷元単位の梱包）と、属する注文ヘッダ・unit 明細・配送先・出荷元別の状態を返します。同一追跡番号が複数 shipment（別注文 / 再発行）に当たりうるため配列（`created_at` 降順）で返します。

### リクエスト

```http
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 文字）    |

### レスポンス

```json
{
  "ok": true,
  "count": 1,
  "shipments": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "secured",
      "trackingNumber": "4912345678901",
      "carrierCode": "yamato",
      "fromLocationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "fromLocationLabel": "大阪MFC",
      "securedAt": "2026-06-07T09:00:00.000Z",
      "inTransitAt": null,
      "packingStartedAt": null,
      "shippedAt": null,
      "cancelledAt": null,
      "labelVoidedAt": null,
      "labelVoidReason": null,
      "consolidationShelfCode": "R-01",
      "consolidationLabelPlacedAt": null,
      "consolidationGroupId": null,
      "shelfLink": {
        "shelfCode": "F-18",
        "locationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "linkedAt": "2026-06-07T10:00:00.000Z"
      },
      "order": {
        "id": "7b1f08a3-1234-4abc-9def-0123456789ab",
        "orderNumber": "1001",
        "orderName": "BJP1001",
        "sourceSystem": "shopify",
        "status": "routed",
        "shipTo": {
          "name": "山田 太郎",
          "company": null,
          "phone": "+819012345678",
          "email": "taro@example.com",
          "country": "JP",
          "postalCode": "150-0001",
          "prefecture": "東京都",
          "city": "渋谷区",
          "address1": "道玄坂1-2-3",
          "address2": null
        },
        "serviceLines": [
          {
            "barcode": "4589903599585",
            "sku": "SSB1S-BK",
            "productName": "ショッパーバッグ (Sサイズ)",
            "variantName": "ブラック",
            "quantity": 1
          }
        ]
      },
      "units": [
        {
          "id": "uuuuuuuu-1111-2222-3333-444444444444",
          "barcode": "4912345678901",
          "sku": "SKU-001",
          "lineInstanceNo": 1,
          "status": "secured",
          "secured": true,
          "shelfCode": "A-01-01",
          "productName": "サンプル商品",
          "variantName": "M",
          "imageUrl": "https://.../image.jpg",
          "giftWrap": false,
          "sourceChange": null
        }
      ]
    }
  ]
}
```

| フィールド                               | 説明                                                                                                                                                                                                                                                                    |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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](/lmile-docs/shelf-api/link.md) の `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 のため返さず、導出した真偽値のみ                                                                                                                |
| `units[].sourceChange`              | [出荷元変更](/lmile-docs/oversell-api/source-change.md)（拠点間移動）の状態。移動フロー中なら `{ id, status, toSourceLocationId, toSourceLocationLabel, batchId, returnTrackingNumber }`（`batchId` は[倉庫間移動バルク](/lmile-docs/transfer-api/batches.md)所属時）。フロー外は `null`。iOS の「移動対象 → 移動画面へ」案内に使う |

### 挙動

* 該当 shipment が無ければ `404 shipment_not_found`。
* shipment が指す注文ヘッダが引けない不整合は隠さず `500 data_inconsistency` で表面化します（`null` で誤魔化しません）。

***

## `GET` /api/operator/products/by-barcode

バーコードをスキャンし、該当商品の基本情報（名前 / SKU / 画像 / カテゴリ / 価格 等）を返します。`(shop, barcode)` は一意運用です。

### リクエスト

```http
GET https://api.lmile.io/api/operator/products/by-barcode?shop=demo-store.myshopify.com&barcode=4912345678901
Authorization: Bearer {OPERATOR_JWT}
```

| クエリ       | 型      |  必須 | 説明                     |
| --------- | ------ | :-: | ---------------------- |
| `shop`    | string |  ✓  | 店舗ドメイン（スタッフの束縛 shop 内） |
| `barcode` | string |  ✓  | 商品バーコード（最大 100 文字）     |

### レスポンス

```json
{
  "ok": true,
  "product": {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "barcode": "4912345678901",
    "sku": "SKU-001",
    "productName": "サンプル商品",
    "variantName": "M",
    "brand": "Sample Brand",
    "categoryL1": "アパレル",
    "categoryL2": "トップス",
    "categoryL3": "Tシャツ",
    "currentPrice": 3200,
    "currency": "JPY",
    "primaryImageUrl": "https://.../image.jpg",
    "isActive": true,
    "isNonInventory": false,
    "lifecycleStatus": "active"
  }
}
```

| フィールド                                                       | 説明                                 |
| ----------------------------------------------------------- | ---------------------------------- |
| `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` 降順）で返します。

### リクエスト

```http
GET https://api.lmile.io/api/operator/oversell-cases?shop=demo-store.myshopify.com&trackingNumber=4912345678901&status=dispatched&limit=50
Authorization: Bearer {OPERATOR_JWT}
```

| クエリ              | 型      |  必須 | 説明                            |
| ---------------- | ------ | :-: | ----------------------------- |
| `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`

### レスポンス

```json
{
  "ok": true,
  "count": 1,
  "cases": [
    {
      "id": "cccccccc-dddd-eeee-ffff-000000000000",
      "status": "dispatched",
      "barcode": "4912345678901",
      "lineInstanceNo": 1,
      "trackingNumber": "4912345678901",
      "externalShipmentRef": null,
      "note": null,
      "wontDoReason": null,
      "foundLocationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "foundLocationLabel": "大阪店",
      "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": "oversell_in_progress" },
      "contactedAt": null,
      "securedAt": "2026-06-07T08:00:00.000Z",
      "dispatchRequestedAt": "2026-06-07T08:30:00.000Z",
      "dispatchedAt": "2026-06-07T09:00:00.000Z",
      "warehouseReceivedAt": null,
      "wontDoAt": null,
      "openedAt": "2026-06-07T07:00:00.000Z",
      "createdAt": "2026-06-07T07:00:00.000Z",
      "updatedAt": "2026-06-07T09:00:00.000Z"
    }
  ]
}
```

| フィールド                                    | 説明                                     |
| ---------------------------------------- | -------------------------------------- |
| `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` にはしません）。

## エラー

エンドポイント固有:

| Status | 条件                                                  | レスポンス例                                                                                                     |
| :----: | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|  `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](/lmile-docs/reference/error-codes.md) を参照。

## データモデル

* `sot.lm_fulfillment_shipments` / `sot.lm_fulfillment_units` — [Units](/lmile-docs/fulfillment-api/units.md) の出荷元ヘッダ・単位明細。
* `sot.lm_routing_orders` — 注文ヘッダ。配送先（`ship_to_*`）は PII で公開 view からは除外され、本 API は operator JWT 認証下で service\_role により直接参照します。
* `sot.lm_oversell_cases` — [売越しケース](/lmile-docs/oversell-api/cases.md)。
* `sot.products` / `sot.locations` — 商品マスター / 拠点マスター（barcode・ロケーション ID の enrich）。
* `sot.lm_shelf_inventory` — 棚在庫（`shipments/by-tracking` の `units[].shelfCode` の解決元。`qty>0` 優先・同点 `shelf_code` 昇順）。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://lmile.gitbook.io/lmile-docs/operator-api/lookup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.