> 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/allocation.md).

# Routing Allocation — 引き当て暫定確定通知

[Routing](/lmile-docs/routing-api/orders.md)（`/api/routing/orders`）で**在庫引き当てが暫定確定したとき**（= 引き当て先ロケーションが決まった瞬間）に通知します。引き当て先ロケーションごとに 1 通ずつ送信し、引き当て不能の明細があれば `unallocated` イベントを 1 通追加します。どのロケーションから出荷されるかを外部 OMS・カートへ即時反映する用途を想定しています。

> **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/allocation-webhook-config` | shop 単位の引き当て暫定確定 webhook 送信先設定を登録 / 更新（upsert） |

***

## `POST` /api/routing/allocation-webhook-config

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

### リクエスト

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

```json
{
  "shop": "demo-store.myshopify.com",
  "destinationUrl": "https://oms.example.com/lmile/allocation",
  "authType": "bearer",
  "authSecret": "oms-api-token-xxxxx",
  "payloadTemplate": {
    "order": "{{externalOrderRef}}",
    "location": "{{fromLocationLabel}}",
    "result": "{{allocationStatus}}",
    "items": "{{lines}}"
  },
  "isActive": true
}
```

> 設定後は、[`/api/routing/orders`](/lmile-docs/routing-api/orders.md) のルーティング完了直後に、引き当て先ロケーションごとに 1 通（`allocationStatus: "allocated"`）、引き当て不能明細があれば追加で 1 通（`allocationStatus: "unallocated"`、全量在庫不足 = `no_stock` 含む）を宛先へ自動 POST します（注文レスポンスは待たせずバックグラウンド送信）。

### ボディパラメータ

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

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

利用可能な変数:

| 変数                                  | 説明                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shop`                              | 店舗ドメイン                                                                                                                                                                                                                                                                                                                                                                            |
| `routingOrderId`                    | ルーティング注文 id（`sot.lm_routing_orders.id`）                                                                                                                                                                                                                                                                                                                                           |
| `shipmentId`                        | 出荷元ヘッダ id（`sot.lm_fulfillment_shipments.id`。`unallocated` イベントは `null`）                                                                                                                                                                                                                                                                                                           |
| `externalOrderRef` / `sourceSystem` | 外部注文参照 / 取込元（注文ヘッダ由来。相関用）                                                                                                                                                                                                                                                                                                                                                         |
| `fromLocationId`                    | 引き当て先（在庫ロケーション）id（`unallocated` イベントは `null`）                                                                                                                                                                                                                                                                                                                                     |
| `fromLocationLabel`                 | 引き当て先の表示名（`unallocated` イベントは `null`）                                                                                                                                                                                                                                                                                                                                             |
| `fulfillmentSourceLocationId`       | 注文の出荷元 id（[Routing](/lmile-docs/routing-api/orders.md) リクエストの `fulfillmentSourceLocationId`。注文単位の単一値で、`unallocated` イベントにも入ります。引き当て先が無い注文の出荷元解決用）                                                                                                                                                                                                                                 |
| `allocationStatus`                  | `allocated`（このロケーションに引き当て）/ `unallocated`（引き当て不能明細）                                                                                                                                                                                                                                                                                                                               |
| `tag`                               | ディスパッチ先選択タグ                                                                                                                                                                                                                                                                                                                                                                       |
| `decidedAt`                         | ルーティング判定時刻（ISO8601）                                                                                                                                                                                                                                                                                                                                                               |
| `changedAt`                         | 通知生成時刻（ISO8601）                                                                                                                                                                                                                                                                                                                                                                   |
| `lines`                             | このイベントの明細 `[{ "barcode", "sku", "productName", "quantity", "properties" }]`（`unallocated` イベントは各行に `"reason"` 付き）。出荷指示と同じ `barcode` × `properties` 単位の行に、商品情報（`sku` / `productName` = `sot.products` を barcode で解決。未登録は `null`）を付与。`properties` は明細単位の任意キー/値（[Routing の `lines[].properties`](/lmile-docs/routing-api/orders.md)。刻印テキスト等。無ければ `null`）。単一変数 `"{{lines}}"` で配列のまま描画 |

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

```json
{
  "event": "routing_allocation_decided",
  "shop": "{{shop}}",
  "routingOrderId": "{{routingOrderId}}",
  "shipmentId": "{{shipmentId}}",
  "externalOrderRef": "{{externalOrderRef}}",
  "sourceSystem": "{{sourceSystem}}",
  "fromLocationId": "{{fromLocationId}}",
  "fromLocationLabel": "{{fromLocationLabel}}",
  "fulfillmentSourceLocationId": "{{fulfillmentSourceLocationId}}",
  "allocationStatus": "{{allocationStatus}}",
  "tag": "{{tag}}",
  "decidedAt": "{{decidedAt}}",
  "changedAt": "{{changedAt}}",
  "lines": "{{lines}}"
}
```

`lines` の描画例（同一 `barcode` でも `properties` が異なれば別行のまま運びます）:

```json
// allocationStatus: "allocated"
"lines": [
  { "barcode": "4900000000011", "sku": "TSHIRT-WH-M", "productName": "コットンTシャツ ホワイト M",
    "quantity": 2, "properties": null },
  { "barcode": "4900000000011", "sku": "TSHIRT-WH-M", "productName": "コットンTシャツ ホワイト M",
    "quantity": 1, "properties": { "刻印": "Taro" } }
]

// allocationStatus: "unallocated" （引き当て不能の理由付き）
"lines": [
  { "barcode": "4900000000035", "sku": "MUG-BK", "productName": "マグカップ ブラック",
    "quantity": 1, "properties": null, "reason": "no_stock_anywhere" }
]
```

### レスポンス

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

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

### 挙動

* **発火タイミング**: [`/api/routing/orders`](/lmile-docs/routing-api/orders.md) のルーティング完了直後（= 各引き当て先の出荷元ヘッダが `allocated` で用意された時点）にバックグラウンド送信します。`/api/routing/update` / `/api/routing/reallocate` 等の再引き当てでは発火しません
* **暫定確定**: 通知時点の引き当ては暫定です。後続の[売越し再引き当て](/lmile-docs/oversell-api/oversell-reallocate.md)や[出荷元変更](/lmile-docs/oversell-api/source-change.md)で変わる場合があります。確保以降の進捗は [Fulfillment Status Webhook](/lmile-docs/webhooks/fulfillment-status.md) で追跡してください
* **イベントの分割**: 引き当て先ロケーションごとに 1 通（`allocationStatus: "allocated"`）。引き当て不能明細（[`unroutableLines`](/lmile-docs/routing-api/orders.md)）があれば、部分・全量を問わず `allocationStatus: "unallocated"`（`fromLocationId: null`）を 1 通追加します。全量在庫不足（`status: no_stock`）の注文は `unallocated` イベントのみが届きます。`unallocated` でも `fulfillmentSourceLocationId`（注文の出荷元）は入るため、出荷元単位の通知・印刷に使えます
* **明細（`lines`）の snapshot**: 明細は起票時点の引き当て結果（出荷指示と同じ `barcode` × `properties` 単位の行）に商品情報（`sku` / `productName`）を付与して outbox に snapshot し、送信時に再取得しません。非在庫サービス品（`serviceLines`）は含まれません。`properties` は名入れ等で顧客情報を含み得るため、送信ペイロードと outbox 以外（公開 read view）には出ません
* **冪等性**: `dispatched` 済み注文の同一キー再 POST（入口冪等）では発火しません。未 dispatch の同一注文を再 POST した場合は再ルーティングされ、最新の引き当て結果が改めて送信されます。受け手は `shipmentId`（`unallocated` は `routingOrderId` + `allocationStatus`）を冪等キーに最新イベントで上書きしてください

## エラー

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

## データモデル

* `sot.lm_routing_allocation_webhook_config` — shop 単位の送信設定（`UNIQUE (shop)`）
* `sot.lm_routing_allocation_events` — 引き当て結果イベント outbox + 送信ログ（`allocation_status` / `lines` snapshot / `decided_at` を記録）
* 引き当ての元: [`sot.lm_fulfillment_shipments`](/lmile-docs/fulfillment-api/fulfillment.md)（出荷元ヘッダ。ルーティング完了時に `allocated` で作成）


---

# 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/allocation.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.