API und Webhooks
Das Hochladen und Auslesen von Belegen ist über die REST API verfügbar. Die Verwaltung des Kontos, der Ordner, Labels und Verbindungen bleibt in der Anwendung.
Schlüssel
Er wird in den Einstellungen → Für Entwickler angelegt. Der Schlüssel wird einmalig bei der Erstellung angezeigt — danach nie wieder, 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 fünf Schlüssel vorhanden sein, jeder mit einer optionalen Gültigkeitsdauer von bis zu zwei Jahren.
Der Eigentümer des Kontos erhält eine E-Mail über jeden neuen Schlüssel, ebenso wie zwei Wochen bevor der Schlüssel abläuft. Siehe E-Mail-Benachrichtigung.
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, Typ, Währung, Schema, Ordner, 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 Paging |
GET /api/jobs/{id} | Status, ausgelesene Daten, Funde und Ergebnis im Ziel-Format |
GET /api/jobs/{id}/original | Hochgeladene Datei |
DELETE /api/jobs/{id} | In den Papierkorb verschieben |
Excel und PDF kommen im Ergebnis als Base64. Wer das Ergebnis nicht benötigt, sendet includeResult=false, um die Umwandlung auf dem Server zu sparen.
Die Schnittstellenbeschreibung 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 tut.
Kontrolle bei Belegen aus der API
Die Kontrolle vor dem Versand gilt standardmäßig auch für Belege, die mit dem Schlüssel hochgeladen wurden: Der Beleg wartet auf Bestätigung in der Anwendung und der Webhook wird erst danach gesendet. Wer eine Integration aufbaut, bei der niemand vor dem Bildschirm sitzt, kann in den Einstellungen → Kontrolle vor dem Versand den API-Kanal entfernen oder die Kontrolle deaktivieren.
MCP
Für AI-Agenten gibt es unter /api/mcp einen MCP-Server mit demselben Schlüssel. Er kann Belege lesen und durchsuchen, nicht hochladen; das Hochladen wird als fertiger Befehl zurückgegeben, den der Agent selbst ausführt.
Webhooks
Anstelle von Abfragen zum Status lassen Sie sich das Ergebnis zusenden, sobald es fertig ist. Die Adresse wird für das gesamte Konto in den Einstellungen → Für Entwickler festgelegt, oder bei einem einzelnen Upload über den Parameter targetWebhookUrl. Der Button in den Einstellungen sendet eine Testnachricht.
Es wird ein POST mit JSON gesendet: Beleg-ID, Dateiname, Format und Ergebnis im Ziel-Format. Wenn der Beleg die Kontrolle besteht oder erneut verarbeitet wird, kommt der Webhook ein zweites Mal mit dem Flag für Korrektur (IsCorrection).
Die Nachricht wird nicht signiert. Überprüfen Sie den Absender, indem Sie Ihren geheimen Token in die Adresse einfügen. Adressen zu privaten Netzwerken werden abgelehnt.
Wenn der Webhook auch nach allen Versuchen nicht ankommt, etwa nach viereinhalb Stunden, kommt eine E-Mail. Während eines Ausfalls nur einmal, weitere Fehlversuche werden im Aktivitätsprotokoll festgehalten. Eine E-Mail wird auch bei jeder Änderung der Webhook-Adresse gesendet, falls diese von jemand anderem als Ihnen geändert wurde.
Fehlgeschlagenes Zustellen wird mit steigender Verzögerung wiederholt, elf Versuche innerhalb von etwa viereinhalb Stunden. Jeder Versuch ist in der Aktivität aufgeführt, einschließlich der Antwort von Ihrer Seite; bei einem Beleg in der Auflistung gibt es ein Symbol mit dem Zustellresultat.
Limits
Die API hat keine eigene Obergrenze für die Anzahl der Aufrufe pro Minute; das Hochladen wird durch Credits, die Dateigröße gemäß Tarif und zwanzig Seiten pro Beleg eingeschränkt. Eine Ablehnung kommt als Fehler 400 mit einem Code, der erklärt, warum. Der MCP-Server ist auf zehn Anfragen pro Sekunde begrenzt.