API und Webhooks
Das Hochladen und Lesen von Belegen ist über die REST API verfügbar. Die Verwaltung des Kontos, der Ablagen, Tags und Verbindungen bleibt in der Anwendung.
Schlüssel
Der Schlüssel wird unter Einstellungen → Für Entwickler erstellt. Der Schlüssel wird einmalig bei der Erstellung angezeigt — danach nicht mehr, da nur sein Hash gespeichert wird. Ein verlorener Schlüssel kann nicht wiederhergestellt werden, es wird ein neuer erstellt und der alte gelöscht. Es können bis zu fünf Schlüssel vorhanden sein, jeder mit einer optionalen Gültigkeit von bis zu zwei Jahren.
Der Schlüssel wird im Header X-API-Key gesendet.
Was die API kann
| Operation | Beschreibung |
|---|---|
POST /api/upload | Hochladen einer Datei mit Optionen: Format, Richtung, Art, Währung, Schema, Ablage, Webhook |
POST /api/upload/url | Dasselbe von einer öffentlichen Adresse; wir laden die Datei selbst herunter |
GET /api/jobs | Auflistung von Belegen mit Filtern und Pagination |
GET /api/jobs/{id} | Status, gelesenes Datum, Funde und Ergebnis im Zielformat |
GET /api/jobs/{id}/original | Hochgeladene Datei |
DELETE /api/jobs/{id} | In den Papierkorb verschieben |
Excel- und PDF-Dateien werden im Ergebnis als Base64 geliefert. Wer das Ergebnis nicht benötigt, kann includeResult=false senden, um die Umwandlung auf dem Server zu sparen.
Die Schnittstellendokumentation im OpenAPI-Format befindet sich unter /api/docs; der Link ist in den Einstellungen bei den Schlüsseln. Die Beschreibung wird aus dem laufenden Code generiert, sodass sie dem entspricht, was die API tatsächlich tut.
Prüfung bei Belegen aus der API
Die Prüfung vor dem Versand gilt standardmäßig auch für Belege, die mit einem Schlüssel hochgeladen wurden: Der Beleg wartet im Anwendungsbereich auf Bestätigung und der Webhook wird erst danach gesendet. Wer eine Integration aufbaut, bei der niemand am Bildschirm sitzt, kann im Einstellungen → Prüfung vor dem Versand den API-Kanal entfernen oder die Prüfung deaktivieren.
MCP
Für KI-Agenten gibt es unter /api/mcp einen MCP-Server mit dem gleichen Schlüssel. Er kann Belege lesen und suchen, aber nicht hochladen; das Hochladen wird als ausführlicher Befehl zurückgegeben, den der Agent selbst ausführen kann.
Webhooks
Anstelle von Statusabfragen lassen Sie sich das Ergebnis zusenden, sobald es fertig ist. Die Adresse wird für das gesamte Konto unter Einstellungen → Für Entwickler festgelegt oder bei jedem einzelnen Upload mit dem Parameter targetWebhookUrl. Der Button in den Einstellungen sendet eine Testnachricht.
Es wird ein POST mit JSON gesendet: Belegidentifikator, Dateiname, Format und Ergebnis im Zielformat. Wenn der Beleg die Prüfung besteht oder erneut verarbeitet wird, kommt der Webhook ein zweites Mal mit dem Korrektursignal (IsCorrection).
Die Nachricht wird nicht signiert. Überprüfen Sie den Absender, indem Sie Ihren eigenen geheimen Token in die Adresse einfügen. Adressen zu privaten Netzwerken werden abgelehnt.
Fehlerhafte Zustellungen werden mit zunehmender Verzögerung wiederholt, insgesamt elf Versuche über einen Zeitraum von etwa viereinhalb Stunden. Jeder Versuch ist in der Aktivität mit der Antwort Ihrer Seite enthalten; bei einem Beleg in der Auflistung gibt es ein Symbol mit dem Zustellstatus.
Limits
Die API hat kein eigenes Limit für die Anzahl der Aufrufe pro Minute; das Hochladen wird durch Credits, die Dateigröße je nach Tarif und zwanzig Seiten pro Beleg begrenzt. Eine Ablehnung erfolgt mit einem Fehler 400 und einem Code, der erklärt, warum. Der MCP-Server ist auf zehn Anfragen pro Sekunde beschränkt.