GoBD konforme Belegarchivierung

Ganz einfach mit Paperless-ngz 

Heute schauen wir uns mal das Open-Source Dokumenten-Management-System (DMS) Paperless-ngz an. Genau genommen wollen wir es dazu verwenden, um unsere geschäftlichen Belege damit GoBD konform zu archivieren. Wir nutzen hierzu wieder mal Docker. Alle Dateien die Sie dazu benötigen stelle ich Ihnen im Artikel bereit, damit ist das ruck zuck aufgesetzt. Aufwand fürs erste Einrichten: ein Vormittag.  Dieser Guide richtet sich an Admins von kleinen Firmen/Handwerkern/Freelancer/Soloselbstständige oder Kleingewerbetreibende.


Die wenigsten kleinen Unternehmen wissen überhaupt, daß die GoBD existert, geschweige denn, was sie konkret bdeutet. Ich will das jetzt auch nicht groß erklären. Dafür gibt es Wikipedia. Im Wesentlichen geht es aber darum, daß alle Ein- und Ausgangsbelege des Unternehmens so archiviert werden müssen, dass sie vollständig, unveränderbar und jederzeit für das Finanzamt nachvollziehbar sind. Und das leider nicht mehr in Papierform, sondern digital.

Wer Belege nicht GoBD-konform archiviert, riskiert bei einer Betriebsprüfung Steuerschätzungen, Nachzahlungen und den Verlust des Vorsteuerabzugs.
Fehlende oder veränderbare Belege können zu Bußgeldern und höherem Aufwand beim Steuerberater führen. Zwar sind Prüfer bei kleinen Unternehmen nicht so streng, aber wir wollen uns ja nicht auf die Kulanz eines Beamten verlassen, der ausgerechnet heute mit dem falschen Fuß aufgestanden ist und jetzt Ihr Unternehmen prüfen muss.
 

OK, fangen wir an

Sie benötigen Docker. Bei uns läuft das in einer VM unter Ubuntu, also Linux. Ich setze voraus, daß Sie sich schon etwas mit docker auskennen und es schon lauffähig in Ihrem Intranet verfügbar ist. Zugriff von aussen wird es keinen geben, entsprechend richte ich jetzt auch kein SSL und so ein - also wirklich nur die Basics, damit paperless läuft.

Entpacken Sie fogendes Archiv in Ihr Docker-Verzeichnis
paperless.zip [4,47 KB]

Darin unter anderem enthalten die docker-compose.yml und ein Dockerfile für Mustang

Damit Sie verstehen, was später passieren wird, hier mal der Ablauf für den Import eines Beleges:
Beleg in den consume-Ordner legen. paperless schnappt sich sofort nach dem Kopieren die Datei, analysiert sie, läßt Texterkennung drüber laufen, entscheidet dann, ob es eine Eingangs- oder Ausgangsrechnung ist und vermerkt das entsprechend. Dabei ist es egal was Sie in den consume-Ordner legen. Sie können:
  • eine PDF, die per Mail kam händisch rein legen
  • einen Papierbeleg einscannen und das JPG manuell oder automatisiert übers Netzwerk in den Ordner schieben
  • auch e-Rechungen im ZugFerd-Format sind kein Problem
Problematisch wird es erst bei X-Rechnungen. Die bestehen nämlich nur aus einem XML. Das möchte paperless aber von Haus aus nicht importieren. Abgesehen davon, könnten Sie es dann später in paperless auch nicht einfach so anschauen - xml Daten sind zwar sauber strukturiert, aber für Menschen schwer lesbar. Hier kommt Mustang ins Spiel. Das steht mit in der docker-compose.yml
 
mustang:
  build: ./mustang
  container_name: mustang
  restart: unless-stopped
  volumes:
    - ./consume:/usr/src/paperless/consume

Wie Sie gleich sehen, wird der Container über ein Dockerfile erstellt:
 
FROM eclipse-temurin:17-jre
WORKDIR /app
RUN apt-get update \
 && apt-get install -y wget inotify-tools \
 && rm -rf /var/lib/apt/lists/*
# Mustang CLI herunterladen
RUN wget -O Mustang-CLI.jar \
  https://github.com/ZUGFeRD/mustangproject/releases/download/core-2.21.0/Mustang-CLI-2.21.0.jar
# Watch-Script
COPY consume_watch.sh /app/consume_watch.sh
RUN chmod +x /app/consume_watch.sh
CMD ["/app/consume_watch.sh"]

Was macht Mustang? Nun, es startet ein kleines Script: consume_watch.sh und läßt dieses in Endlosschleife laufen. Das Script überwacht den consume-Ordner. Wird eine XML da rein kopiert, nimmt sich das Script die Datei und wandelt den Inhalt der XML (klappt nur bei X-Rechnungen) in ein gut lesbares PDF um. An dieses PDF wird dann noch die XML angehängt und das Ganze wird wieder in den consume-Ordner gelegt (hinterher wird noch aufgeräumt).
Hier findet papperless dann einen ganz normale PDF (quasi eine ZugFerd) und importiert dieses sauber. Da wir das original XML an der PDF hängen haben, erfüllen wir alle Anforderungen der GoBD - Problem gelöst.

OK, jetzt noch schnell den Container bauen, dann sind wir technisch auch schon fertig:
sahib@docker:~/docker/paperless$ chmod +x mustang/consume_watch.sh
Damit machen wir das Skript ausführbar. Dann
 
sahib@docker:~/docker/paperless$  docker compose build
sahib@docker:~/docker/paperless$  docker compose up -d
Fertig. Kurz darauf sollten Sie im Browser auf paperless zugreifen können. Bei uns ist das unter http://dev.ait.local:8110/dashboard der Fall, bei Ihrer Dockerumgebung ist das sicher abweichend. Beachten Sie, wir haben den Standardport von 8000 auf 8110 umgemappt, da wir schon einige Sachen in docker laufen haben, die alle auf 8000 wollen.


paperless einrichten

Denn standardmäßig ist es noch nicht GoBD konform

Richten Sie zusnächst einen Adminaccount ein. Bei Benutzer und Gruppen, legen Sie sich passende an. Wichtig ist hier eigentlich nur, daß Sie bei der Rechtevergabe darauf achten, daß ausser dem Admin-Account, niemand anderes im System löschen / Rechte vergeben darf. Wenn der Admin zeitgleich noch andere Funktionen inne hat, dann legen Sie ihm bitte einen weiteren Account ohne Adminrechte an, den er für's tägliche Arbeiten in paperless nutzt.

Eine wichtige Einstellung in Ihren Einstellungen (Sie sind ja noch als Admin im System): im Tab Berechtigungen machen Sie die Standardberechtigungen raus. Sonst sind alle Elemente die wir gleich anlegen zunächst nur für Sie - das wollen wir aber nicht, die sollen von allen Usern genutzt werden.

Dann mal von oben nach unten:


Tags

wir legen an: Eingang, Ausgang, gelöscht und SYSTEM. Bei allen wählen Sie beim Anlegen unter Zuweisungsalgorithmus: keiner


Dokumententypen

Wir legen an: Rechnung [Ausgang], Rechnung [Eingang]. Auch hier: keine automatische Zuweisung


Speicherpfade

Wir legen an: Standard:
Pfad: {{ correspondent }}/{{ document_type }}/{{ created_year }}/{{ created_month }}/{{ title }}
Keine automatische Zuweisung. Den Pfad an sich können Sie selbst anpassen, wie es für Sie genehm ist. Der hier löst sich beispielsweise wie folgt auf: Kunde/Rechnung [Ausgang]/2026/01/rechnung_00001.pdf
Sie können hierzu aber die Vorschaufunktion beim Erstellen nutzen...
Ausserdem brauchen wir: gelöschte Dokumente
gelöschte Dokumente/{{ correspondent }}/{{ document_type }}/{{ created_year }}/{{ created_month }}/{{ title }}
Dieser Ordner ist wichtig, weil wir laut GoBD nicht einfach Vogänge löschen dürfen. Daher verschieben wir die nur...
Keine automatische Zuweisung.


Arbeitsabläufe

Wir legen an: Rechnungen  [Ausgang] erkennen
Auslöser ist Dokument hinzugefügt.
Inhaltsabgleichsalgorithmus: Regulärer Ausdruck.
Lieblingswitz: Manchmal scheint die beste Lösung für ein Problem ein regulärer Ausdruck zu sein. Gratulation - jetzt haben Sie 2 Probleme!
Mit dem Regulären Ausdruck wollen wir Ihre eigenen Rechnungen erkennen. D.h. Wir suchen Begriffe die so nur auf Ihrer eigenen Rechnung vorkommen. zB Ihre Steuernummer, Ihre HRB-Nummer, oder Ihre Domain.
Daraus machen wir jetzt einen Regulärer Ausdruck, der genau auf diese Dinge reagiert.
Den selbst zu erstellen macht Laien echt keinen Spaß (wir arbeiten natürlich sehr häufig mit RegEx, sind ja aber auch Entwickler). Nutzen Sie deshalb eine KI Ihrer Wahl (zB perpelexity.ai) und geben Sie ein Promt wie dieses hier ein: 
erstelle einen robusten regex für paperless ngx arbeitsabläufe. der regex soll auf diesen Begriffe reagieren: "HRB: 1234567"
Bitte berücksichtige daß beim Einlesen der PDFs durch OCR Fehler entstehen können oder Leerzeichen/Zeilenumbrüche fehlen, oder hinzugefügt werden.


Was auch immer dann da raus kommt, Copy'Paste in den Arbeitsablauf. Unter Aktion wählen Sie dann noch den Ausgang-Tag und den Ausgangs-Dokumententyp. Fertig.

Nächster Ablauf: Rechnungen  [Ausgang] erkennen.
Kein Inhaltsabgleichsalgorithmus, dafür der erweiterte Filter: hat diesen Tag nicht: Ausgang
Unter Aktion ordnen wir jetzt wieder Tag und Dokumententyp zu: Eingang

Wir legen an: Dokument [löschen]
Auslöser ist Dokument hinzugefügt.
Inhaltsabgleichsalgorithmus: keiner. Erweiterter Filter: hat Tag: gelöscht
Aktion: Speicherpfad zuweisen - gelöschte Dokumente

Wir legen an: Dokument [löschen] [rückgänig]
Auslöser ist Dokument hinzugefügt.
Inhaltsabgleichsalgorithmus: keiner. Erweiterter Filter: hat Tag nicht: gelöscht
Aktion: Speicherpfad zuweisen - Standard
 

So, das wars.

Ab jetzt sollten neue Dokumente nur noch in den consume-Ordner gelegt werden, danach tauchen sie in der Dokumentenliste von Paperless auf. Ein-/Ausgang ist schon richtig zugeordnet. Fleißige Bienchen weisen jetzt noch jedem Dokument einen Korrepondenten zu. Wir sortieren dazu nach Korrespondent, so daß die Vorgänge ohne oben angezeigt werden.
1. Anklicken, Korrespondent wird vorgeschlagen wenn er erkannt wurde, ansonsten neu anlegen. Häufig genutze legen wir mit einem Zuweisungsfilter über einen passenden Suchbegriff an, dann klappt das in Zukunft zuverlässig. Speichern und weiter zeigt die nächste unbearbeitete Rechung in der Liste. Geht eigentlich recht fix. Für einmalige Kunden/Lieferanten haben wir den "diverse" Korrespondenten. Keine Sorge: über die Volltextsuche findet man das Dokument trotzdem!
Ab und an auch mal ein Blick auf das erkannte Datum werfen, wobei das eigentlich recht zuverlässig klappt. 


...oder war's das doch nicht?

Nein, natürlich nicht. Deutsche Bürokratie!

Man mag es kaum glauben, aber wichtiger als die technische Lösung ist, daß die Lösung dokumentiert ist!
Um Ihnen Arbeit abzunehmen hier eine passende Verfahrensbeschreibung als Muster für Sie.

Mustertext.docx [20,88 KB]

Das Muster hat noch keiner Betriebsprüfung standgehalten, noch wurde es von einem Steuerberateroder Anwalt abgesegnet - die Nutzung erfolgt auf eigenes Risiko. Dies gilt übrigens für alle Anweisungen aus diesem Artikel...

Stellen, die Sie anpassen müssen, sind rot. Es macht absolut Sinn, sie trotzdem mal ganz durchzulesen, Sie müssen Sich ja an dieses Verfahren später auch halten, sonst bringt es nicht! Vor einer Prüfung macht es noch Sinn, zB eine KI die ganze Doku für den Prüfer kurz zusammenzufassen zu lassen, das gibt Pluspunkte ;-)

Dann mal viel Spaß damit - In Zukunft schläft Ihr Admin mit dem ruhigen Gewissen, daß das GoBD-Problem abgehakt ist...

 
Tobias Arnoldt, 19.01.2026 | zurück zur Blog-Übersicht