Paperless-ngx mit n8n: Belege automatisch einsortieren und weiterreichen

Paperless-ngx lässt sich mit n8n über zwei Wege verbinden: den Post-Consume-Hook, der nach dem Einlesen eines Dokuments ein Skript startet, und die REST-API, über die n8n Dokumente, Tags und Metadaten abfragen oder neue Belege hochladen kann. Für die Übergabe an die Buchhaltung bedeutet das in der Praxis meist, dass ein Post-Consume-Skript einen n8n-Webhook aufruft und n8n anschließend über die REST-API die vollständigen Dokumentdaten nachlädt, statt alle Informationen bereits im ersten Aufruf mitzuschicken. Ein bekannter Stolperstein dabei ist der Dateiupload von n8n zu Paperless-ngx, der bei falscher Konfiguration mit einem 415-Fehler abbricht. Stand: August 2026.

Wie löst ein Post-Consume-Skript einen n8n-Workflow aus?

Paperless-ngx erlaubt laut eigener Dokumentation, nach Abschluss der Dokumentverarbeitung ein eigenes Skript auszuführen, das per Umgebungsvariablen Zugriff auf Metadaten wie DOCUMENT_ID, DOCUMENT_CORRESPONDENT, DOCUMENT_TAGS und DOCUMENT_ARCHIVE_PATH erhält. Das Skript kann den Verarbeitungsprozess dabei ausdrücklich nicht abbrechen und sollte die Dokumentdateien selbst nicht verändern, da es synchron läuft und die Konsumierung sonst verzögert. In einer Docker-Compose-Installation binden Sie das Skript-Verzeichnis als Volume ein und setzen die Umgebungsvariable PAPERLESS_POST_CONSUME_SCRIPT auf den Pfad im Container. Das einfachste Skript ruft mit den übergebenen Variablen die Produktions-URL eines n8n-Webhook-Nodes per curl auf und übergibt Dokument-ID und Tags als JSON. Details zu den verfügbaren Variablen finden Sie in der Paperless-ngx-Dokumentation zur erweiterten Nutzung.

Wie lädt n8n Belege per REST-API in Paperless-ngx hoch oder wieder aus?

Die REST-API von Paperless-ngx authentifiziert sich über ein Token, das Sie entweder im Profilbereich der Weboberfläche erzeugen oder programmatisch per POST an /api/token/ mit Benutzername und Passwort anfordern; anschließend übergeben Sie es im Header Authorization: Token <token>. Für den Upload eines Dokuments ruft n8n den Endpunkt /api/documents/post_document/ als multipart-formatiertes Formular auf und kann dabei optional Felder wie title, correspondent, document_type, storage_path und mehrfach tags mitschicken, während Paperless-ngx bei erfolgreichem Start sofort die UUID der Konsumierungs-Aufgabe zurückgibt. Zum Auslesen bestehender Belege steht der Endpunkt /api/documents/ mit Such- und Filterparametern wie text= oder query= zur Verfügung. Details zu Authentifizierung und Endpunkten finden Sie in der Paperless-ngx-API-Dokumentation.

Warum bricht der Datei-Upload mit einem 415-Fehler ab?

In einem dokumentierten Fall aus der n8n-Community scheiterte der Upload eines PDFs von Google Drive zu einer lokalen Paperless-ngx-Instanz mit der Meldung „Unsupported media type 'application/pdf' in request", weil der HTTP-Request-Node die Datei nicht im von der API erwarteten multipart/form-data-Format gesendet hatte. Der Nutzer löste das Problem, indem er die Anfrage anhand der offiziellen API-Dokumentation neu konfigurierte, statt die Binärdatei direkt im Rohformat zu übertragen. Prüfen Sie deshalb im HTTP-Request-Node explizit, dass der Body-Typ auf multipart-form-data und nicht auf einen generischen JSON- oder Binär-Body eingestellt ist, bevor Sie das Feld mit der Binärdatei aus einem vorherigen Node verknüpfen. Dieser Fehler taucht in der Praxis vor allem beim ersten Aufbau der Integration auf und ist danach kein wiederkehrendes Problem.

Wie ordnen Sie Tags automatisch zu, und wie geht es dann an die Buchhaltung weiter?

Paperless-ngx vergibt Tags über konfigurierbare Zuordnungsalgorithmen, darunter Any, All, Exact, Regex, Fuzzy und Auto, wobei Auto auf einem an vorhandenen Dokumenten trainierten Modell basiert und ganz ohne manuelle Regeln auskommt. Für die Übergabe an die Buchhaltung liest der n8n-Workflow nach dem Webhook-Trigger die Dokumentdaten inklusive zugewiesener Tags über die REST-API nach und leitet Belege mit einem passenden Tag, etwa „Eingangsrechnung" oder „Reisekosten", per HTTP-Request-Node an ein Buchhaltungssystem oder per E-Mail-Node an die zuständige Person weiter. So entsteht ein durchgehender Prozess vom Scannen oder E-Mail-Import bis zur Ablage im Buchhaltungssystem, ohne dass jemand Belege manuell sortiert. NordFlux baut solche Übergabe-Workflows im Rahmen der n8n-Automatisierung für Kunden individuell auf, meist ergänzt um eine Fehlerbenachrichtigung für nicht zuordenbare Belege.

Häufige Fragen zu n8n mit Paperless-ngx

Brauche ich zwingend den Post-Consume-Hook, oder reicht die REST-API allein?

Die REST-API allein reicht, wenn Sie in n8n regelmäßig nach neuen Dokumenten abfragen wollen, der Post-Consume-Hook ist aber der direktere Weg, weil Paperless-ngx dann selbst aktiv einen Workflow anstößt. In der Praxis liefert die Kombination aus beidem die zuverlässigsten Ergebnisse, weil der Hook den Zeitpunkt liefert und die API die vollständigen Daten.

Warum schlägt der Datei-Upload zu Paperless-ngx in n8n oft fehl?

Der häufigste Grund ist ein falsch konfigurierter Body-Typ im HTTP-Request-Node, der die Datei nicht als multipart/form-data überträgt, wie es der Endpunkt /api/documents/post_document/ erwartet. Ein Blick in die offizielle API-Dokumentation vor dem ersten Testlauf erspart hier die übliche Fehlersuche per 415-Meldung.

Kann ich mit n8n auch bestehende Tags in Paperless-ngx ändern?

Ja, über die REST-API lassen sich Dokumente inklusive ihrer Tag-Zuordnung lesen und mit einem PUT- oder PATCH-Aufruf aktualisieren, sofern der verwendete Token die nötigen Rechte besitzt. Das eignet sich etwa, um Belege nachträglich als „verbucht" zu markieren, sobald die Buchhaltung sie verarbeitet hat.

Läuft die Automatisierung auch, wenn Paperless-ngx und n8n auf unterschiedlichen Servern liegen?

Ja, solange beide Systeme sich gegenseitig über das Netzwerk erreichen und die jeweiligen URLs in Skript und Workflow korrekt hinterlegt sind. Achten Sie in diesem Fall besonders auf HTTPS und eine token-basierte statt einer offenen Authentifizierung, da die Verbindung dann über das öffentliche Netz oder ein VPN läuft.