Eine Bank-CSV mit bea in Beancount importieren

Eine gewöhnliche Bank-CSV benötigt keinen Python-Importer. Ordnen Sie ihre Spalten mit --csv zu, benennen Sie das Quellkonto mit --account, kategorisieren Sie Zeilen mit --rules, und prüfen und übernehmen Sie dann die Buchungen mit bea import.

Sie benötigen ein bestehendes Hauptbuch. Wenn Sie neue Bücher beginnen, folgen Sie dem CLI Schnellstart. Bewahren Sie den originalen Bankexport auf, um ihn mit der Vorschau vergleichen zu können.

1. Die CSV-Spalten zuordnen​

Speichern Sie dieses Beispiel als statement.csv und führen Sie dann die folgenden Befehle aus demselben Verzeichnis aus:

Date,Payee,Narration,Amount
2026-08-02,Whole Foods,groceries,-20.00
2026-08-03,Shell,gas,-40.00
2026-08-04,Unknown Shop,mystery,-9.99

Beträge verwenden die Bank-Vorzeichenkonvention: Ausgaben sind negativ und eine Einzahlung positiv. Die Währung ist standardmäßig die Betriebwährung des Hauptbuchs, daher benötigt diese Datei keine Währungsspalte. Legen Sie eine Bankbeschreibungs-Spalte in narration an und behalten Sie payee für den Händler bei.

Erstellen Sie das Hauptbuch und öffnen Sie das unten verwendete Unterkonto für Kraftstoff:

bea --no-input init books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-08-01 --account Expenses:Transport:Fuel -c USD

Die Vorlage öffnet bereits Expenses:Groceries und die anderen üblichen Konten. Expenses:Transport:Fuel wird nicht geöffnet, daher öffnet der zweite Befehl es vor dem Import. Globale Optionen wie --file stehen vor dem Unterbefehl.

2. Die Buchungen vorschauen​

Speichern Sie diese Kategorisierungsregeln als rules.toml und sehen Sie sie sich dann in der Vorschau an:

cat > rules.toml <<'EOF'
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
 
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"
EOF
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee,narration=Narration --account Assets:Checking --rules rules.toml

Regeln passen zuerst auf den Zahlungsempfänger und dann auf die Beschreibung, ohne Groß-/Kleinschreibung zu beachten. Die erste passende Regel gewinnt. Zeilen, auf die keine Regel zutrifft, werden mit Flagge ! an Expenses:Uncategorized gebucht zur späteren Überprüfung. Der Produkt-IMPORTIEREN Leitfaden dokumentiert das vollständige Zuordnungsreferenz, einschließlich des Paars debit und credit, der category-Spalte und des Einlesens von --csv auto-Kopfzeilen.

Es wird noch nichts ins Hauptbuch geschrieben. Die Vorschau meldet 3 ready, 0 exact duplicates, 0 possible duplicates und gibt Status 0 zurück. Seine RULE-Spalte benennt das gewinnende Muster pro Zeile oder unmatched für die Unknown Shop-Zeile. Überprüfen Sie die Daten, Begünstigten, vorzeichenbehafteten Quellbeträge, Zielkonten, Duplikatübereinstimmungen und den vorgeschlagenen Dateiunterschied. Korrigieren Sie eine falsche Regel oder Kategorie und schauen Sie erneut in die Vorschau. Öffnen Sie alle fehlenden Konten vor dem Anwenden des Imports: Eine Regel, die ein Konto benennt, dass das Hauptbuch nicht öffnet, schlägt die Validierung fehl.

3. Die geprüften Buchungen übernehmen​

bea --file books/main.bean import statement.csv --apply
bea --file books/main.bean check
bea --file books/main.bean list transaction --flag '!'
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

Die Spaltenzuordnung wird pro Hauptbuch, Kopfzeile und Quellkonto gespeichert, sodass --apply ohne Flags erneut ausgeführt wird und die gespeicherte Spaltenzuordnung verwendet. Die Vorschau wird anhand der aktuellen Dateien neu berechnet, das vollständige Kandidatenhauptbuch wird vor dem Schreiben validiert und 3 Buchungen werden geschrieben. bea check meldet keine Fehler. Die !-Warteschlange listet die eine nicht abgeglichene Zeile: Unknown Shop mit mystery bei -9.99 USD. Ein bestandener Check zeigt nur, dass das Hauptbuch ausgeglichen ist und validiert wurde. Es sagt nichts darüber aus, ob diese Zeile zu Expenses:Uncategorized gehört, daher kategorisieren Sie sie bewusst in Ihrem Hauptbuch um. Die Prüfung endet bei 930.01 USD: der 1,000 USD Anfangssaldo minus 69.99 USD Ausgaben.

4. Wiederholte Importe bringen nichts​

bea --file books/main.bean import statement.csv --apply

Die Vorschau meldet 0 ready, 3 exact duplicates, und der Lauf schreibt 0 Einträge mit Exit 0. Jede geschriebene Zeile trägt import-id Metadaten mit einem Inhalts-Hash, sodass die identische Datei mit jeder Zeile übereinstimmt. Behalten Sie diese Metadaten beim Bearbeiten importierter Einträge bei. Importieren fügt Einträge hinzu; es aktualisiert oder löscht keine bestehenden Buchungen. Nehmen Sie Korrekturen gezielt in Ihrem Hauptbuch vor und führen Sie anschließend bea check aus. Massenhafte JSON-Eingabe mit bea add transactions erkennt keine Duplikate.

5. Mögliche Duplikate auflösen​

Ein späterer Download kann eine Zeile mit anderer Bezeichnung oder Bank-IDs wiederholen. Datum, normalisierter Zahlungsempfänger und signierter Quellbetrag kennzeichnen sie dennoch als mögliche Übereinstimmung:

Eine andere Bank-ID schließt ein Duplikat nicht aus. Banken können bei späteren Downloads IDs ändern. Zwei echte Käufe können außerdem dasselbe Datum, denselben Zahlungsempfänger und Betrag teilen, sodass eine mögliche Übereinstimmung Beleg und kein Beweis ist. Bea rät nicht mit einem KI-Modell und kategorisiert nie automatisch für Sie über Ihre Regeln hinaus.

Der Standard --duplicates review lehnt die Anwendung von ungeklärten Übereinstimmungen ab. Bei einem Verifikationslauf wurde eine zweite Datei mit einer wiederholten 2026-08-02 Whole Foods -20.00 USD-Zeile unter einer anderen Erläuterung als 1 mögliche Duplikatvorschau erkannt, und --apply endete mit 4 ohne etwas zu schreiben. Nach Prüfung aller möglichen Übereinstimmungen wählen Sie eine dieser Alternativen:

bea --file books/main.bean import statement.csv --apply --duplicates skip
bea --file books/main.bean import statement.csv --apply --duplicates include

Wählen Sie include, um legitime wiederholte Käufe zu erhalten. Die Entscheidung gilt für alle möglichen Übereinstimmungen bei dieser Ausführung. Exakte Duplikate bleiben übersprungen. ID-Konflikte verhindern weiterhin das Schreiben. --no-input und --yes umgehen diese Prüfung nicht. Eine bewusste Entscheidung, jede Zeile zu überspringen, beendet mit 0 ohne Buchhaltungszugänge.

6. Verwenden Sie einen Python-Importer für andere Formate​

Für Formate, die nicht durch die Spaltenzuordnung ausgedrückt werden können, wie OFX, QIF oder eine CSV mit ungewöhnlichem Layout, ruft bea import einen konfigurierten Importer über die aktuelle Beangulp-Schnittstelle auf: identify(filepath), account(filepath) und extract(filepath, existing). Der Importer übernimmt die bankspezifische Analyse und Kategorisierung. Er muss explizite Beträge bei den Quellkontobuchungen bereitstellen, damit bei der Dublettenprüfung die tatsächlichen Bankbeträge verwendet werden. Ein Python-Importer ist weiterhin der fortgeschrittene Weg für diese Formate. Für eine bankeigene CSV versuchen Sie zunächst --csv.

Für einen ersten Übungslauf speichern Sie die Beispiel-Konfiguration für kategorisierte CSV als importers.py neben Ihrem Hauptbuch ab. Sie verwendet nur Beancount und Pythons Standardbibliothek, daher funktioniert sie mit der Homebrew-Installation. Das Beispiel-bank.csv nutzt einen signierten Betrag des Girokontos: einen -5.25 USD Essensaufwand und eine 1,000 USD Gehaltseinzahlung. Die Beispielkonfiguration erwartet genau ihre dokumentierten Spalten. Führen Sie nur Python-Konfigurationen aus, denen Sie vertrauen.

bea --file books/main.bean import bank.csv --config importers.py
bea --file books/main.bean import bank.csv --config importers.py --importer categorized-checking
bea --file books/main.bean import bank.csv --config importers.py --apply

Ihre importers.py-Konfiguration exportiert CONFIG = [importer, ...]. Wenn mehrere Importer die Datei erkennen, wählen Sie einen nach Namen aus. Ein unbekannter Name listet die konfigurierten Namen auf. Ein bekannter Importer, der die Datei nicht erkennt, meldet dies gesondert.

Das CLI merkt sich den Konfigurationspfad für dieses Hauptbuch. Zukünftige Ausführungen wählen zuerst die explizite --config, dann den gemerkten Pfad, dann importers.py neben dem Hauptbuch. Die Ausgabe nennt den Pfad und seine Herkunft.

--apply berechnet die Vorschau anhand der aktuellen Dateien neu. Es validiert das vollständige Kandidaten-Hauptbuch vor dem Schreiben. Ein Validierungsfehler lässt das ursprüngliche Hauptbuch unverändert und beendet mit Code 1. Eine gleichzeitige Änderung des Hauptbuchs beendet mit Code 4; überprüfen Sie die Änderung und führen Sie vor dem erneuten Versuch eine frische Vorschau aus.

Importe wiederholbar halten​

Standardmäßig prüft die Duplikatsübereinstimmung bank_id, fitid, transaction_id und imported_id Metadaten innerhalb des Quellkontos des Importeurs. Verwenden Sie wiederholte --id-key KEY Optionen, um diesen Satz zu ersetzen.

Eine Zeile mit einer stabilen Bank-ID wird mit import-id Metadaten geschrieben, die ihre Art benennen, z. B. ein bank: oder ofx: Präfix. Eine Zeile ohne eine solche wird mit einem csv:sha256: Inhalts-Hash über Datum, Betrag, Beschreibung und Konto geschrieben, sodass das erneute Importieren derselben Datei jede Zeile überspringt. Einträge, die vor dieser Konvention geschrieben wurden, können dennoch bea_import_id Metadaten enthalten, und diese stimmen beim Re-Import weiterhin überein. Mögliche Übereinstimmungen werden gegen bestehende Transaktionen und akzeptierte Zeilen im selben Stapel geprüft.

Begünstigte, Erläuterungen und Zeichenketten-Metadaten ersetzen Zeilenumbrüche vor der Vorschau und dem Schreiben durch Leerzeichen. Anführungszeichen und Rückwärtsschritte behalten ihre Inhalte. Der importierte Händlertext bleibt dadurch auf einer einzigen Hauptbuchzeile lesbar.

In eine eingebundene Datei schreiben​

Behalten Sie --file auf das Root-Verzeichnis gerichtet und wählen Sie das Ziel mit --into aus:

bea --file books/main.bean import statement.csv --into 2026.bean
bea --file books/main.bean import statement.csv --into 2026.bean --apply

2026.bean muss bereits existieren und vom Root-Verzeichnis eingebunden sein. Sein Pfad ist relativ zum Root-Verzeichnis. Der Exportpfad bleibt relativ zu Ihrem Arbeitsverzeichnis. Die Vorschau identifiziert die Datei, die sich ändern wird.

Importe in einem Skript verwenden​

bea --file books/main.bean --json --no-input import statement.csv --apply --duplicates skip

Wählen Sie skip nur, wenn dies Ihre beabsichtigte Policy für mögliche Übereinstimmungen ist. JSON gibt die Vorschau und Anzahl der Schreibvorgänge innerhalb von data zurück. Abgelehnte Anwendungen legen die Vorschau in error.result auf stderr mit written: 0. Prüfen Sie stets den Exit-Status. Siehe die JSON- und Exit-Code-Referenz, bevor Sie unbeaufsichtigte Importe planen.

Einen Importeur beheben​

Importeur-Konfigurationen laufen in der verwalteten Engine. Wenn eine Konfiguration Beangulp importiert, installieren Sie die System-libmagic-Bibliothek und aktivieren Sie Beangulp dort einmalig:

bea engine enable beangulp
bea --file books/main.bean import bank.ofx --config importers.py
bea --debug --file books/main.bean import bank.csv --config importers.py

bea engine status meldet die aktivierten Funktionen. Die Installation eines Bankimporteurs neben der bea-Oberfläche macht diesen nicht innerhalb der Engine verfügbar. Eine Konfiguration, die zusätzliche Pakete importiert, benötigt diese Abhängigkeiten in der Engine; die Aktivierung von Beangulp allein installiert sie nicht. Verwenden Sie den CSV-Mapper oder die unten stehenden Konverter, wenn diese Importeur-Abhängigkeiten nicht verfügbar sind.

Für eine Importer-Ausnahme setzen Sie --debug vor den Befehl, um dessen Traceback anzuzeigen. Die Ausgabe des Importers wird in importer_output erfasst, sodass das JSON nicht beschädigt wird. Im JSON-Debug-Modus ist der Traceback error.traceback.

Für eine einmalige Konvertierung ohne Python-Importer versuchen Sie den CSV-Konverter oder den OFX- und QIF-Konverter. Überprüfen Sie die generierten Einträge, bevor Sie sie in Ihre Bücher aufnehmen.