Dokument einreichen

Ein Dokument wird per POST /v1/scans als multipart/form-data eingereicht. Der Aufruf legt einen Verarbeitungslauf an, plant die Verarbeitung ein und kehrt sofort mit 202 Accepted zurück – er wartet nicht auf das Ergebnis.

Anfrage

Query-Parameter environment (Pflicht): prod oder test.
Formularfelder:
- file – das PDF (nur application/pdf).
- documentType – der Slug des Dokumenttyps.
Header Idempotency-Key (optional, je nach Konfiguration verpflichtend).

curl -X POST "https://api.legentio.com/v1/scans?environment=prod" \
  -H "Authorization: Bearer $SCAN_PORTAL_API_KEY" \
  -H "Idempotency-Key: 2f1c8e9a-…" \
  -F "file=@rechnung.pdf;type=application/pdf" \
  -F "documentType=rechnung"

Antwort

202 Accepted mit einem Location-Header und:

{
  "scanId": "k17c9c8f2a1b3d4e5f6a7b8c9d0e1f2",
  "status": "processing",
  "statusUrl": "https://api.legentio.com/v1/scans/k17c9c8f2a1b3d4e5f6a7b8c9d0e1f2"
}

Merkt euch die scanId. Das Ergebnis holt ihr anschließend über den Feed oder direkt unter statusUrl ab.

Umgebung: prod vs. test

Der environment-Parameter ist verpflichtend und nicht vorbelegt, damit nie unklar ist, wohin ein Dokument ging.

prod – produktiver Lauf; speist den Standard-Feed und die Kennzahlen.
test – wird identisch verarbeitet, bleibt aber aus dem Standard-Feed und den Dashboard-Kennzahlen heraus. Testläufe lest ihr über den Feed-Filter environment=test (oder all) zurück.

Ein fehlender oder unbekannter Wert ist ein 400.

Idempotenz

Über den Header Idempotency-Key sichert ihr Wiederholungen ab (z. B. nach einem Timeout, ohne zu wissen, ob die erste Anfrage ankam):

Gleicher Schlüssel + identische Anfrage → 200 mit dem bestehenden Lauf und seinem aktuellen Status; es wird kein neuer Lauf angelegt. Das ist der Wiederherstellungspfad, wenn ihr die erste Antwort verloren habt.
Gleicher Schlüssel + abweichende Anfrage (andere Datei oder andere Umgebung) → 409.

„Identisch“ heißt: gleicher Dokumenttyp-Slug, gleiche Datei und gleiche Umgebung.

Statuscodes

Status	Bedeutung
`202`	Angenommen, neuer Lauf angelegt.
`200`	Idempotente Wiederholung – bestehender Lauf zurückgegeben.
`400`	Ungültige Anfrage: `environment` fehlt/ungültig, kein `multipart/form-data`, kein PDF, fehlender `documentType`, Datei zu groß oder Pflicht-`Idempotency-Key` fehlt.
`401` / `403`	Authentifizierung fehlgeschlagen – siehe Authentifizierung.
`404`	Der Dokumenttyp wurde nicht gefunden.
`409`	`Idempotency-Key` mit abweichender Anfrage wiederverwendet.
`422`	Für den Dokumenttyp ist in dieser Umgebung noch kein einsatzbereites Schema eingerichtet.
`500`	Interner Serverfehler.