# 非同期タスクモデル — ドキュメントとバッチの処理ステータス

> v1 APIにおけるドキュメントとバッチの非同期処理の仕組み — queued/processing/succeeded/failed/canceledのステートマシンと、created_at/started_at/completed_atのタイムスタンプチェーンについて解説します。

ドキュメントをアップロードしても処理は開始されず、処理を開始しても同じリクエスト内で完了するとは限りません。すべてのドキュメントとバッチは、固定された閉じたステータスのセットを遷移します。このページでは、そのライフサイクルを最初から最後まで解説します。

## ステータスライフサイクル

すべてのドキュメント（および集約されたすべてのバッチ）は、常に次の5つの状態のいずれかにあります。

```text
queued → processing → succeeded | failed | canceled
```

- `queued` — アップロード済み、またはワーカーが取得するのを待機中。
- `processing` — ワーカーがドキュメントを取得し、データ抽出を実行中。
- `succeeded` — 抽出が完了。結果レスポンスの`line_items`が設定されます。
- `failed` — このドキュメントの抽出を完了できませんでした（これは*ドキュメントレベル*の結果であり、API呼び出しエラーではありません。[エラーハンドリング](/developers/guides/errors)の`processing_error`に関する注意事項を参照してください）。
- `canceled` — 処理開始前にドキュメントがキューから削除されました（例：ドキュメントが`queued`の状態でバッチが削除された場合）。

この5つの値のセットは公開契約であり、システムが内部で使用する状態から意図的に切り離されています。新しい内部中間状態が後で導入されても、ここに6番目の値が追加されることはありません。今日解析するすべてのv1レスポンスは引き続き動作します。

## タイムスタンプチェーン

ドキュメント（`GET /documents/{id}`）とバッチ（`GET /batches/{batch_name}/results`）の両方のレスポンスには、同じ3つのフィールドが含まれています。これにより、「キューに入ったまま停止している」状態と「アクティブに実行中」の状態と「本当に完了した」状態を区別できます。

| フィールド | 設定されるタイミング |
| --- | --- |
| created_at | ドキュメントがアップロードされたとき（バッチの場合は、その中で最も早くアップロードされたとき）。 |
| started_at | ワーカーがドキュメントを取得し、処理を開始したとき。 status がまだ queued の間は null のままです。 |
| completed_at | ドキュメントが succeeded 、 failed 、 canceled のいずれかの終了状態に達したとき。 queued または processing の間は null のままです。バッチレベルでは、バッチ内の すべての ドキュメントがこの値を持つまで null のままです。一部のドキュメントが既に完了していても、処理中のドキュメントが残っているバッチはまだ「完了」していません。 |

## ポーリング vs ウェブフック

バッチの完了を確認する方法は2つあります。

- **ポーリング** — `GET /batches/{batch_name}` を定期的に呼び出し、`all_done` を確認します。シンプルで、サーバー側に特別なインフラは不要ですが、ポーリング間隔が短すぎるとリクエストを無駄に消費し（ステータスエンドポイントの上限は120回/分です。[レート制限](/developers/guides/rate-limits)を参照）、長すぎると完了に気づくまでに遅延が生じます。
- **ウェブフック** — `PUT /batches/{batch_name}/webhook` でコールバックURLを一度登録するだけで、繰り返し問い合わせる代わりに、バッチが完了した瞬間に通知を受け取れます。詳細は[ウェブフック](/developers/guides/webhooks)ガイドをご覧ください。このガイドでは、一度通知を受け取った後にバッチにさらにドキュメントを追加して再処理した場合の動作についても説明しています（簡単に言うと、追加の登録なしで自動的に再通知されます）。

1回だけ処理する小さなバッチであれば、数回のポーリングが最も簡単です。より大量の処理や、リクエストループを待機させたくない場合は、ウェブフックの方が適しています。

---

Source: https://imagetotable.ai/ja/developers/guides/async-model