Importeer een bank-CSV in Beancount met bea

Een gewone bank CSV heeft geen Python-importeur nodig. Koppel de kolommen met --csv, benoem de bronrekening met --account, categoriseer rijen met --rules, en bekijk vervolgens een preview en pas de boekingen toe met bea import.

Je hebt een bestaand grootboek nodig. Als je nieuwe boeken begint, volg dan de CLI quick start. Bewaar de originele bankexport zodat je deze kunt vergelijken met de preview.

1. Koppel de CSV-kolommen​

Sla dit voorbeeld op als statement.csv en voer onderstaande commando's uit vanuit dezelfde map:

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

Bedragen gebruiken de banktekenconventie: uitgaven zijn negatief en een storting is positief. De valuta is standaard die van het grootboek, dus deze file heeft geen valutakolom nodig. Zet een bankomschrijvingkolom in narration en behoud payee voor de handelaar.

Maak het grootboek aan en open de gebruikte brandstofsubrekening hieronder:

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

De template opent Expenses:Groceries en de andere veelgebruikte rekeningen al. Expenses:Transport:Fuel wordt niet geopend, dus de tweede opdracht opent deze vóór de import. Globale opties zoals --file gaan vóór de subcommand.

2. Bekijk de boekingen in preview​

Sla deze categorisatieregels op als rules.toml en bekijk ze dan in preview:

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

Regels passen eerst de begunstigde toe, daarna de omschrijving, zonder hoofdlettergevoeligheid. De eerste regel die klopt, wint. Rijen waar geen regel op past, worden geboekt naar Expenses:Uncategorized met vlag ! voor latere controle. De product IMPORTING gids documenteert de volledige mappingreferentie, inclusief de debit en credit combinatie, de category kolom, en --csv auto header uitlezing.

Er wordt nog niets naar het grootboek geschreven. De preview rapporteert 3 ready, 0 exact duplicates, 0 possible duplicates en eindigt met status 0. De RULE kolom bevat per rij het winnende patroon, of unmatched voor de Unknown Shop-rij. Controleer de data, begunstigden, getekende bronbedragen, bestemmingsrekeningen, dubbele matches en het voorgestelde bestandsverschil. Corrigeer een verkeerde regel of categorie en toon opnieuw een preview. Open eventuele ontbrekende rekeningen vóór het toepassen van de import: een regel die een rekening benoemt die het grootboek niet opent, faalt de validatie.

3. Pas de gecontroleerde boekingen toe​

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"

De kolomtoewijzing wordt per grootboek, headerrij en bronrekening onthouden, dus --apply voert opnieuw uit zonder vlaggen en rapporteert met de onthouden kolomtoewijzing. Het berekent de preview opnieuw tegen de huidige bestanden, valideert het volledige kandidaat-grootboek voordat het schrijft, en schrijft 3 boekingen. bea check meldt geen fouten. De !-wachtrij toont de ene niet-overeenkomende rij: Unknown Shop met mystery bij -9.99 USD. Een geslaagde controle bewijst alleen dat het grootboek in balans is en valideert. Het zegt niets over of die rij thuishoort in Expenses:Uncategorized, dus hercategoriseer deze bewust in je grootboek. De controle eindigt bij 930.01 USD: het 1,000 USD openingssaldo minus 69.99 USD aan uitgaven.

4. Herhaalde imports voegen niets toe​

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

De preview rapporteert 0 ready, 3 exact duplicates, en de run schrijft 0 boekingen met exit 0. Elke geschreven rij bevat import-id-metadata met een content-hash, zodat het identieke bestand overeenkomt met elke rij. Behoud die metadata bij het bewerken van geïmporteerde boekingen. Importeren voegt boekingen toe; het werkt een bestaande transactie niet bij of verwijdert die niet. Voer correcties bewust uit in je grootboek en voer daarna bea check uit. Bulk JSON invoer met bea add transactions heeft geen dubbele detectie.

5. Los mogelijke duplicaten op​

Een latere download kan een rij herhalen met een andere omschrijving of bank-ID's. Datum, genormaliseerde begunstigde en getekend bronbedrag markeren het nog steeds als een mogelijke match:

Een andere bank-ID sluit een duplicaat niet uit. Banken kunnen ID's wijzigen bij latere downloads. Twee echte aankopen kunnen ook datum, begunstigde en bedrag delen, dus een mogelijke match is bewijs, geen zekerheid. Bea raadt niet met een AI-model en categoriseert nooit voor je buiten je regels om.

De standaard --duplicates review weigert onopgeloste overeenkomsten toe te passen. Bij een verificatieloop werd een tweede bestand dat de 2026-08-02 Whole Foods -20.00 USD-rij herhaalde onder een andere omschrijving gepresenteerd als 1 mogelijke duplicaat, en --apply beëindigde met 4 zonder iets te schrijven. Na het beoordelen van elke mogelijke overeenkomst, kies een van deze alternatieven:

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

Kies include om legitieme herhaalde aankopen te behouden. De beslissing geldt voor alle mogelijke overeenkomsten in die aanroep. Exacte duplicaten worden nog steeds overgeslagen. ID-conflicten blokkeren nog steeds het schrijven. --no-input en --yes omzeilen die beoordeling niet. Een bewuste beslissing om elke rij over te slaan beëindigt met 0 zonder toevoegingen aan het grootboek.

6. Gebruik een Python-importer voor andere formaten​

Voor formaten die de kolommapping niet kan uitdrukken, zoals OFX of QIF of een CSV met een ongebruikelijke indeling, roept bea import een geconfigureerde importer aan met behulp van de huidige Beangulp-interface: identify(filepath), account(filepath) en extract(filepath, existing). De importer beheert bankspecifieke verwerking en categorisering. Hij moet expliciete bedragen leveren op bron-rekeningposten zodat dubbele overeenkomsten de daadwerkelijke bankbedragen gebruiken. Een Python-importer blijft het geavanceerde pad voor deze formaten. Voor een native CSV van een bank, probeer eerst --csv.

Voor een eerste oefenrun sla de voorbeeld geconfigureerde CSV configuratie op als importers.py naast je hoofdlijst. Het gebruikt alleen Beancount en de standaardbibliotheek van Python, dus het werkt met de Homebrew-installatie. Het voorbeeld bank.csv gebruikt een ondertekend betaalrekeningbedrag: een -5.25 USD etenskost en een 1,000 USD salarisstorting. De voorbeeldconfiguratie verwacht precies zijn gedocumenteerde kolommen. Voer alleen Python-configuraties uit die je vertrouwt.

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

Je importers.py-configuratie exporteert CONFIG = [importer, ...]. Als meerdere importers het bestand herkennen, selecteer dan een op naam. Een onbekende naam toont de geconfigureerde namen. Een bekende importer die het bestand niet herkent, meldt dat afzonderlijk.

De CLI onthoudt het configuratiepad voor dit hoofdlijst. Toekomstige runs kiezen eerst de expliciete --config, daarna het onthouden pad, daarna importers.py naast de root. De uitvoer vermeldt het pad en de herkomst ervan.

--apply berekent de preview opnieuw op basis van de huidige bestanden. Het valideert het volledige kandidaat-boekingsstuk voordat het schrijft. Een validatiefout laat het oorspronkelijke boekingsstuk ongewijzigd en beëindigt met 1. Een gelijktijdige wijziging aan het boekingsstuk beëindigt met 4; inspecteer de wijziging en voer een nieuwe preview uit voordat u het opnieuw probeert.

Houd importen herhaalbaar​

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

Een regel met een stabiel bank-ID wordt geschreven met import-id metadata die het type benoemt, zoals een bank: of ofx: prefix. Een regel zonder zo'n ID wordt geschreven met een csv:sha256: content hash over datum, bedrag, omschrijving en rekening, zodat het opnieuw importeren van hetzelfde bestand elke regel overslaat. Vóór deze conventie geschreven boekingen kunnen nog steeds bea_import_id metadata bevatten, en die worden bij herimportatie nog steeds gematched. Mogelijke matches worden gecontroleerd tegen bestaande transacties en geaccepteerde regels in dezelfde batch.

Begunstigden, verklaringen en string metadata vervangen regeleinden door spaties vóór preview en schrijven. Aanhalingstekens en backslashes behouden hun inhoud. Geïmporteerde handelsinformatie blijft daardoor leesbaar op één boekingsregel.

Schrijf naar een inbegrepen bestand​

Houd --file gericht op de root en selecteer de bestemming met --into:

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 moet al bestaan en inbegrepen zijn door de root. Het pad is relatief ten opzichte van de rootmap. Het exportpad blijft relatief aan uw werkmap. De preview identificeert het bestand dat zal veranderen.

Gebruik importen in een script​

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

Kies skip alleen als dat uw beoogd beleid is voor mogelijke matches. JSON geeft de preview en het aantal geschreven regels terug binnen data. Geweigerd aanvragen plaatsen de preview in error.result op stderr, met written: 0. Controleer altijd de exit-status. Zie de JSON en exit-code referentie voordat u ongecontroleerde imports inplant.

Los problemen met een importeur op​

Importerconfiguraties draaien in de beheerde engine. Als een configuratie Beangulp importeert, installeer dan de systeem-libmagic bibliotheek en activeer Beangulp daar één keer:

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 rapporteert de geactiveerde functies. Het installeren van een bankimporteur naast de bea frontend maakt deze niet beschikbaar binnen de engine. Een configuratie die extra pakketten importeert heeft die dependencies nodig in de engine; het enkel activeren van Beangulp installeert die niet. Gebruik de CSV-mapper of onderstaande converters wanneer die importeur dependencies niet beschikbaar zijn.

Voor een importer-uitsluiting plaatst u --debug vóór de opdracht om de traceback te tonen. Importeroutput wordt vastgelegd in importer_output zodat deze de JSON niet corrumpeert. In JSON-debugmodus is de traceback error.traceback.

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