Job-Status

Basis-URL https://api.accessful.de/api/v1/upload-service. Jede Anfrage benötigt den X-API-Key-Header — siehe Authentifizierung.

GET /job-status/{caseId}

200 OK — ein fertiger Case:

{ "jobStatus": "completed", "stage": "finished", "score": 87 }

score ist die Barrierefreiheits-Qualität des Ergebnisses, 0–100 (aussagekräftig, sobald completed). 404 wird bei unbekannter caseId zurückgegeben.

jobStatus	Bedeutung
queued	Wartet in der Warteschlange.
running	Wird gerade verarbeitet.
completed	Fertig — Ergebnis zum Download bereit.	Endzustand
failed	Verarbeitung fehlgeschlagen.	Endzustand
analyzer_failed	Der Analyse-Schritt ist fehlgeschlagen.	Endzustand
canceled	Der Job wurde abgebrochen.	Endzustand
quota_pending	Wartet auf eine asynchrone Kontingentprüfung.
quota_exceeded	Abgelehnt — Vertragskontingent erschöpft.	Endzustand

Beim Pollen: stoppe, sobald du einen Endzustand siehst.

Verarbeitungsphase

Neben jobStatus enthält jede Antwort ein stage-Feld — die feingranulare Pipeline-Phase, orthogonal zum groben Status. Damit zeigst du Fortschritt jenseits eines bloßen „läuft“: die lange KI-Remediation lässt sich von der Analyse unterscheiden.

stage	Bedeutung
queued	Angenommen, wartet auf den Start der ersten Analyse.
analyzing	Die Erstanalyse der hochgeladenen Datei läuft.
resolving	Die KI-Remediation der Datei läuft.
revalidating	Die Re-Analyse der remediierten Datei läuft.
finished	Verarbeitung fertig; score spiegelt die finale Datei.
failed	Verarbeitung wegen eines nicht behebbaren Fehlers gestoppt.

Warteposition

Solange ein Case queued ist, sagt die Antwort dir außerdem, an welcher Stelle der Analyse-Warteschlange er steht — dieselbe Live-„Warteposition“, die das Web-UI zeigt — sodass du statt eines statischen „queued“ ein sinnvolles „7 von 23, ~5 Min“ anzeigen kannst.

200 OK — ein Case, der noch wartet:

{
  "jobStatus": "queued",
  "stage": "queued",
  "score": 0,
  "queuePosition": 7,
  "queueTotal": 23,
  "estimatedWaitSeconds": 300
}

Feld	Typ	Hinweise
queuePosition	integer	1-basierter Rang in der Warteschlange (1 = als Nächstes dran).
queueTotal	integer	Gesamtzahl der aktuell wartenden Cases (Länge der Warteschlange).
estimatedWaitSeconds	integer	Grobe Wartezeit-Schätzung in Sekunden, abgeleitet aus Warteschlangentiefe und Analyzer-Durchsatz. Kann fehlen, wenn keine Schätzung verfügbar ist.

Hinweis

Die drei queue*-Felder sind nur vorhanden, solange der Case queued ist. Sobald der Analyzer ihn aufnimmt (oder der Case einen anderen Zustand erreicht), werden sie aus dem JSON weggelassen — sie erscheinen nie als null. Behandle ihr Fehlen als „wartet nicht“. Das ist additiv: ein Client, der nur jobStatus/score liest, ist nicht betroffen.

Die Position ist ein Best-Effort-Live-Snapshot, der bei jeder Anfrage neu berechnet wird: sie sinkt nur, während vorausliegende Cases verarbeitet werden, und ein einziges Abarbeiten verschiebt alle dahinter. Als Push-Alternative registriere den case.queued-Webhook, um die Startposition im Moment der Annahme zu erhalten.