> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lymo.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# 非同期パターン

> analyses / scorings のライフサイクル

<Note>
  本ガイドは [クイックスタート](/guides/quickstart) で `$LYMO_KEY`・`$LYMO_BASE`・`$VIDEO` を設定済みであることを前提とします。`$LYMO_BASE` は `/platform` までで、バージョン付きパスは `/v1` 配下です。
</Note>

Platform API における長時間処理は、**ステータスを自身で保持するドメインリソース** としてモデル化されています。不透明なジョブ ID ではありません。該当リソースは現時点で 2 種類です。

* `POST /v1/videos/:id/analyses` — 動画を分析
* `POST /v1/deals/:id/scorings` — 案件をスコアリング

どちらも作成直後に `201` と `status: "processing"`、および安定した `id` を返します。完了はリソースをポーリングするか、Webhook を購読して取得してください。

## ライフサイクル

```
POST   /v1/videos/:id/analyses           → 201 { id, status: "processing", ... }
GET    /v1/videos/:id/analyses/:id       → 200 { id, status: "processing" | "completed" | "failed", ... }
GET    /v1/videos/:id/analyses           → 200 { data: [履歴 ...] }
```

## ステータス値

外部ステータスは、内部ワークフローの複数の状態を 3 値に集約したものです。

| ステータス        | 意味                                       |
| ------------ | ---------------------------------------- |
| `processing` | キュー投入済み、または処理中                           |
| `completed`  | 正常終了。`result` に結果が格納される                  |
| `failed`     | 終端的な失敗。`error: { code, message }` が付与される |

`completed` または `failed` に到達したリソースは、それ以上遷移しません。

## 完了結果の読み取り

分析やスコアリングが `completed` になると、同じ GET エンドポイントのレスポンスに `result` フィールドが加わります。フィールドごとの完全なスキーマは **APIリファレンス** タブを参照してください。概要は以下のとおりです。

* **分析（Analyses）** — `result` には要約セクション、チェックリスト評価（組織で有効な場合）、検出された営業イベントが含まれます。個別に取得したい場合は `GET /v1/videos/:id/summary`、`.../checklist`、`.../events` を使ってください。
* **スコアリング（Scorings）** — `result` には案件に対して算出されたスコア因子が含まれます。`GET /v1/deals/:id` でも同じ因子を参照できます。

`failed` の場合は `result` の代わりに `error: { code, message }` が入ります。`code` は機械判読用の安定した文字列で、switch で分岐できます。`message` は人間向けの説明で、バージョン間で変わる可能性があります。

エンドツーエンドの処理時間は通常、分単位の範囲です。ポーリング間隔は 5〜10 秒で十分です。処理が本当に詰まった場合は内部のタイムアウトで `failed` に遷移するため、API 側がリソースを永遠に `processing` のままにすることはありません。

## ポーリング

```bash theme={null}
ANALYSIS=$(curl -s -X POST "$LYMO_BASE/v1/videos/$VIDEO/analyses" \
  -H "Authorization: Bearer $LYMO_KEY" | jq -r .data.id)

while true; do
  STATUS=$(curl -s "$LYMO_BASE/v1/videos/$VIDEO/analyses/$ANALYSIS" \
    -H "Authorization: Bearer $LYMO_KEY" | jq -r .data.status)
  [ "$STATUS" != "processing" ] && break
  sleep 5
done

echo "Analysis finished with status: $STATUS"
```

ポーリング間隔は 5 秒を推奨します。`429` レスポンスには `Retry-After` ヘッダーが付くので、即時再試行せず必ずこれに従ってください。

## 冪等性

POST リクエストでは `Idempotency-Key` ヘッダーを受け付けます。最初の 2xx レスポンスは 24 時間キャッシュされ、キーは `(組織, メソッド, パス, キー, ボディハッシュ)` の組で管理されます。再送時は同じレスポンスがそのまま返されます。

```bash theme={null}
curl -X POST "$LYMO_BASE/v1/videos/$VIDEO/analyses" \
  -H "Authorization: Bearer $LYMO_KEY" \
  -H "Idempotency-Key: $(openssl rand -hex 16)"
```

同じキーで異なるボディを送ると、キャッシュキーが一致しないため別の処理として扱われます。つまり、ペイロードが違う再送で想定外のレスポンスを受け取る事故は起きません。

<Warning>
  元リソースが削除または再処理されていても、キャッシュされたレスポンスがそのまま返ります。新規リクエストとして強制したい場合は新しい `Idempotency-Key` を送ってください。キーが 256 文字を超えると `400 bad_request` になります。
</Warning>

クライアントタイムアウトで POST の成否が曖昧になるような場面では、必ず冪等キーを使ってください。

## ポーリングの代わりに購読する

本番ワークロードでは Webhook を登録して Lymo からの通知を受け取るのが推奨です。

* `video.analysis.completed`
* `video.analysis.failed`

<Info>
  案件スコアリング系イベント（`deal.scoring.completed`・`deal.scoring.failed`）は、SDK の型を安定させる目的でスキーマには定義されていますが、配信側はまだ実装されていません。現時点で購読しても通知は届きません。将来のリリースで有効化予定です。
</Info>

Webhook の登録、署名検証、イベント一覧は [Webhook](/guides/webhooks) を参照してください。