Async-Task-Modell

Das Hochladen eines Dokuments verarbeitet es nicht, und das Starten der Verarbeitung schließt sie nicht in derselben Anfrage ab. Jedes Dokument und jeder Batch durchläuft eine feste, geschlossene Menge von Status – diese Seite beschreibt den gesamten Lebenszyklus.

Status-Lebenszyklus

Jedes Dokument (und aggregiert jeder Batch) befindet sich stets in genau einem von fünf Zuständen:

queued → processing → succeeded | failed | canceled

queued – hochgeladen und/oder wartend auf einen Worker.
processing – ein Worker hat das Dokument übernommen und extrahiert aktiv Daten daraus.
succeeded – Extraktion abgeschlossen; line_items in der Ergebnisantwort ist befüllt.
failed – Extraktion konnte für dieses Dokument nicht abgeschlossen werden (dies ist ein Dokument-Level-Ergebnis, kein API-Aufruffehler – siehe Hinweis zu processing_error in Fehlerbehandlung).
canceled – das Dokument wurde vor Verarbeitungsbeginn aus der Warteschlange entfernt (z. B. weil sein Batch gelöscht wurde, während es noch queued war).

Diese Fünf-Werte-Menge ist ein öffentlicher Vertrag, bewusst entkoppelt von den internen Zuständen des Systems. Neue interne Zwischenzustände können später hinzugefügt werden, ohne jemals einen sechsten Wert hier einzuführen – jede heute geparste v1-Antwort funktioniert weiterhin.

Die Zeitstempelkette

Sowohl Dokument- (GET /documents/{id}) als auch Batch-Antworten (GET /batches/{batch_name}/results) enthalten dieselben drei Felder, sodass Sie „in der Warteschlange feststeckend“ von „aktiv in Bearbeitung“ und „tatsächlich abgeschlossen“ unterscheiden können:

Feld	Gesetzt wenn
`created_at`	Das Dokument hochgeladen wurde (bzw. beim Batch der früheste Upload darin).
`started_at`	Ein Worker das Dokument übernommen und mit der Verarbeitung begonnen hat. Bleibt `null`, solange `status` noch `queued` ist.
`completed_at`	Das Dokument einen Endzustand erreicht hat – `succeeded`, `failed` oder `canceled`. Bleibt `null`, solange es noch `queued` oder `processing` ist. Auf Batch-Ebene bleibt es `null`, bis jedes Dokument im Batch einen solchen Status hat – ein Batch mit noch laufenden Dokumenten ist noch nicht „abgeschlossen“, selbst wenn einige Dokumente bereits fertig sind.

Polling vs. Webhooks

Sie haben zwei Möglichkeiten, um zu erfahren, wann ein Batch fertig ist:

Polling – Rufen Sie regelmäßig GET /batches/{batch_name} auf und prüfen Sie all_done. Einfach, keine Infrastruktur auf Ihrer Seite erforderlich, aber verschwendet Anfragen, wenn Sie zu aggressiv pollt (siehe Ratenlimits für das 120/Minute-Limit bei Statusendpunkten) oder zu langsam (zusätzliche Latenz, bevor Sie den Abschluss bemerken).
Webhooks – Registrieren Sie einmalig eine Callback-URL mit PUT /batches/{batch_name}/webhook und werden Sie benachrichtigt, sobald der Batch fertig ist, anstatt wiederholt nachzufragen. Siehe die Webhooks-Anleitung – sie behandelt auch, was passiert, wenn Sie einem Batch weitere Dokumente hinzufügen und ihn erneut verarbeiten, nachdem er Sie bereits einmal benachrichtigt hat (kurz: Sie werden automatisch erneut benachrichtigt, keine zusätzliche Registrierung erforderlich).

Für einen einzelnen kleinen Batch, der einmal verarbeitet wird, ist mehrmaliges Polling am einfachsten. Bei größeren Volumina oder wenn Sie keine Anfrageschleife laufen lassen möchten, sind Webhooks die bessere Wahl.