API für Finanzdokumente

Laden Sie Kontoauszüge, Rechnungen und Belege aus Ihrer Software hoch. Rufen Sie ausgelesene Daten ab, prüfen Sie unklare Felder und exportieren Sie CSV, Excel oder JSON.

OpenAPI-Schema Upload-Beispiel herunterladen

Das OpenAPI-Schema enthält Anfragefelder, Antworten und Berechtigungen. Das Beispiel liest den Schlüssel aus einer Umgebungsvariable und lädt nur die von Ihnen gewählte Datei hoch.

Arbeitsbereich verbinden

Öffnen Sie im Arbeitsbereich Einstellungen → API-Schlüssel. Erstellen Sie einen Schlüssel mit den benötigten Berechtigungen. Die Arbeitsbereich-ID steht nach /app/ in seiner URL. Senden Sie den Schlüssel im Header Authorization: Bearer an https://rahunko.com/api/v1/workspaces/{workspaceId}.

Rahunko öffnen

Schlüssel auf dem Server speichern

Der vollständige Schlüssel wird nur beim Erstellen angezeigt. Speichern Sie ihn in einem Secret-Manager, niemals im Browsercode, in URLs, Screenshots oder Protokollen. Jeder Schlüssel gehört zu einem Arbeitsbereich. Erstellen Sie einen neuen Schlüssel, bevor Sie den alten in den Einstellungen widerrufen.

Upload-Beispiel herunterladen

Starten Sie das heruntergeladene Beispiel mit Bun. Setzen Sie RAHUNKO_API_KEY und RAHUNKO_WORKSPACE_ID als Umgebungsvariablen. Der Schlüssel benötigt documents:write und jobs:read. Für Exporte ist zusätzlich exports:read erforderlich. Das Beispiel bestätigt keine Prüfung für Sie.

bun upload-document.ts ./statement.pdf

Datei hochladen

Erstellen Sie einen Upload mit Dateigröße, SHA-256-Hash und batchId. Teilen Sie die Datei nach dem zurückgegebenen partSize auf und senden Sie jeden Teil an partsUrl/{partNumber}. Jeder Teil benötigt seinen Hash und einen Idempotency-Key. Rufen Sie nach dem letzten Teil completeUrl auf.

Verarbeitung starten

Rufen Sie nach dem Upload uploadUrl/finalize auf. Fragen Sie den Status mit der zurückgegebenen Auftrags-ID ab. Verarbeitung und Prüfung haben getrennte Statuswerte. Auch nach erfolgreicher Verarbeitung können Felder eine Prüfung erfordern.

Prüfen und exportieren

Rufen Sie das Auftragsergebnis oder Dokument ab. Prüfen oder korrigieren Sie Werte über die review-Endpunkte und exportieren Sie die aktuelle revision. Bei einer geänderten Version laden Sie zuerst die aktuellen Daten. Bestätigen Sie eine Prüfung nicht automatisch, nur um einen Export freizugeben.

Limits und Wiederholungen

Eine Datei darf bis zu 50 MiB groß sein. Ein Upload läuft nach einer Stunde ab. Verwenden Sie die zurückgegebenen Teilgrößen und URLs. Zusätzlich gelten die Verarbeitungskontingente des Arbeitsbereichs. Verwenden Sie denselben Idempotency-Key nur für dieselbe Anfrage oder denselben Teil. Beachten Sie bei 429 den Header Retry-After, falls vorhanden, und verlängern Sie die Wartezeit zwischen Versuchen.

Bis zu 300 Anfragen pro Schlüssel und 600 pro IP-Adresse innerhalb von 60 Sekunden. Beide Limits gelten. Bei Überschreitung erhalten Sie 429 mit Retry-After.

Fehler gezielt behandeln

400 oder 422 erfordert korrigierte Eingaben. 401 oder 403 bedeutet, dass der Zugriff verweigert wurde. Bei 404 ist die Ressource in diesem Arbeitsbereich nicht verfügbar. 409 weist auf einen Konflikt bei Status, Version oder Idempotency-Key hin. Wiederholen Sie diese Anfragen nicht unverändert. Ein 5xx-Fehler kann vorübergehend sein. Wiederholen Sie nur dafür geeignete Vorgänge.

Ausnahme: Ein Auftragsergebnis mit HTTP 409 und status=waiting wird noch verarbeitet. Fragen Sie den Auftragsstatus mit einer Pause erneut ab.

Webhooks

Callback-Adressen müssen derzeit vom Rahunko-Betreiber eingerichtet werden. Die API registriert deren endpointId, keine beliebige URL. Prüfen Sie die Signatur der unveränderten Body-Bytes mit dem Zeitstempel. Verwerfen Sie veraltete Zustellungen und verarbeiten Sie jede Ereignis-ID nur einmal. Bis zur Einrichtung können Sie den Auftragsstatus abfragen.

Der Header x-rahunko-signature enthält sha256= und den Base64-kodierten HMAC-SHA256 von timestamp.eventId.rawBody mit dem eingerichteten Geheimnis. Lesen Sie die Ereignis-ID aus x-rahunko-event-id und den Unix-Zeitstempel in Sekunden aus x-rahunko-timestamp. Vergleichen Sie Signaturen in konstanter Zeit, bevor Sie den Body verarbeiten.

Endpunkte

Aus dem versionierten API-Vertrag generiert. Alle Endpunkte erfordern einen API-Schlüssel des Arbeitsbereichs. Pfade, Felder und Berechtigungsnamen sind in allen Sprachen gleich.

Dokumente auflistenGET /api/v1/workspaces/{workspaceId}/documents: Erforderliche Berechtigung: documents:read
Dokument abrufenGET /api/v1/workspaces/{workspaceId}/documents/{documentId}: Erforderliche Berechtigung: documents:read
Dokument löschenDELETE /api/v1/workspaces/{workspaceId}/documents/{documentId}: Erforderliche Berechtigung: documents:write
Verarbeitung abbrechenPOST /api/v1/workspaces/{workspaceId}/documents/{documentId}/cancel: Erforderliche Berechtigung: documents:write
Quelldaten abrufenGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/evidence: Erforderliche Berechtigung: documents:read
Originalseite abrufenGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/evidence/pages/{pageNumber}: Erforderliche Berechtigung: documents:read
Version exportierenGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/export: Erforderliche Berechtigung: exports:read
Prüffelder abrufenGET /api/v1/workspaces/{workspaceId}/documents/{documentId}/review: Erforderliche Berechtigung: documents:read
Felder korrigierenPATCH /api/v1/workspaces/{workspaceId}/documents/{documentId}/review: Erforderliche Berechtigung: documents:write
Durchgeführte Prüfung bestätigenPOST /api/v1/workspaces/{workspaceId}/documents/{documentId}/review/complete: Erforderliche Berechtigung: documents:write
Verarbeitungsstatus abrufenGET /api/v1/workspaces/{workspaceId}/jobs/{jobId}: Erforderliche Berechtigung: jobs:read
Ergebnis und Export-Links abrufenGET /api/v1/workspaces/{workspaceId}/jobs/{jobId}/result: Erforderliche Berechtigung: jobs:read
Verarbeitungskontingent abrufenGET /api/v1/workspaces/{workspaceId}/quota: Erforderliche Berechtigung: documents:read
Upload anlegenPOST /api/v1/workspaces/{workspaceId}/uploads: Erforderliche Berechtigung: documents:write
Upload-Fortschritt abrufenGET /api/v1/workspaces/{workspaceId}/uploads/{uploadId}: Erforderliche Berechtigung: documents:write
Upload abbrechenPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/abort: Erforderliche Berechtigung: documents:write
Hochgeladene Teile abschließenPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/complete: Erforderliche Berechtigung: documents:write
Datei zur Verarbeitung übergebenPOST /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/finalize: Erforderliche Berechtigung: documents:write
Einen Teil hochladenPUT /api/v1/workspaces/{workspaceId}/uploads/{uploadId}/parts/{partNumber}: Erforderliche Berechtigung: documents:write
Registrierte Webhooks auflistenGET /api/v1/workspaces/{workspaceId}/webhooks: Erforderliche Berechtigung: webhooks:read
Eingerichteten Webhook registrierenPOST /api/v1/workspaces/{workspaceId}/webhooks: Erforderliche Berechtigung: webhooks:write
Webhook deaktivierenDELETE /api/v1/workspaces/{workspaceId}/webhooks/{endpointId}: Erforderliche Berechtigung: webhooks:write