> 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/webhooks/oversell-status.md).

# Oversell Status — 売越しケース受付完了通知

[Oversell Cases](/lmile-docs/oversell-api/cases.md)（`/api/routing/oversell-case`）で売越しケースが **MFC 倉庫で受付完了（`warehouse_received`）に遷移したとき**に通知します。1 ケース = 1 販売単位（fulfillment unit）なので 1 遷移 = 1 通です。確保元ロケーション（`found_location_id`）からの出庫分が MFC センターで受付完了したことを外部システムへ伝え、スマレジ等への入庫処理を実行する用途を想定しています（商品解決は `barcode` 経由）。

> **Base URL** `https://api.lmile.io` · **認証** `x-ingest-secret` ヘッダー（[詳細](/lmile-docs/getting-started/authentication.md)） · `shop` はリクエストボディに含めます（省略するとキーのアカウント）

> 配信・リトライ・暗号化など共通の仕組みは [Webhooks 概要](/lmile-docs/webhooks/overview.md)を参照。

## エンドポイント

| Method | Path                                          | 用途                                               |
| ------ | --------------------------------------------- | ------------------------------------------------ |
| `POST` | `/api/routing/oversell-status-webhook-config` | shop 単位の売越しケース受付完了 webhook 送信先設定を登録 / 更新（upsert） |

***

## `POST` /api/routing/oversell-status-webhook-config

`shop` 単位で設定を upsert します。

### リクエスト

```http
POST https://api.lmile.io/api/routing/oversell-status-webhook-config
x-ingest-secret: {INGEST_SECRET}
Content-Type: application/json
```

```json
{
  "shop": "demo-store.myshopify.com",
  "destinationUrl": "https://sync.example.com/oversell/warehouse-received",
  "authType": "bearer",
  "authSecret": "sync-api-token-xxxxx",
  "payloadTemplate": {
    "order": "{{externalOrderRef}}",
    "case": "{{oversellCaseId}}",
    "receivedLocation": "{{foundLocationId}}",
    "items": "{{lines}}"
  },
  "isActive": true
}
```

> 設定後は、[`/api/routing/oversell-case`](/lmile-docs/oversell-api/cases.md) でケースが `warehouse_received` に遷移するたびに、`oversellCaseId` / `foundLocationId` / `lines`（`barcode` 単位）等を宛先へ自動 POST します（操作レスポンスは待たせずバックグラウンド送信）。

### ボディパラメータ

[共通パラメータ](https://lmile.gitbook.io/lmile-docs/webhooks/pages/OotbCjshtf2WFaZaqjCi#設定upsert)のみです（固有パラメータなし）。

### ペイロードテンプレート

利用可能な変数:

| 変数                                  | 説明                                                                                                                                                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shop`                              | 店舗ドメイン                                                                                                                                                                                                  |
| `routingOrderId`                    | ルーティング注文 id（`sot.lm_routing_orders.id`）                                                                                                                                                                 |
| `oversellCaseId`                    | 売越しケース id（`sot.lm_oversell_cases.id`。受信側の冪等キーに使えます）                                                                                                                                                     |
| `fulfillmentUnitId`                 | 対象の販売単位 id（`sot.lm_fulfillment_units.id`）                                                                                                                                                               |
| `externalOrderRef` / `sourceSystem` | 外部注文参照 / 取込元（注文ヘッダ由来。相関用）                                                                                                                                                                               |
| `foundLocationId`                   | 確保元（出庫元）= 受領（入庫）元ロケーション id（`sot.lm_oversell_cases.found_location_id`。未設定は `null`）                                                                                                                       |
| `status`                            | 常に `warehouse_received`（本 webhook は受付完了の 1 種別のみ）                                                                                                                                                        |
| `tag`                               | ディスパッチ先選択タグ                                                                                                                                                                                             |
| `warehouseReceivedAt`               | ケースの受付完了時刻（ISO8601）                                                                                                                                                                                     |
| `changedAt`                         | 通知生成時刻（ISO8601）                                                                                                                                                                                         |
| `lines`                             | このケースの明細 `[{ "barcode", "sku", "productName", "quantity" }]`。1 ケース = 1 単位のため 1 行（`quantity` は常に `1`）。商品情報（`sku` / `productName`）は `sot.products` を barcode で解決（未登録は `null`）。単一変数 `"{{lines}}"` で配列のまま描画 |

省略時の既定テンプレート:

```json
{
  "event": "oversell_case_warehouse_received",
  "shop": "{{shop}}",
  "routingOrderId": "{{routingOrderId}}",
  "oversellCaseId": "{{oversellCaseId}}",
  "fulfillmentUnitId": "{{fulfillmentUnitId}}",
  "externalOrderRef": "{{externalOrderRef}}",
  "sourceSystem": "{{sourceSystem}}",
  "foundLocationId": "{{foundLocationId}}",
  "status": "{{status}}",
  "tag": "{{tag}}",
  "warehouseReceivedAt": "{{warehouseReceivedAt}}",
  "changedAt": "{{changedAt}}",
  "lines": "{{lines}}"
}
```

`lines` の描画例（1 ケース = 1 単位 = 1 行、`quantity` は常に `1`）:

```json
"lines": [
  { "barcode": "4900000000011", "sku": "TSHIRT-WH-M", "productName": "コットンTシャツ ホワイト M", "quantity": 1 }
]
```

### レスポンス

```json
{ "ok": true, "id": "c0ffee00-...", "shop": "demo-store.myshopify.com",
  "is_active": true, "has_secret": true }
```

| フィールド        | 説明                                                 |
| ------------ | -------------------------------------------------- |
| `id`         | 設定行 id（`sot.lm_oversell_status_webhook_config.id`） |
| `has_secret` | 認証 secret が保存済か（secret 値そのものは返しません）                |

### 挙動

* **発火タイミング**: [`/api/routing/oversell-case`](/lmile-docs/oversell-api/cases.md) でケースが `warehouse_received`（8 ステップ目の MFC 倉庫受付完了）に遷移した直後にバックグラウンド送信します。他のステップ遷移（`locating` / `contacted` / `stock_secured` 等）では発火しません
* **絶対状態の送信**: `status` は常に `warehouse_received` です。受け手は `oversellCaseId` を冪等キーに、確保元（`foundLocationId`）からの出庫分の入庫を冪等に反映できます
* **明細（`lines`）の snapshot**: 明細は起票時点の `barcode` に商品情報（`sku` / `productName`）を付与して outbox に snapshot し、送信時に再取得しません。1 ケース = 1 販売単位のため常に 1 行・`quantity: 1` です
* **冪等性**: outbox は `UNIQUE (oversell_case_id)` のため、同一ケースのイベントは 1 件しか起票しません（二重発行を防止）。`warehouse_received` は終端ステップで再遷移できないため、通常は 1 ケースにつき 1 通だけ届きます

## エラー

エンドポイント固有のエラーはありません。共通エラーは [Webhooks 概要](https://lmile.gitbook.io/lmile-docs/webhooks/pages/OotbCjshtf2WFaZaqjCi#エラー) / [Error Codes](/lmile-docs/reference/error-codes.md) を参照。

## データモデル

* `sot.lm_oversell_status_webhook_config` — shop 単位の送信設定（`UNIQUE (shop)`）
* `sot.lm_oversell_status_events` — ケース受付完了イベント outbox + 送信ログ（`oversell_case_id` / `found_location_id` / `lines` snapshot / `warehouse_received_at` を記録。`UNIQUE (oversell_case_id)`）
* 遷移の元: [`sot.lm_oversell_cases`](/lmile-docs/oversell-api/cases.md)（売越し 8 ステップ管理）の `status` 列が `warehouse_received` になった瞬間


---

# 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/webhooks/oversell-status.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.