私はどのように税務申告の準備を自動化したか: Paperless-NGX + n8n + GenAI

まず完全な透明さを宣言しておく：この記事の間、「steuerscan」サービスは請求書の税務上の処理可能性の検証に使用されます。私は「steuerscan」の開発者です。ただし、今回は Paperless-ngx と n8n に焦点を当てます。Docker Compose スタックおよび n8n ワークフローはすべて GitHub でオープンソース化されています。サービスは柔軟に交換可能です。 毎年同じ儀礼：所得証明書が到着し、休暇手当の補填のために税務申告に進む必要があります。申告提出後、そして特に高額な返金が入った後の心地よい感覚を、以前からいくつかのグレーな髪の毛を生じさせる可能性があります。 市場の主要プレイヤーは、税務申告の記入および提出において本当に素晴らしい仕事をしています。しかし私の問題はそれより一歩前にあります：具体的に税務申告で何を記載すればよいのか？「新しいラップトップのための資金を取り戻せますか？」や「塗工事がよく報酬を得た、それを記載できますか？」といった質問は毎年再び私の頭に浮かびます。私が専門的なスキルであり、特にプライベートでプログラミングが好きであり、さらに LLM の時代であるため、これは自動化の最適な機会でした。 プライベートでは、ドキュメント洪水の処理（ドイツの官僚制度改革の進捗はどうなっているのか？）のために Paperless-ngx を使用しています。他の小規模な自動化については、ますます n8n を使用しています。そして誰でも驚くでしょうが、この 2 つを非常に簡単に結合できます。 アイデアは単純です：Paperless にドキュメントをアップロードするたびに、それを 2 つの点で確認したいと考えています。 それは請求書ですか？ そしてはいの場合：それは税務申告のどこかに記載できますか？ 全プロセスは以下のようになります： 新しいドキュメントを Paperless にアップロード Paperless がドキュメントを請求書として分類 それは請求書である場合、Paperless が Webhook を呼び出し、n8n ワークフローを開始 n8n がドキュメントを受け取り、steuerscan API に转发 API が請求書の税務上の処理可能性を返す 請求書が処理可能である場合、Paperless に「税務上の処理可能」というタグが自動的に付与 全スタック（Paperless および n8n、ワークフローを含む）は私の GitHub リポジトリにあります。Docker Compose を使用してローカル環境や VPS でホストできます。手順は以下の通りです： まずリポジトリをクローンし、環境変数を設定します。.env.example テンプレートを使用すると、.env ファイルを生成し、適切に入力できます。その後にスタックを起動します。 git clone https://github.com/creil94/paperless-steuerscan.git cd paperless-steuerscan cp .env.example .env # .env に PAPERLESS_SECRET_KEY を設定（openssl rand -hex 32） docker compose up -d サービスは現在、以下の URL から利用可能です： Paperless: http://localhost:8010/ n8n: http://localhost:5678/ 2. Paperless の設定 Paperless の設定には、以下の手順を実行する必要があります： 以下のコマンドで管理者ユーザーを作成： docker compose exec webserver python manage.py createsuperuser 2. ドキュメントタイプ「請求書」を作成 「設定 → ドキュメントタイプ → 新規」で名前を入力し、アルゴリズムに「Irgendein Wort」を選択し、検索用語（空白で区切る）を「割り当てパターン」フィールドに入力します。私の統合用に、私は次のキーワードを使用しました： rechnung invoice rechnungsnummer rechnungsdatum mwst umsatzsteuer 3. タグ「税務上の処理可能」を作成 「設定 → タグ → 新規」で、任意の名前と任意の颜色を持つ新しいタグを作成します。 重要：作成したタグをクリックすると、上記の弹出ウィンドウに表示される ID が表示されます。これは後に n8n ワークフローに必要です。 4. ワークフローを作成 「ワークフロー → ワークフローを追加」を選択します。「トリガー → トリガertype」で「ドキュメントが追加された」を選択します。下部で、

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 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 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" 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: 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". 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. 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. 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. 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. Zusätzliche Links GitHub Repository mit docker-compose.yml und n8n Workflow Ausführliche Anleitung mit Screenshots steuerscan API