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

# Fulfillment Status — 出荷ステータス通知

[Fulfillment](/lmile-docs/fulfillment-api/fulfillment.md) のステータス報告・確保フロー（[在庫確保](/lmile-docs/fulfillment-api/units.md) / 確保スキャン）で各出荷元（shipment）の**ステータスが変わったとき**（`allocated` → `secured` → `in_transit_to_mfc` → `packing` → `shipped` ＋ 売越サブ状態、初回報告を含む）に通知します。出荷ステータス・追跡番号を Shopify 等の EC や外部 OMS へ反映する用途を想定しています。

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

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

> 店舗受け取り（[Store Pickup](/lmile-docs/fulfillment-api/store-pickup.md)）の荷物では、`status_after` に `store_pickup_ready`（受取待ち）/ `store_pickup_handed_over`（引渡し済み）のイベントも届きます。引渡し済みは荷物の工程を `shipped` にしますが、`shipped` のイベントは送りません（発送ではないため）。

## エンドポイント

| Method | Path                                 | 用途                                                                        |
| ------ | ------------------------------------ | ------------------------------------------------------------------------- |
| `POST` | `/api/routing/status-webhook-config` | shop 単位（任意で取込元 `sourceSystem` ごと）の出荷ステータス変動 webhook 送信先設定を登録 / 更新（upsert） |

***

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

`shop` 単位（任意で取込元 `sourceSystem` ごと）で設定を upsert します。

### リクエスト

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

```json
{
  "shop": "demo-store.myshopify.com",
  "destinationUrl": "https://sync.example.com/fulfillment/status",
  "authType": "bearer",
  "authSecret": "sync-api-token-xxxxx",
  "payloadTemplate": {
    "order": "{{externalOrderRef}}",
    "status": "{{status}}",
    "tracking": "{{trackingNumber}}"
  },
  "isActive": true
}
```

> 設定後は、[`/api/routing/fulfillment`](/lmile-docs/fulfillment-api/fulfillment.md) で各出荷元の `status` が変わるたび（初回報告含む）に、`status` / `previousStatus` / `trackingNumber` / `shipmentId` / `lines`（出荷明細の barcode 単位集約）等を宛先へ自動 POST します（注文レスポンスは待たせずバックグラウンド送信）。

### ボディパラメータ

[共通パラメータ](https://lmile.gitbook.io/lmile-docs/webhooks/pages/OotbCjshtf2WFaZaqjCi#設定upsert)に加えて:

| パラメータ          | 型      |  必須 | 説明                                                                              |
| -------------- | ------ | :-: | ------------------------------------------------------------------------------- |
| `sourceSystem` | string |     | 設定を適用する取込元（イベントの `sourceSystem` と一致させる値）。省略（または空文字）するとその shop の**既定宛先**の設定になります |

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

利用可能な変数:

| 変数                                  | 説明                                                                                                                                                                                                                                             |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shop`                              | 店舗ドメイン                                                                                                                                                                                                                                         |
| `routingOrderId`                    | ルーティング注文 id（`sot.lm_routing_orders.id`）                                                                                                                                                                                                        |
| `shipmentId`                        | 出荷元ヘッダ id（`sot.lm_fulfillment_shipments.id`。受信側の冪等キーに使えます）                                                                                                                                                                                     |
| `externalOrderRef` / `sourceSystem` | 外部注文参照 / 取込元（注文ヘッダ由来。相関用）                                                                                                                                                                                                                      |
| `fromLocationId`                    | 出荷元（在庫ロケーション）id                                                                                                                                                                                                                                |
| `status`                            | 遷移後ステータス                                                                                                                                                                                                                                       |
| `previousStatus`                    | 直前ステータス（初回報告は `null`）                                                                                                                                                                                                                          |
| `trackingNumber` / `carrierCode`    | 遷移時点の追跡番号 / キャリア（確保時に採番。未採番は `null`）                                                                                                                                                                                                           |
| `trackingCompany` / `trackingUrl`   | 出荷済みにするときに手入力された配送業者の名前 / 追跡ページの URL（指定が無ければ `null`）                                                                                                                                                                                           |
| `tag`                               | ディスパッチ先選択タグ                                                                                                                                                                                                                                    |
| `transitionedAt`                    | 遷移検知時刻（ISO8601）                                                                                                                                                                                                                                |
| `changedAt`                         | 通知生成時刻（ISO8601）                                                                                                                                                                                                                                |
| `lines`                             | この shipment の出荷明細（[`sot.lm_fulfillment_units`](/lmile-docs/fulfillment-api/units.md) を barcode 単位に集約した `[{ "barcode", "sku", "quantity" }]`。単一変数 `"{{lines}}"` で配列のまま描画）。`shipped` 遷移では注文の非在庫サービス品（ショッパーバッグ等の同梱品）の barcode / 数量も合流する（下記「挙動」参照） |

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

```json
{
  "event": "fulfillment_shipment_status_changed",
  "shop": "{{shop}}",
  "routingOrderId": "{{routingOrderId}}",
  "shipmentId": "{{shipmentId}}",
  "externalOrderRef": "{{externalOrderRef}}",
  "sourceSystem": "{{sourceSystem}}",
  "fromLocationId": "{{fromLocationId}}",
  "status": "{{status}}",
  "previousStatus": "{{previousStatus}}",
  "trackingNumber": "{{trackingNumber}}",
  "carrierCode": "{{carrierCode}}",
  "trackingCompany": "{{trackingCompany}}",
  "trackingUrl": "{{trackingUrl}}",
  "tag": "{{tag}}",
  "transitionedAt": "{{transitionedAt}}",
  "changedAt": "{{changedAt}}",
  "lines": "{{lines}}"
}
```

`lines` の描画例（barcode 単位に集約。1 行 = 1 barcode、`quantity` はその shipment 内の単位数）:

```json
"lines": [
  { "barcode": "4900000000011", "sku": "TSHIRT-WH-M", "quantity": 2 },
  { "barcode": "4900000000028", "sku": "TSHIRT-WH-L", "quantity": 1 }
]
```

### レスポンス

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

| フィールド           | 説明                                                    |
| --------------- | ----------------------------------------------------- |
| `id`            | 設定行 id（`sot.lm_fulfillment_status_webhook_config.id`） |
| `source_system` | この設定が適用される取込元（既定宛先の設定は `null`）                        |
| `has_secret`    | 認証 secret が保存済か（secret 値そのものは返しません）                   |

### 挙動

* **遷移検知**: [`/api/routing/fulfillment`](/lmile-docs/fulfillment-api/fulfillment.md) で各 shipment（`routing_order × from_location`）の `status` を更新する際、**直前の値と異なる shipment だけ**イベントを起票します（初回報告 = `previousStatus: null` も対象）。同じ status の再報告では送信しません
* **取込元（`sourceSystem`）ごとの宛先**: 取込元ごとに宛先を分けられます。`sourceSystem` 指定なしの設定はその shop の**既定宛先**です。イベントは自分の取込元と一致する設定があればそちらへ、なければ既定宛先へ届きます（どちらも無い場合は送信せず `skipped` を記録します）
* **確保（secured）遷移も対象**: 確保フロー（[在庫確保](/lmile-docs/fulfillment-api/units.md) `/api/routing/secure`・[確保スキャン](/lmile-docs/operator-api/secure-scan.md) `/api/operator/secure-scan`・[追跡番号で確保](/lmile-docs/operator-api/secure-by-tracking.md) `/api/operator/secure-by-tracking`）でヘッダが `secured` に遷移したときも、同じペイロード形・同じ outbox でイベントを起票・配信します（`status: "secured"`・`previousStatus` は遷移前のヘッダ status）。`secured` 以外のステータスだけを処理する受け手には新しい status 値が届くだけで後方互換です
* **絶対状態の送信**: ペイロードは遷移後の絶対状態（`status` / `previousStatus` / `trackingNumber`）と出荷明細（`shipmentId` / `lines`）です。受け手は `shipmentId` を冪等キーに同一 shipment の再送を弾きつつ、該当明細だけを冪等に反映できます
* **明細（`lines`）の組み立て**: 送信時に shipment 配下の [`sot.lm_fulfillment_units`](/lmile-docs/fulfillment-api/units.md) を barcode 単位に集約して同梱します。units の取得に失敗した場合・0 件の場合は **lines 無しのまま送信せず** `delivery_status: failed`（`last_error: units_fetch_error / no_units_for_shipment`）として outbox に残し、再送で回収します
* **`shipped` は非在庫サービス品も `lines` に含む**: 注文に非在庫サービス品（`products.is_non_inventory = true`。ショッパーバッグ等の同梱品・刻印等のサービス行）がある場合、`shipped` 遷移の `lines` にはその barcode / 数量も合流します（在庫引き当て対象外で unit を持たないため、適用中 routing decision から補完）。routing に送られた明細は出荷済み反映の対象、という契約です。受け手が明細を残数ベースで冪等に反映していれば、複数出荷元に分割された注文でも最初の出荷 1 回だけに反映されます。`shipped` 以外の遷移の `lines` は従来どおり unit 由来のみです
* **配信タイミング**: [`/api/routing/fulfillment`](/lmile-docs/fulfillment-api/fulfillment.md) / 確保フローの成功直後にバックグラウンド送信

## エラー

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

## データモデル

* `sot.lm_fulfillment_status_webhook_config` — shop × 取込元単位の送信設定（`UNIQUE NULLS NOT DISTINCT (shop, source_system)`。`source_system` が `NULL` の行 = その shop の既定宛先）
* `sot.lm_fulfillment_status_events` — status 遷移イベント outbox + 送信ログ（`status_before` / `status_after` / `tracking_number` を記録）
* 遷移の元: [`sot.lm_fulfillment_shipments`](/lmile-docs/fulfillment-api/fulfillment.md)（出荷元ヘッダ = 梱包単位 / 注文 × from\_location）の `status` 列


---

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