Import bankového CSV do Beancount pomocou bea

Bežný bankový CSV nepotrebuje Python importer. Mapujte jeho stĺpce pomocou --csv, pomenujte zdrojový účet pomocou --account, kategorizujte riadky pomocou --rules a potom zobrazte a aplikujte položky pomocou bea import.

Potrebujete existujúci účtovný denník. Ak začínate nové účtovníctvo, postupujte podľa CLI rýchleho štartu. Uchovajte pôvodný bankový export, aby ste ho mohli porovnať s náhľadom.

1. Mapovanie stĺpcov CSV​

Uložte túto vzorku ako statement.csv a potom spustite príkazy nižšie z rovnakého adresára:

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

Sumy používajú bankovú konvenciu znamienok: výdavky sú záporné a vklad je kladný. Mena sa predvolene nastaví na prevádzkovú menu účtovného denníka, takže tento súbor nepotrebuje stĺpec meny. Umiestnite stĺpec s popisom banky do narration a ponechajte payee pre obchodníka.

Vytvorte účtovný denník a otvorte podúčet paliva použitý nižšie:

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

Šablóna už otvára Expenses:Groceries a ostatné bežné účty. Neotvára Expenses:Transport:Fuel, takže druhý príkaz ho otvorí pred importom. Globálne možnosti ako --file idú pred podpríkaz.

2. Zobrazenie položiek​

Uložte tieto pravidlá kategorizácie ako rules.toml a potom zobrazte náhľad:

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

Pravidlá sa najprv zhodujú s príjemcom, potom s naráciou, pričom ignorujú veľkosť písmen. Vyhráva prvé zodpovedajúce pravidlo. Riadky, ktorým nezodpovedá žiadne pravidlo, sa účtujú na Expenses:Uncategorized s príznakom ! na neskoršiu kontrolu. Produkt IMPORTING sprievodca dokumentuje kompletný referenčný rámec mapovania, vrátane páru debit a credit, stĺpca category a čítania hlavičiek --csv auto.

Zatiaľ sa do účtovného denníka nič nezapisuje. Náhľad hlási 3 ready, 0 exact duplicates, 0 possible duplicates a končí s kódom 0. Jeho stĺpec RULE pomenúva víťazný vzor pre každý riadok alebo unmatched pre riadok Unknown Shop. Skontrolujte dátumy, príjemcov, podpísané zdrojové sumy, cieľové účty, zhody duplicít a navrhovaný diff súboru. Opravte nesprávne pravidlo alebo kategóriu a potom znova zobrazte náhľad. Pred aplikáciou importu otvorte všetky chýbajúce účty: pravidlo pomenúvajúce účet, ktorý účtovný denník neotvára, zlyhá pri overení.

3. Aplikácia skontrolovaných položiek​

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"

Mapovanie stĺpcov sa pamätá pre každý účtovný denník, riadok hlavičky a zdrojový účet, takže --apply sa spustí znova bez príznakov a hlási pomocou zapamätaného mapovania stĺpcov. Prepočíta náhľad proti aktuálnym súborom, overí kompletný kandidátny účtovný denník pred zápisom a zapíše 3 položky. bea check hlási žiadne chyby. Front ! zobrazuje jeden nezodpovedaný riadok: Unknown Shop s mystery pri -9.99 USD. Úspešná kontrola len dokazuje, že účtovný denník je vyvážený a platný. Nehovorí nič o tom, či tento riadok patrí do Expenses:Uncategorized, takže ho zámerne prekategorizujte vo svojom účtovnom denníku. Kontrola končí pri 930.01 USD: počiatočný zostatok 1,000 USD mínus 69.99 USD výdavkov.

4. Opakované importy nepridávajú nič​

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

Náhľad hlási 0 ready, 3 exact duplicates a spustenie zapíše 0 položiek s kódom 0. Každý zapísaný riadok nesie metadáta import-id s hašom obsahu, takže identický súbor sa zhoduje s každým riadkom. Zachovajte tieto metadáta pri úprave importovaných položiek. Import pridáva položky; neaktualizuje ani nemaže existujúcu transakciu. Vykonajte opravy zámerne vo svojom účtovnom denníku a potom spustite bea check. Hromadný JSON zápis pomocou bea add transactions nemá detekciu duplicít.

5. Riešenie možných duplicít​

Neskoršie stiahnutie môže zopakovať riadok s inou naráciou alebo bankovými ID. Dátum, normalizovaný príjemca a podpísaná zdrojová suma ho stále označujú ako možnú zhodu:

Iné bankové ID nevylučuje duplicitu. Banky môžu meniť ID pri neskorších stiahnutiach. Dva skutočné nákupy môžu tiež zdieľať dátum, príjemcu a sumu, takže možná zhoda je dôkaz, nie dôkaz istoty. Bea nehádže s AI modelom a nikdy nekategorizuje za vás nad rámec vašich pravidiel.

Predvolené --duplicates review odmieta aplikovať nevyriešené zhody. V overovacom spustení sa druhý súbor opakujúci riadok 2026-08-02 Whole Foods -20.00 USD s inou naráciou zobrazil ako 1 možná duplicita a --apply skončil s kódom 4 bez zápisu. Po preskúmaní každej možnej zhody vyberte jednu z týchto alternatív:

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

Vyberte include na zachovanie legitímnych opakovaných nákupov. Rozhodnutie sa vzťahuje na všetky možné zhody v tomto vyvolaní. Presné duplicity zostávajú preskočené. Konflikty ID stále blokujú zápis. --no-input a --yes neobchádzajú túto kontrolu. Zámerné rozhodnutie preskočiť každý riadok končí s kódom 0 bez pridaní do účtovného denníka.

6. Použitie Python importera pre iné formáty​

Pre formáty, ktoré mapovanie stĺpcov nedokáže vyjadriť, ako OFX alebo QIF alebo CSV s nezvyčajným rozložením, bea import volá nakonfigurovaný importer pomocou aktuálneho Beangulp rozhrania: identify(filepath), account(filepath) a extract(filepath, existing). Importer vlastní bankovo špecifické parsovanie a kategorizáciu. Musí poskytnúť explicitné sumy na účtovaniach zdrojového účtu, aby párovanie duplicít používalo skutočné bankové sumy. Python importer zostáva pokročilou cestou pre tieto formáty. Pre natívny CSV banky skúste najprv --csv.

Pre prvý tréningový beh uložte príklad konfigurácie CSV importéra ako importers.py vedľa svojho koreňového účtovného denníka. Používa iba Beancount a štandardnú knižnicu Pythonu, takže funguje s inštaláciou cez Homebrew. Jeho vzorový bank.csv používa podpísanú sumu bežného účtu: výdavok na stravovanie -5.25 USD a vklad mzdy 1,000 USD. Vzorová konfigurácia očakáva presne svoje dokumentované stĺpce. Spúšťajte iba Python konfigurácie, ktorým dôverujete.

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

Vaša konfigurácia importers.py exportuje CONFIG = [importer, ...]. Ak niekoľko importérov rozpozná súbor, vyberte jeden podľa mena. Neznáme meno zobrazí nakonfigurované mená. Známý importer, ktorý súbor nerozpozná, to hlási samostatne.

CLI si pamätá cestu konfigurácie pre tento koreňový účtovný denník. Budúce spustenia vyberú explicitné --config, potom zapamätanú cestu, potom importers.py vedľa koreňa. Výstup pomenúva cestu a odkiaľ pochádza.

--apply prepočíta náhľad proti aktuálnym súborom. Overí kompletný kandidátny účtovný denník pred zápisom. Zlyhanie overenia ponechá pôvodný účtovný denník nezmenený a končí s kódom 1. Súbežná zmena účtovného denníka končí s kódom 4; skontrolujte zmenu a spustite čerstvý náhľad pred opätovným pokusom.

Udržiavanie importov opakovateľných​

Predvolene párovanie duplicít kontroluje metadáta bank_id, fitid, transaction_id a imported_id v rámci zdrojového účtu importéra. Použite opakované možnosti --id-key KEY na nahradenie tejto sady.

Riadok so stabilným bankovým ID sa zapíše s metadátami import-id pomenúvajúcimi jeho druh, ako predpona bank: alebo ofx:. Riadok bez neho sa zapíše s hašom obsahu csv:sha256: cez jeho dátum, sumu, popis a účet, takže opätovný import rovnakého súboru preskočí každý riadok. Položky zapísané pred touto konvenciou môžu stále niesť metadáta bea_import_id a tie sa stále zhodujú pri opätovnom importe. Možné zhody sa kontrolujú proti existujúcim transakciám a akceptovaným riadkom v tej istej dávke.

Príjemcovia, narácie a reťazcové metadáta nahrádzajú konce riadkov medzerami pred náhľadom a zápisom. Úvodzovky a spätné lomítka si zachovávajú svoj obsah. Importovaný obchodný text preto zostáva čitateľný na jednom riadku účtovného denníka.

Zápis do zahrnutého súboru​

Ponechajte --file nasmerovaný na koreň a vyberte cieľ pomocou --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 musí už existovať a byť zahrnutý koreňom. Jeho cesta je relatívna k adresáru koreňa. Cesta exportu zostáva relatívna k vášmu pracovnému adresáru. Náhľad identifikuje súbor, ktorý sa zmení.

Použitie importov v skripte​

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

Vyberte skip iba vtedy, keď je to váš zamýšľaný postup pre možné zhody. JSON vracia náhľad a počet zápisov v data. Odmietnuté aplikácie umiestňujú náhľad do error.result na stderr s written: 0. Vždy skontrolujte stav ukončenia. Pozrite si referenciu JSON a kódov ukončenia pred plánovaním neobsluhovaných importov.

Riešenie problémov s importerom​

Konfigurácie importerov sa spúšťajú v spravovanom engine. Ak konfigurácia importuje Beangulp, nainštalujte systémovú knižnicu libmagic a povoľte Beangulp tam raz:

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 hlási povolené funkcie. Inštalácia bankového importéra vedľa bea frontendu ho nesprístupní vnútri enginu. Konfigurácia, ktorá importuje ďalšie balíky, potrebuje tieto závislosti v engine; povolenie Beangulp samotné ich neinštaluje. Použite CSV mapper alebo konvertory nižšie, keď tieto závislosti importéra nie sú k dispozícii.

Pre výnimku importéra dajte --debug pred príkaz, aby sa zobrazil jeho traceback. Výstup importéra sa zachytáva v importer_output, aby nepoškodil JSON. V JSON režime ladenia je traceback error.traceback.

Pre jednorazovú konverziu bez Python importéra vyskúšajte CSV konvertor alebo OFX a QIF konvertor. Skontrolujte vygenerované položky pred ich pridaním do svojich účtovných kníh.