Bankexporten importeren met de CLI

Gebruik bea import om een bankexport te bekijken, duplicaten te controleren en gevalideerde invoer aan uw lokale grootboek toe te voegen.

U heeft een bestaand grootboek en een Python-importer nodig voor het exacte exportformaat van uw bank. Als u met nieuwe boeken begint, volg dan de CLI-snelstart. Bewaar de originele bankexport zodat u deze kunt vergelijken met het voorbeeld.

1. Kies een importer​

Een importer leest het bankbestand en levert de transactierekeningen aan. Bea raadt het formaat niet en categoriseert aankopen niet met een AI-model.

Uw importers.py-configuratie exporteert CONFIG = [importer, ...]. Importeurs gebruiken de huidige Beangulp-interface: identify(filepath), account(filepath) en extract(filepath, existing). Bronrekeningboekingen hebben expliciete bedragen nodig voor dubbele matching.

Voor een eerste oefensessie, sla de voorbeeldconfiguratie voor gecategoriseerde CSV op als importers.py naast uw root-grootboek. Het gebruikt alleen Beancount en Python's standaardbibliotheek, dus het werkt met de Homebrew-installatie.

Sla dit voorbeeld op als bank.csv in dezelfde map:

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

Het voorbeeld gebruikt een ondertekend bedrag voor de betaalrekening: uitgaven zijn negatief en een storting is positief. Category levert de andere rekening op. Beide categorieën staan in het USD-sjabloon dat door bea init is gemaakt.

Gebruik een importer die voor uw bank is geschreven bij het importeren van de native CSV, OFX of QIF. De voorbeeldconfiguratie verwacht exact de bovenstaande kolommen. Voer alleen Python-configuraties uit die u vertrouwt.

2. Bekijk de invoer​

Voer dit uit vanuit de map met main.bean:

bea import bank.csv --config importers.py

Er wordt nog niets naar het grootboek geschreven. Controleer de datums, begunstigden, ondertekende bronbedragen, doelrekeningen, duplicaatovereenkomsten en het voorgestelde bestandsdiff van het voorbeeld.

Voor het voorbeeld moet het voorbeeld een maaltijdkost van 5,25 USD en een salarisstorting van 1.000 USD bevatten. Corrigeer een onjuiste categorie in de importer of brondata en bekijk dan opnieuw. Open eventuele ontbrekende rekeningen voordat u de import toepast.

Als meerdere importeurs het bestand herkennen, selecteer er dan één op naam:

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

Een onbekende naam toont de geconfigureerde namen. Een bekende importer die het bestand niet herkent, meldt dat afzonderlijk.

3. Pas de beoordeelde invoer toe​

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

De CLI onthoudt het configuratiepad voor dit root-grootboek. Toekomstige runs kiezen de expliciete --config, dan het onthouden pad, dan importers.py naast de root. De uitvoer noemt het pad en waar het vandaan komt.

--apply herberekent het voorbeeld op basis van de huidige bestanden. Het valideert het volledige kandidaat-grootboek voordat het schrijft. Een validatiefout laat het originele grootboek ongewijzigd en eindigt met 1. Een gelijktijdige grootboekwijziging eindigt met 4; inspecteer de wijziging en voer een nieuw voorbeeld uit voordat u het opnieuw probeert.

4. Los mogelijke duplicaten op​

Het herhalen van dezelfde voorbeeldimport slaat de bestaande invoer over. Een overlappende export kan ook rijen bevatten die een beslissing vereisen:

Een ander bank-ID sluit een duplicaat niet uit. Banken kunnen ID's wijzigen bij latere downloads. Twee echte aankopen kunnen ook dezelfde datum, begunstigde en bedrag delen.

Na het beoordelen van elke mogelijke overeenkomst, kiest u een van deze alternatieven:

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

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

De beslissing geldt voor alle mogelijke overeenkomsten in die aanroep. Exacte duplicaten blijven overgeslagen. ID-conflicten blokkeren het schrijven nog steeds.

De standaard --duplicates review weigert onopgeloste overeenkomsten toe te passen. Het eindigt met 4 en noemt de betreffende voorbeeldrijen. --no-input en --yes omzeilen die beoordeling niet. Een bewuste beslissing om elke rij over te slaan eindigt met 0 en zonder grootboektoevoegingen.

Houd importen herhaalbaar​

Standaard controleert duplicaatmatching bank_id, fitid, transaction_id en imported_id-metadata binnen de bronrekening van de importer. Gebruik herhaalde --id-key KEY-opties om die set te vervangen.

De CLI schrijft ook bea_import_id-metadata om de rij in de originele export te identificeren. Behoud dit bij het bewerken van geïmporteerde invoer. Mogelijke overeenkomsten worden gecontroleerd tegen bestaande transacties en geaccepteerde rijen in dezelfde batch.

Begunstigden, beschrijvingen en stringmetadata vervangen regeleinden door spaties vóór het voorbeeld en schrijven. Aanhalingstekens en backslashes behouden hun inhoud. Geïmporteerde handelaarstekst blijft dus leesbaar op één grootboekregel.

Importeren voegt invoer toe; het werkt een bestaande transactie niet bij of verwijdert deze niet. Maak correcties bewust in uw grootboek en voer daarna bea check uit. Bulk-JSON-invoer met bea add transactions heeft geen duplicaatdetectie.

Schrijf naar een opgenomen bestand​

Houd --file gericht op de root en selecteer de bestemming met --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 moet al bestaan en worden opgenomen door de root. Het pad is relatief ten opzichte van de rootmap. Het exportpad blijft relatief ten opzichte van uw werkmap. Het voorbeeld identificeert het bestand dat zal veranderen.

Gebruik importen in een script​

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

Kies skip alleen wanneer dat uw beoogde beleid is voor mogelijke overeenkomsten. JSON retourneert het voorbeeld en het schrijfaantal in data. Geweigerde toepassingen plaatsen het voorbeeld in error.result op stderr, met written: 0. Controleer altijd de exitstatus. Zie de JSON- en exitcode-referentie voordat u onbeheerde importen plant.

Problemen met een importer oplossen​

Als de configuratie pakketten van derden importeert, moeten die pakketten in de Python-omgeving staan die bea draait. Bijvoorbeeld:

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

Voeg --with YOUR_IMPORTER_PACKAGE toe voor een afzonderlijk geïnstalleerde bankimporter. Dit gebruikt een aparte omgeving van Homebrew.

Voor een importeruitzondering, plaats --debug vóór de opdracht om de traceback te tonen:

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

De uitvoer van de importer wordt vastgelegd in importer_output, zodat het JSON niet beschadigt. In JSON-debugmodus is de traceback error.traceback.

Voor een eenmalige conversie zonder Python-importer, probeer de CSV-converter of de OFX- en QIF-converter. Controleer de gegenereerde invoer voordat u deze aan uw boeken toevoegt.