Rechnungen mit n8n an bimetrics übertragen

Das brauchst du

• Selbst gehostetes n8n und eine einzelne PDF, auf die dein n8n-Server zugreifen kann.
• Einen aktiven bezahlten bimetrics-Tarif. API-Nutzung ist in Solo, Team und Scale enthalten. In der kostenlosen Testphase ist die API nicht verfügbar.
• Einen API-Schlüssel für die gewünschte Firma mit Belege hochladen (upload) und Daten lesen (read). Als Inhaber legst du ihn unter Einstellungen → API an.

Die Firma ergibt sich aus dem Schlüssel. Ein eigener bimetrics-Node ist nicht nötig. Der Datei-Eingang dieser Vorlage ist für selbst gehostetes n8n eingerichtet; E-Mail- oder Cloud-Speicher-Eingänge sind separate Erweiterungen.

Den Workflow einrichten

1. Vorlage importieren und Datei angeben

   Importiere die JSON-Datei in n8n. Die Vorlage startet manuell. Öffne den Code-Node Upload konfigurieren und trage im Objekt input bei filePath den absoluten Pfad zur PDF und bei fileName ihren Dateinamen ein.

   Bei Docker muss die Datei im Container erreichbar sein. Der Datei-Node liest nur freigegebene Verzeichnisse; prüfe gegebenenfalls N8N_RESTRICT_FILE_ACCESS_TO. Ein Pfad auf deinem Browsercomputer genügt nicht.

2. Den API-Schlüssel als Credential speichern

   Lege in n8n ein Header Auth-Credential an: Name Authorization, Wert Bearer gefolgt von deinem API-Schlüssel. Wähle es in PDF hochladen und Verarbeitungsstatus lesen aus.

   Speichere den Schlüssel ausschließlich im Credential. So bleibt er außerhalb der exportierten Workflow-Datei.

3. Eine feste Upload-ID vergeben

   Setze sourceDocumentId im Konfigurations-Node auf eine eindeutige ID aus deinem Quellsystem, etwa eingangsrechnung-2026-0042. Die Vorlage übernimmt sie als uploadRequestId. Verwende für jede neue Datei eine neue ID und für jede Wiederholung derselben Übertragung dieselbe ID.

   Die ID darf 1–128 druckbare ASCII-Zeichen ohne Leerzeichen enthalten. Ein bei jedem Versuch neu erzeugter Zeitstempel eignet sich dafür nicht.

4. Eine PDF als Beleg übertragen

   Der Upload-Node ist bereits konfiguriert. Diese Felder verbinden die Datei mit der API:

   Method / URL

   POST https://app.bimetrics.de/api/document/

   Header

   X-Upload-Request-Id mit deiner festen ID

   Body Content Type

   Form-Data

   Parameter Type / Name

   n8n Binary File / receipt[]

   Input Data Field Name

   data

   Genau eine Datei, keine zusätzlichen Formularfelder. Den Content-Type-Header setzt n8n selbst. Starte mit einer dafür vorgesehenen Testdatei: Der Aufruf legt einen Beleg an und stößt dessen Verarbeitung an.

5. Den Status mit der Beleg-ID lesen

   Die Upload-Antwort enthält einen Beleg im Array. Die Vorlage übernimmt dessen id und liest GET /api/document/{id}. Entscheidend ist uploadDocument.ocrStatus.

   Solange die Verarbeitung läuft, fragt die Vorlage höchstens sechsmal mit fünf Sekunden Abstand ab. Danach behältst du die Beleg-ID und kannst später weiter abfragen. Die erfolgreiche Übertragung allein bestätigt noch keine abgeschlossene Verarbeitung.

Was das Ergebnis bedeutet

pending / processing

Die Verarbeitung steht an oder läuft. Die Vorlage fragt mit Abstand erneut ab.

success

Die API meldet die Verarbeitung als abgeschlossen. Öffne den Beleg und prüfe die Angaben.

failed

Die Verarbeitung ist fehlgeschlagen. Öffne den gespeicherten Beleg in bimetrics.

quota_paused

Die Verarbeitung wartet auf freies Kontingent an verarbeiteten Dokumenten. Prüfe dein Kontingent, statt neu hochzuladen.

Im letzten Node steht zusätzlich outcome: processed, processing_failed, quota_paused oder poll_limit_reached. Ein grüner n8n-Lauf kann auch einen korrekt behandelten Fehlerzustand bedeuten. success ist keine Buchungsfreigabe.

Wenn der Ablauf stoppt

400 · BadRequest

Prüfe das Upload-Feld: genau eine Datei als receipt[], keine zusätzlichen Formularfelder.

409 · UploadRequestConflict

Die Upload-ID wurde bereits anders verwendet oder der ursprüngliche Beleg ist nicht mehr verfügbar. Prüfe Datei, Dateiname und Feld. Eine neue ID ist für einen tatsächlich neuen Beleg vorgesehen.

403 · Zugriff fehlt

APIKeyPermissionDenied betrifft die erforderlichen Rechte, APIUnavailable den API-Zugang der Firma. Scheitert erst die Statusabfrage, kann der Beleg bereits gespeichert sein. Prüfe read und verwende die erhaltene Beleg-ID.

Wiederholen, ohne einen zweiten Beleg anzulegen

Nach einem Verbindungsabbruch verwendest du dieselbe Upload-ID, dieselben Dateibytes, denselben Dateinamen und dasselbe Feld. Auch Firma und API-Schlüssel müssen gleich bleiben. Ein anderer Schlüssel eröffnet einen eigenen Bereich für Upload-IDs.

Die Vorlage stoppt bei HTTP-Fehlern. Sie wiederholt Uploads nicht automatisch. Warte bei 429 mindestens die Sekunden aus Retry-After ab; wiederhole vorübergehende Serverfehler nur begrenzt und mit wachsendem Abstand. Liegt bereits eine Beleg-ID vor, frage zuerst deren Status ab.