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

# Apps 概要

LMile 上で発生したイベント（在庫引き当ての暫定確定など）を検知して、コードで書いた自動処理（外部システム連携・通知・LMile API への write-back）を実行する仕組みです。アプリは LMile がホストする専用の実行環境（1 アプリ = 1 VM、相互に隔離）で動くため、受け手のサーバーを自前で運用する必要がありません。

> **ステータス: プレビュー** — アプリの登録・デプロイ・環境変数の設定は現在 LMile 運用が行います（<admin@lmile.io>）。開発者は SDK（[`@lmile/app-kit`](/lmile-docs/apps/sdk.md)）でアプリ本体のコードだけを書きます。

## Webhooks との使い分け

|                        | [Webhooks](/lmile-docs/webhooks/overview.md) | Apps                                   |
| ---------------------- | -------------------------------------------- | -------------------------------------- |
| 受け手                    | 自前のサーバー（宛先 URL を登録）                          | LMile がホストする専用 VM                      |
| 実装                     | 任意の言語・任意の処理                                  | TypeScript（`@lmile/app-kit` の handler） |
| ペイロード                  | テンプレートで自由に整形                                 | 型付きイベント（固定スキーマ）                        |
| 明細の `properties`（名入れ等） | 同梱される                                        | 含まれない（PII 保護）                          |
| 向く用途                   | 既存システムへの直接通知・取込                              | 「検知 → 判断 → LMile API を呼び返す」自動処理        |

同じ発火点から両方へ並走して配信されるため、併用できます。

## 動作モデル

1. **購読** — アプリは manifest で購読イベントを宣言します
2. **配信** — イベント発生時、購読アプリの VM へ型付き JSON が配信されます。イベントは送信前に outbox へ記録され、失敗しても回収・再送できます
3. **実行** — handler が実行されます。LMile API の呼び返しは `ctx.api`（認証キーは実行環境が注入し、アプリのコードには書きません）
4. **記録** — 実行結果（成功 / 失敗 / timeout・所要時間・構造化ログ）が実行ログに記録されます

### 配信の性質

* **at-least-once / 順序保証なし** — handler は冪等・順序非依存で書きます（[SDK](/lmile-docs/apps/sdk.md) / [Idempotency](/lmile-docs/reference/idempotency.md#apps)）
* handler の失敗（例外 / timeout）は配信失敗として記録され、LMile が自動で再送します（silent skip しません）
* **再送の回数と間隔** — 失敗した配信は、5 分・30 分・2 時間・5 時間と間隔を空けて送り直します（既定は合計 6 回・約 7.5 時間）。印刷のように遅れて届くと困るイベントは、少ない回数で打ち切ります。打ち切った配信は LMile 運用に通知され、必要なら手動で送り直します
* **送り直さないイベント** — 送信元のシステムが自分で再送するイベント（倉庫への出荷指示など、結果をその場で返すもの）は、LMile は送り直しません。同じ指示が二重に届かないようにするためです
* **timeout で処理が止まる** — handler の実行が上限を超えると `ctx.signal` が中断されます。外部への呼び出しには `ctx.signal` を渡してください（[SDK](/lmile-docs/apps/sdk.md)）
* **配信の本人確認** — 配信には [Standard Webhooks](https://www.standardwebhooks.com/) 形式の署名（`webhook-id` / `webhook-timestamp` / `webhook-signature`）が付き、実行環境が handler を呼ぶ前に確かめます。`webhook-id` は `ctx.idempotencyKey` と同じ値です
* **形の確認** — イベントの中身は、handler を呼ぶ前に [イベントの型定義](https://lmile.gitbook.io/lmile-docs/apps/pages/frBVnx0tU1VgZ8LoBoIu#型定義-json-schema) で確かめます。形が合わないイベントは handler に渡りません
* **PII 保護** — 明細の `properties`（名入れ等の任意キー/値）と配送先住所は、アプリ向けイベントに含まれません

## 購読できるイベント

| イベント                                                       | 内容                       | 状態      |
| ---------------------------------------------------------- | ------------------------ | ------- |
| [`routing_allocation_decided`](/lmile-docs/apps/events.md) | ルーティングで在庫引き当てが暫定確定       | **配信中** |
| `fulfillment_shipment_status_changed`                      | 出荷元（shipment）の出荷ステータスが遷移 | 準備中     |
| `fulfillment_source_inventory_changed`                     | 出荷元の合算販売可能在庫が変動          | 準備中     |

## 利用開始

1. [SDK — アプリの書き方](/lmile-docs/apps/sdk.md)を読んでアプリを書く
2. LMile（<admin@lmile.io>）にアプリの登録・デプロイを依頼する（アプリ名 / 対象 shop / 購読イベント / 必要な環境変数キーを共有）
3. 配信開始後の実行結果・配信状態は LMile 側で確認できます（失敗イベントの再送も LMile 運用が行います）

## 次のステップ

1. [SDK — アプリの書き方](/lmile-docs/apps/sdk.md)
2. [Events — 購読できるイベント](/lmile-docs/apps/events.md)
3. [Idempotency](/lmile-docs/reference/idempotency.md#apps) — 配信と handler の冪等性


---

# 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/apps/overview.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.