> 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/shelf-api/shelves.md).

# Shelves — 棚マスタ

棚（シェルフ）の一覧を持つ API です。棚在庫・状態別在庫に新しい棚が現れると棚は自動で登録されるので、この API は **空の棚を先に登録する / 売場・バックヤードなどの区分（`zone`）を付ける / 使わなくなった棚を無効にする** ために使います。棚の在庫数は動かしません。

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

## エンドポイント

| Method | Path                       | 用途                 | テーブル         |
| ------ | -------------------------- | ------------------ | ------------ |
| `POST` | `/api/shelf/master/upsert` | 棚の登録・区分・有効 / 無効の更新 | `lm_shelves` |

***

## `POST` /api/shelf/master/upsert

拠点の棚を 1 件以上まとめて登録・更新します。すでにある棚は `zone` と `isActive` を上書きします。

### リクエスト

```http
POST https://api.lmile.io/api/shelf/master/upsert
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json
```

```json
{
  "shop": "demo-store.myshopify.com",
  "locationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "shelves": [
    { "shelfCode": "SA-A-13", "zone": "バックヤード" },
    { "shelfCode": "SA-A-14", "zone": "バックヤード" },
    { "shelfCode": "F-1", "zone": "売場", "isActive": false }
  ]
}
```

### ボディパラメータ

| パラメータ        | 型             |  必須 | 説明                         |
| ------------ | ------------- | :-: | -------------------------- |
| `shop`       | string        |  ✓  | 店舗ドメイン（API キーで呼ぶ場合は省略できます） |
| `locationId` | string (uuid) |  ✓  | 拠点（shop に実在が必須）            |
| `shelves[]`  | array         |  ✓  | 1〜500 件                    |

#### `shelves[]` オブジェクト

| パラメータ       | 型       |  必須 | 説明                                                                                   |
| ----------- | ------- | :-: | ------------------------------------------------------------------------------------ |
| `shelfCode` | string  |  ✓  | 棚コード（最大 32 文字。形式 `^[A-Z0-9]+(-[A-Z0-9]+)+$` かつ英字を 1 文字以上）。大文字へ正規化します。同じリクエストの中で重複は不可 |
| `zone`      | string  |     | 区分（売場 / バックヤードなど。最大 40 文字）。省略すると `null`（更新時は `null` で上書き）                            |
| `isActive`  | boolean |     | 省略すると `true`                                                                         |

### レスポンス

```json
{ "ok": true, "shop": "demo-store.myshopify.com", "locationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "upserted": 3 }
```

### 挙動・冪等性

* **冪等（絶対値）**: `(shop, locationId, shelfCode)` で upsert します。同じ内容の再送は同じ結果になります。
* 棚在庫の数は動きません。棚を無効にしても、その棚にある在庫はそのままです。
* 棚在庫（`receive` / `move` / `adjust` / MFC 在庫取込）や状態別在庫に新しい棚コードが現れると、この API を呼ばなくても棚は登録されます（`zone` は `null`）。

## エラー

エンドポイント固有:

| Status | 条件                         | レスポンス例                                                                                                                               |
| :----: | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|  `400` | `shelves[]` に同じ棚コードが 2 回ある | `{ "ok": false, "error_kind": "invalid_payload", "error": "shelfCode duplicated in shelves[]", "shelfCode": "SA-A-13", "index": 1 }` |
|  `422` | 棚コード形式不正                   | `{ "ok": false, "error_kind": "invalid_shelf_code", "error": "shelfCode must match ...", "shelfCode": "SA_A_13", "index": 0 }`       |
|  `422` | `locationId` が shop に存在しない | `{ "ok": false, "error_kind": "location_unresolved", "error": "location_id not found for shop" }`                                    |

共通エラー（`401` / `400` / `403` / `405` / `500` / `503`）は [Error Codes](/lmile-docs/reference/error-codes.md) を参照。

## データモデル

* `sot.lm_shelves` — 棚の一覧。`UNIQUE (shop, location_id, shelf_code)` / `zone` / `is_active`。読み取り view: `agent_read.shelves`


---

# 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/shelf-api/shelves.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.