Wie ich die Vorbereitung für meine Steuererklärung automatisiert habe: Paperless-NGX + n8n + GenAI

Christian Reil — Sat, 14 Mar 2026 12:40:59 +0000

Volle Transparenz vorweg: Während des Artikels wird der Service steuerscan zur Prüfung von Rechnungen auf Absetzbarkeit verwendet. Ich bin der Entwickler von steuerscan. Im Fokus soll hier aber Paperless-ngx und n8n stehen. Der Docker Compose Stack und der n8n Workflow sind vollständig Open Source auf GitHub. Der Service kann flexibel ausgetauscht werden.

Jedes Jahr dasselbe Ritual: Die Lohnsteuerbescheinigung ist da, jetzt geht es an die Steuererklärung zur Aufbesserung der Urlaubskasse. Was nach Abgabe und vor allem nach Eingang einer bestenfalls hohen Rückerstattung ein befriedigendes Gefühl auslöst, kann im Vorfeld schon mal das ein oder andere zusätzliche graue Haar verursachen.

Die etablierten Player am Markt machen einen wirklich wunderbaren Job wenn es um das Ausfüllen und Abgeben der Steuererklärung geht. Mein Problem ist aber einen Schritt davor: Was kann ich eigentlich jetzt genau in der Steuererklärung angeben? Fragen wie "Kann ich Geld für den neuen Laptop wiederbekommen?" oder "Der Maler hat sich das Tapezieren aber gut bezahlen lassen, kann ich das angeben?" stellen sich mir jedes Jahr aufs Neue. Da ich beruflich und vor allem privat gerne programmiere und im Zeitalter von LLMs, war dies die perfekte Gelegenheit für eine Automatisierung.

Privat nutze ich zur Bewältigung der Dokumentenflut (Wie war nochmal der Stand zum Bürokratieabbau in Deutschland?) Paperless-ngx. Für andere kleine Automatisierungen nutze ich vermehrt n8n. Und wer hätte es gedacht, die beiden kann man sehr einfach miteinander verbinden.

Die Idee

Die Idee ist simpel: Ich möchte jedes Mal, wenn ich ein Dokument in Paperless hochlade, dieses auf zwei Dinge überprüfen:

Ist das Dokument eine Rechnung?
Und wenn ja: Kann ich das irgendwo in der Steuererklärung angeben?

Der Plan

Der gesamte Prozess soll wie folgt aussehen:

Ich lade ein neues Dokument in Paperless hoch
Paperless klassifiziert das Dokument als Rechnung
Handelt es sich um eine Rechnung, löst Paperless einen Webhook aus und startet einen n8n Workflow
n8n empfängt das Dokument und leitet es an die steuerscan API weiter
Die API gibt zurück, ob die Rechnung steuerlich absetzbar ist
Ist die Rechnung absetzbar, bekommt das Dokument in Paperless automatisch einen Tag „steuerlich absetzbar"

Die Umsetzung

Der gesamte Stack (Paperless und n8n inkl. dem Workflow) befindet sich in meinem GitHub Repository und kann mittels Docker Compose lokal oder auf einem VPS gehostet werden. Schritt für Schritt sieht das wie folgt aus:

1. Repository klonen und Stack starten

Zunächst wird das Repo geklont und die Environment Variablen gesetzt. Dafür kann die Vorlage .env.example verwendet werden, um die Datei .env anzulegen und entsprechend auszufüllen. Danach startet man den Stack.

git clone https://github.com/creil94/paperless-steuerscan.git
cd paperless-steuerscan
cp .env.example .env
# PAPERLESS_SECRET_KEY in .env setzen (openssl rand -hex 32)
docker compose up -d

Die Services sind nun unter den folgenden URLs verfügbar:

Paperless: http://localhost:8010/
n8n: http://localhost:5678/

2. Paperless konfigurieren

Zur Einrichtung von Paperless müssen folgende Schritte ausgeführt werden:

Admin-User anlegen mit dem folgenden Befehl:

docker compose exec webserver python manage.py createsuperuser

2. Dokumenttyp "Rechnungen" anlegen

Unter "Einstellungen → Dokumenttypen → Neu" den Namen vergeben, den Algorithmus "Irgendein Wort" auswählen und Suchwörter (durch Leerzeichen getrennt) in das Feld "Zuweisungsmuster" eintragen. Für meine Integration habe ich folgende Schlüsselwörter verwendet:

rechnung invoice rechnungsnr rechnungsdatum mwst umsatzsteuer

3. Tag "steuerlich absetzbar" anlegen

Unter "Einstellungen → Tags → Neu" einen neuen Tag mit beliebigem Namen und beliebiger Farbe anlegen.

Wichtig: Wenn man auf den angelegten Tag klickt, sieht man oben im sich öffnenden Fenster eine Id. Diese braucht man später im n8n Workflow.

4. Arbeitsablauf anlegen

Unter "Arbeitsabläufe → Arbeitsablauf hinzufügen". Unter "Auslöser → Auslösertyp" → "Dokument hinzugefügt" auswählen. Unten bei "Erweiterte Filter" → "Hat Dokumententyp" und "Rechnungen" auswählen.

Bei "Aktionen → Aktion hinzufügen" den Typen "Webhook" auswählen und folgende Werte eintragen:

Feld	Wert
Webhook-URL	`http://n8n:5678/webhook/paperless-invoice`
Webhook-Parameter (Key)	`doc_url`
Webhook-Parameter (Value)	`{{ doc_url }}`

Anschließend auf "Speichern" klicken.

5. API Token kopieren

Gehe auf dein Profilbild oben rechts → "Mein Profil" und kopiere den Token unter "API-Authentifizierungstoken".

3. n8n Workflow einrichten

n8n unter http://localhost:5678 öffnen und einen Account anlegen. Den Workflow aus dem Repo unter n8n-workflows/paperless-rechnungen.json über "Workflows → Import from File" importieren.

Anschließend müssen noch zwei Nodes angepasst werden:

Node "Steuerscan analysieren": Den Wert für X-API-Key durch den steuerscan API-Token ersetzen.

Node "Tag in Paperless setzen": Unter "Authorization" den Paperless-Token eintragen und im "JSON Body" die Tag-ID einsetzen.

➡️ Workflow aktivieren — fertig.

Der Workflow in Aktion

Sobald in Paperless-ngx ein neues Dokument hochgeladen wurde, wird der n8n Workflow getriggert. Nach einigen Sekunden sollte dieser erfolgreich durchgelaufen sein.

In Paperless findet man unter dem Menüpunkt "Dokumente" das hochgeladene Dokument. Das Dokument erhält automatisch den Tag "steuerlich absetzbar", sofern die Rechnung absetzbar ist.

Fazit

Auf den ersten Blick mag das Setup des Workflows etwas überfordernd wirken (vor allem in Paperless). Einmal eingerichtet läuft der Prozess aber geräuschlos im Hintergrund und ich kann bei der Anfertigung der Steuererklärung sehr schnell die Rechnungen finden, die ich bei der Steuererklärung angeben kann.

Ausblick — Was kann man noch verbessern?

Bevor es zum Ende des Artikels geht, die Frage "Was kann man noch verbessern?":

Paperless-ngx Rechnungsklassifizierung: Derzeit werden hochgeladene Dokumente über Keyword-Matching klassifiziert. Paperless bietet die Möglichkeit mithilfe von beispielhaften Dokumenten und KI zu lernen, wie eine Rechnung aussieht. Damit lässt sich mit Sicherheit die False-Positive-Quote reduzieren.
Braucht man n8n? Da man aus Paperless n8n über einen Webhook aufruft, kann man sich berechtigterweise die Frage stellen, ob man nicht direkt aus Paperless die API aufrufen kann. Ich persönlich finde es aber einfacher und nachvollziehbarer mit n8n als Workflow.
Metainformationen erweitern: Derzeit bekommt das Dokument in Paperless nur den Tag „steuerlich absetzbar". Die API gibt aber bspw. noch zurück, ob es sich hierbei um Werbungskosten etc. handelt und eine ausführliche Begründung. Diese könnte man in Paperless in den Metadaten abspeichern.

DEV Community: Christian Reil