Zum Inhalt springen
LegentioLegentio – Dokumentation

API-Einführung

Die Legentio-API ist vollständig asynchron und pull-basiert. Ein Upload verarbeitet das Dokument nicht sofort, sondern legt einen Verarbeitungslauf an und kehrt umgehend zurück. Die Ergebnisse holt ihr anschließend selbst ab, indem ihr einen Auslieferungs-Feed pollt. Es gibt bewusst keine Webhooks – die Client-Anwendung besitzt die Polling-Schleife.

Basis-URL

Abschnitt betitelt „Basis-URL“

Alle Endpunkte liegen unter /v1 auf folgender Basis-URL:

https://api.legentio.com/v1

Die Authentifizierung erfolgt per Bearer-Token – siehe Authentifizierung.

Die drei Endpunkte

Abschnitt betitelt „Die drei Endpunkte“
Methode & Pfad Zweck
POST /v1/scans Ein Dokument einreichen. Kehrt sofort mit 202 zurück.
GET /v1/scans Auslieferungs-Feed: abgeschlossene Läufe pollen.
GET /v1/scans/{scanId} Einen einzelnen Lauf samt vollständigem Ergebnis abfragen.

Die vollständige Referenz mit allen Feldern und Statuscodes findet ihr unter API-Referenz.

Typischer Ablauf

Abschnitt betitelt „Typischer Ablauf“
  1. Einreichen – PDF per POST /v1/scans hochladen (Umgebung prod oder test angeben). Ihr erhaltet sofort eine scanId.
  2. Pollen – in Intervallen GET /v1/scans mit dem zuletzt gespeicherten cursor abrufen. Neue abgeschlossene Läufe erscheinen im Feed.
  3. Verarbeiten & Cursor speichern – die gelieferten Einträge verarbeiten und den nextCursor persistieren, bevor der nächste Poll läuft.
  4. Bei Bedarf nachladen – war ein Ergebnis zu groß für den Feed (resultTruncated: true), das vollständige Ergebnis über GET /v1/scans/{scanId} holen.

Wichtige Garantien

Abschnitt betitelt „Wichtige Garantien“
  • At-least-once: Nach einem Absturz zwischen „Eintrag verarbeitet“ und „Cursor gespeichert“ seht ihr denselben Lauf erneut. Eure Verarbeitung muss deshalb idempotent sein – nach scanId upserten und die höchste revision behalten.
  • Erneute Auslieferung bei Korrekturen: Ein Retry oder eine Korrektur erhöht die revision und lässt den Lauf erneut im Feed auftauchen – vor jedem gespeicherten Cursor.
  • Test und Produktion getrennt: Beim Einreichen ist die Umgebung (prod/test) verpflichtend. Testläufe werden identisch verarbeitet, erscheinen im Feed aber nur mit environment=test (oder all).

Nächste Schritte

Abschnitt betitelt „Nächste Schritte“