Bankexporte mit der CLI importieren

Verwenden Sie bea import, um einen Bankexport in der Vorschau anzusehen, Duplikate zu prüfen und validierte Einträge an Ihr lokales Hauptbuch anzuhängen.

Sie benötigen ein vorhandenes Hauptbuch und einen Python-Importer für das exakte Exportformat Ihrer Bank. Wenn Sie mit neuen Büchern beginnen, folgen Sie der CLI-Schnellstartanleitung. Bewahren Sie den ursprünglichen Bankexport auf, damit Sie ihn mit der Vorschau vergleichen können.

1. Importer auswählen​

Ein Importer liest die Datei der Bank und liefert die Transaktionskonten. Bea errät weder das Format noch kategorisiert es Käufe mit einem KI-Modell.

Ihre importers.py-Konfiguration exportiert CONFIG = [importer, ...]. Importeure verwenden die aktuelle Beangulp-Schnittstelle: identify(filepath), account(filepath) und extract(filepath, existing). Buchungen auf Quellkonten benötigen explizite Beträge für den Duplikatabgleich.

Für einen ersten Übungslauf speichern Sie die Beispielkonfiguration für kategorisierte CSVs als importers.py neben Ihrem Hauptverzeichnis-Hauptbuch. Sie verwendet nur Beancount und die Standardbibliothek von Python und funktioniert daher mit der Homebrew-Installation.

Speichern Sie diese Beispieldatei als bank.csv im selben Verzeichnis:

Date,Payee,Narration,Amount,Currency,Category,BankID
2026-08-02,Cafe,Coffee,-5.25,USD,Expenses:Dining,bank-001
2026-08-03,Employer,Salary,1000,USD,Income:Salary,bank-002

Das Beispiel verwendet einen vorzeichenbehafteten Kontobetrag: Ausgaben sind negativ, Einzahlungen positiv. Category liefert das andere Konto. Beide Kategorien sind in der von bea init erstellten USD-Vorlage enthalten.

Verwenden Sie einen für Ihre Bank geschriebenen Importer, wenn Sie deren natives CSV-, OFX- oder QIF-Format importieren. Die Beispielkonfiguration erwartet genau die oben genannten Spalten. Führen Sie nur Python-Konfigurationen aus, denen Sie vertrauen.

2. Einträge in der Vorschau ansehen​

Führen Sie dies aus dem Verzeichnis aus, das main.bean enthält:

bea import bank.csv --config importers.py

Es wird noch nichts in das Hauptbuch geschrieben. Prüfen Sie in der Vorschau die Daten, Zahlungsempfänger, vorzeichenbehafteten Quellbeträge, Zielkonten, Duplikatübereinstimmungen und den vorgeschlagenen Dateidiff.

Für das Beispiel sollte die Vorschau eine Essensausgabe von 5,25 USD und eine Gehaltseinzahlung von 1.000 USD enthalten. Korrigieren Sie eine falsche Kategorie im Importer oder in den Quelldaten und sehen Sie sich die Vorschau erneut an. Öffnen Sie fehlende Konten, bevor Sie den Import übernehmen.

Wenn mehrere Importeure die Datei erkennen, wählen Sie einen nach Namen aus:

bea import bank.csv --config importers.py --importer categorized-checking

Ein unbekannter Name listet die konfigurierten Namen auf. Ein bekannter Importer, der die Datei nicht erkennt, meldet dies separat.

3. Geprüfte Einträge übernehmen​

bea import bank.csv --apply
bea check
bea list transaction --limit 10

Die CLI merkt sich den Konfigurationspfad für dieses Hauptverzeichnis-Hauptbuch. Zukünftige Läufe wählen zuerst das explizite --config, dann den gemerkten Pfad, dann importers.py neben dem Hauptverzeichnis. Die Ausgabe nennt den Pfad und woher er stammt.

--apply berechnet die Vorschau anhand der aktuellen Dateien neu. Es validiert das vollständige Kandidatenhauptbuch, bevor es schreibt. Ein Validierungsfehler lässt das ursprüngliche Hauptbuch unverändert und beendet sich mit Exit-Code 1. Eine gleichzeitige Änderung des Hauptbuchs beendet sich mit Exit-Code 4; prüfen Sie die Änderung und führen Sie eine neue Vorschau aus, bevor Sie es erneut versuchen.

4. Mögliche Duplikate auflösen​

Das Wiederholen desselben Beispielimports überspringt dessen vorhandene Einträge. Ein überlappender Export kann auch Zeilen enthalten, die eine Entscheidung erfordern:

Eine andere Bank-ID schließt ein Duplikat nicht aus. Banken können IDs bei späteren Downloads ändern. Zwei echte Käufe können auch Datum, Zahlungsempfänger und Betrag teilen.

Nachdem Sie jede mögliche Übereinstimmung geprüft haben, wählen Sie eine dieser Alternativen:

bea import bank.csv --apply --duplicates skip

bea import bank.csv --apply --duplicates include

Die Entscheidung gilt für alle möglichen Übereinstimmungen in diesem Aufruf. Exakte Duplikate bleiben übersprungen. ID-Konflikte blockieren weiterhin das Schreiben.

Die Standardeinstellung --duplicates review weigert sich, ungeklärte Übereinstimmungen zu übernehmen. Sie beendet sich mit Exit-Code 4 und nennt die betroffenen Vorschauzeilen. --no-input und --yes umgehen diese Prüfung nicht. Eine bewusste Entscheidung, jede Zeile zu überspringen, beendet sich mit Exit-Code 0 und ohne Hinzufügungen zum Hauptbuch.

Importe wiederholbar halten​

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

Die CLI schreibt außerdem die Metadaten bea_import_id, um die Zeile im ursprünglichen Export zu identifizieren. Behalten Sie sie bei, wenn Sie importierte Einträge bearbeiten. Mögliche Übereinstimmungen werden gegen vorhandene Transaktionen und akzeptierte Zeilen im selben Stapel geprüft.

Zahlungsempfänger, Erzählungen und String-Metadaten ersetzen Zeilenumbrüche durch Leerzeichen, bevor sie in der Vorschau angezeigt und geschrieben werden. Anführungszeichen und Backslashes behalten ihren Inhalt. Importierter Händlertext bleibt daher auf einer einzigen Hauptbuchzeile lesbar.

Das Importieren fügt Einträge hinzu; es aktualisiert oder löscht keine vorhandene Transaktion. Nehmen Sie Korrekturen bewusst in Ihrem Hauptbuch vor und führen Sie danach bea check aus. Der Bulk-JSON-Import mit bea add transactions hat keine Duplikaterkennung.

In eine eingebundene Datei schreiben​

Halten Sie --file auf das Hauptverzeichnis gerichtet und wählen Sie das Ziel mit --into:

bea --file ~/my-books/main.bean import bank.csv --into 2026.bean
bea --file ~/my-books/main.bean import bank.csv --into 2026.bean --apply

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

Importe in einem Skript verwenden​

bea --json --no-input import bank.csv --apply --duplicates skip

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

Fehlerbehebung bei einem Importer​

Wenn die Konfiguration Pakete von Drittanbietern importiert, müssen diese Pakete in der Python-Umgebung installiert sein, die bea ausführt. Zum Beispiel:

uv run --with beancount-io --with beangulp \
  bea --file ~/my-books/main.bean import bank.ofx --config importers.py

Fügen Sie --with YOUR_IMPORTER_PACKAGE für einen separat installierten Bank-Importer hinzu. Dies verwendet eine separate Umgebung von Homebrew.

Bei einer Importer-Ausnahme setzen Sie --debug vor den Befehl, um dessen Traceback anzuzeigen:

bea --debug import bank.csv --config importers.py

Die Importer-Ausgabe wird in importer_output erfasst, sodass sie JSON nicht beschädigt. 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. Prüfen Sie die generierten Einträge, bevor Sie sie zu Ihren Büchern hinzufügen.