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

# Order Update — 受注情報更新通知

[Address Recovery](/lmile-docs/fulfillment-api/address-recovery.md)（`/api/routing/shipment/address`）で受注の**配送先住所を手修正したとき**に通知します。外部 EC / WMS / 基幹システムが受信して、自システム側の配送先を LMile の最新状態に同期する用途を想定しています。変更種別 `changeType` を持ち、当面は住所修正（`address_corrected`）の 1 種です（将来、明細プロパティ修正など他の更新種別も同じ webhook に `changeType` を追加して載せられます）。

> **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/order-update-webhook-config` | shop 単位の受注情報更新 webhook 送信先設定を登録 / 更新（upsert） |

***

## `POST` /api/routing/order-update-webhook-config

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

### リクエスト

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

```json
{
  "shop": "demo-store.myshopify.com",
  "destinationUrl": "https://sync.example.com/order/updated",
  "authType": "bearer",
  "authSecret": "sync-api-token-xxxxx",
  "payloadTemplate": {
    "order": "{{externalOrderRef}}",
    "change": "{{changeType}}",
    "address": "{{shipTo}}"
  },
  "isActive": true
}
```

> 設定後は、[`/api/routing/shipment/address`](/lmile-docs/fulfillment-api/address-recovery.md) で配送先住所を手修正するたびに、`changeType` / 修正後の `shipTo` / `correctedAt` 等を宛先へ自動 POST します（操作レスポンスは待たせずバックグラウンド送信）。

### ボディパラメータ

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

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

利用可能な変数:

| 変数                                  | 説明                                                                                                                                                                   |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shop`                              | 店舗ドメイン                                                                                                                                                               |
| `changeType`                        | 変更種別。当面は `address_corrected`（住所修正）のみ                                                                                                                                 |
| `routingOrderId`                    | ルーティング注文 id（`sot.lm_routing_orders.id`）                                                                                                                              |
| `externalOrderRef` / `sourceSystem` | 外部注文参照 / 取込元（注文ヘッダ由来。相関用）                                                                                                                                            |
| `shipTo`                            | **修正後**の配送先住所オブジェクト `{ name, company, phone, email, country, postalCode, prefecture, city, address1, address2 }`。単一変数 `"{{shipTo}}"` でオブジェクトのまま描画。**個人情報（PII）を含みます** |
| `correctedAt`                       | 修正発生時刻（ISO8601）                                                                                                                                                      |
| `correctedBy`                       | 修正者。operator 経由なら検証済の `staffUserId`（`auth.users.id`）、機械間（ingest secret）経由なら任意の `correctedBy`、いずれも無ければ `null`                                                         |
| `changedAt`                         | 通知生成時刻（ISO8601）                                                                                                                                                      |

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

```json
{
  "event": "order_update",
  "changeType": "{{changeType}}",
  "shop": "{{shop}}",
  "routingOrderId": "{{routingOrderId}}",
  "sourceSystem": "{{sourceSystem}}",
  "externalOrderRef": "{{externalOrderRef}}",
  "shipTo": "{{shipTo}}",
  "correctedAt": "{{correctedAt}}",
  "correctedBy": "{{correctedBy}}",
  "changedAt": "{{changedAt}}"
}
```

`shipTo` の描画例:

```json
"shipTo": {
  "name": "山田 太郎",
  "company": null,
  "phone": "09012345678",
  "email": "taro@example.com",
  "country": "JP",
  "postalCode": "1500001",
  "prefecture": "東京都",
  "city": "渋谷区神宮前",
  "address1": "1-2-3",
  "address2": "サンプルマンション101"
}
```

### レスポンス

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

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

### 挙動

* **発火タイミング**: [`/api/routing/shipment/address`](/lmile-docs/fulfillment-api/address-recovery.md) で配送先住所の手修正が成功した直後にバックグラウンド送信します。住所マージ後の検証に失敗した修正（`422`）では発火しません
* **修正後の絶対状態の送信**: `shipTo` は\*\*修正後（マージ後）\*\*の住所全体です。差分ではなく絶対状態を送るため、受け手は `routingOrderId` を冪等キーに、`correctedAt` で順序判断しながら最新の配送先で冪等に上書きできます
* **`shipTo` の snapshot**: 配送先は起票時点の修正後住所を outbox に snapshot し、送信時に再取得しません。後続の再修正があっても当時の内容を再送できます
* **冪等性**: 1 注文に対し複数回の住所修正が起こり得る（修正 → 再修正）ため、outbox は `UNIQUE` 制約を持たず **1 修正 = 1 event** を起票します。受け手は `routingOrderId` + `correctedAt` で順序を判断してください

## エラー

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

## データモデル

* `sot.lm_order_update_webhook_config` — shop 単位の送信設定（`UNIQUE (shop)`）
* `sot.lm_order_update_events` — 受注更新イベント outbox + 送信ログ（`change_type` / 修正後 `ship_to` snapshot / `corrected_at` / `corrected_by` を記録。`ship_to` は PII のため公開 view 非露出・service\_role 限定）
* 発火の元: [`sot.lm_routing_orders`](/lmile-docs/routing-api/orders.md) の `ship_to_*` 列が [`/api/routing/shipment/address`](/lmile-docs/fulfillment-api/address-recovery.md) で更新された瞬間


---

# 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/order-update.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.