Import bankových výpisov pomocou CLI

Použite príkaz bea import na zobrazenie náhľadu bankového výpisu, kontrolu duplicitných položiek a aplikovanie overených zápisov do vášho lokálneho účtovníctva.

Potrebujete existujúce účtovníctvo a Python importer pre formát vášho bankového výpisu. Ak začínate s novými knihami, postupujte podľa rýchleho začiatku CLI. Uchovajte pôvodný bankový výpis, aby ste ho mohli porovnať s náhľadom.

1. Vyberte importer​

Importer číta súbor banky a dodáva účty transakcií. Bea neháda formát ani nekategorizuje nákupy pomocou modelu AI.

Vaša konfigurácia importers.py exportuje CONFIG = [importer, ...]. Importery používajú aktuálne Beangulp rozhranie: identify(filepath), account(filepath) a extract(filepath, existing). Účty transakcií potrebujú explicitné sumy na porovnanie duplicit.

Pre prvý skúšobný beh si uložte príklad konfigurácie CSV ako importers.py vedľa vášho koreňového účtovníctva. Používa iba Beancount a štandardnú knižnicu Pythonu, takže funguje s inštaláciou cez Homebrew.

Uložte tento vzor ako bank.csv v rovnakom adresári:

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

Vzor používa podpísanú sumu na účte: výdavky sú záporné a príjem kladný. Category dodáva účet. Obe kategórie sú v šablóne USD vytvorenej príkazom bea init.

Použite importer napísaný pre vašu banku pri importovaní jej natívneho CSV, OFX alebo QIF formátu. Vzor očakáva presne vyššie uvedené stĺpce. Spúšťajte iba Python konfigurácie, ktorým dôverujete.

2. Zobrazte náhľad​

Spustite tento príkaz z adresára obsahujúceho main.bean:

bea import bank.csv --config importers.py

Do účtovníctva sa zatiaľ nič nezapíše. Skontrolujte dátumy, príjemcov, podpísané sumy, cieľové účty, duplicitné položky a navrhovaný rozdiel v súbore.

Pre vzor by náhľad mal obsahovať výdavok 5,25 USD na stravovanie a príjem 1 000 USD ako mzdu. Opravte nesprávnu kategóriu v importeri alebo zdrojových dátach a znova zobrazte náhľad. Otvorte chýbajúce účty pred aplikovaním importu.

Ak súbor rozpozná viacero importerov, vyberte jeden podľa názvu:

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

Neznámy názov vypíše zoznam dostupných importerov. Známy importer, ktorý súbor nerozpozná, to oznámi samostatne.

3. Aplikujte overené zápisy​

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

CLI si pamätá cestu ku konfigurácii pre toto koreňové účtovníctvo. Budúce spustenia použijú explicitný --config, potom zapamätanú cestu a nakoniec importers.py vedľa koreňa. Výstup uvádza cestu a jej pôvod.

Príkaz --apply prepočíta náhľad proti aktuálnym súborom. Overí celé kandidátske účtovníctvo pred zápisom. Ak overenie zlyhá, pôvodné účtovníctvo sa nezmení a proces skončí s kódom 1. Ak dôjde k súbežnej zmene účtovníctva, skončí s kódom 4; skontrolujte zmenu a spustite nový náhľad pred opätovným pokusom.

4. Vyriešte možné duplicity​

Opakovaný import rovnakého vzoru preskočí jeho existujúce položky. Prekrývajúci sa export môže obsahovať riadky vyžadujúce rozhodnutie:

Rozdielne bankové ID nevylučuje duplicitu. Banky môžu zmeniť ID pri neskorších stiahnutiach. Dve skutočné transakcie môžu mať rovnaký dátum, príjemcu a sumu.

Po preskúmaní každej možnej duplicity vyberte jednu z týchto možností:

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

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

Rozhodnutie sa vzťahuje na všetky možné duplicity v tomto spustení. Presné duplicity zostanú preskočené. Konflikty ID stále zablokujú zápis.

Predvolený režim --duplicates review odmietne aplikovať nevyriešené zhody. Proces skončí s kódom 4 a vypíše dotknuté riadky náhľadu. Prepínače --no-input a --yes neobchádzajú toto preskúmanie. Zámerné rozhodnutie preskočiť každý riadok skončí s kódom 0 a bez zápisu do účtovníctva.

Zabezpečte opakovateľnosť importov​

Predvolene kontrola duplicit porovnáva metadátové polia bank_id, fitid, transaction_id a imported_id v rámci účtu zdrojového importera. Prepínačom --id-key KEY môžete nahradiť túto množinu polí.

CLI tiež zapisuje metadátové pole bea_import_id na identifikáciu riadku v pôvodnom exporte. Zachovajte ho pri úprave zápisov. Možné duplicity sa porovnávajú s existujúcimi transakciami a prijatými riadkami v tej istej dávke.

Príjemcovia, popisy a reťazcové metadáta nahrádzajú konce riadkov medzerami pred náhľadom aj zápisom. Úvodzovky a spätné lomítka si zachovávajú svoj význam. Importovaný text obchodníka tak zostane čitateľný na jednom riadku účtovníctva.

Import pridáva zápisy; neupravuje ani nemaže existujúce transakcie. Vykonávajte opravy zámerne vo svojom účtovníctve a potom spustite bea check. Dávkový JSON import pomocou bea add transactions nemá detekciu duplicit.

Zápis do zahrnutého súboru​

Nechajte --file ukazovať na koreňové účtovníctvo a vyberte cieľový súbor pomocou --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

Súbor 2026.bean musí už existovať a byť zahrnutý v koreňovom účtovníctve. Jeho cesta je relatívna ku koreňovému adresáru. Cesta exportu zostáva relatívna k vášmu pracovnému adresáru. Náhľad identifikuje súbor, ktorý sa zmení.

Použitie v skriptoch​

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

Použite skip iba ak je to vaša zámerná politika pre možné duplicity. JSON režim vracia náhľad a počet zápisov v poli data. Zamietnuté aplikácie umiestnia náhľad do poľa error.result na štandardný chybový výstup, s hodnotou written: 0. Vždy kontrolujte výstupný kód. Pozrite si referenciu JSON a výstupných kódov pred plánovaním neobsluhovaných importov.

Riešenie problémov s importerom​

Ak konfigurácia importuje balíky tretích strán, tieto balíky musia byť v prostredí Pythonu, v ktorom beží bea. Napríklad:

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

Pridajte --with YOUR_IMPORTER_PACKAGE pre samostatne nainštalovaný bankový importer. Toto používa oddelené prostredie od inštalácie cez Homebrew.

Ak dôjde k výnimke importera, použite --debug pred príkazom na zobrazenie tracebacku:

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

Výstup importera sa zachytáva do poľa importer_output, aby nepoškodil JSON. V JSON režime ladenia je traceback v poli error.traceback.

Pre jednorazovú konverziu bez Python importera vyskúšajte CSV prevodník alebo OFX a QIF prevodník. Pred pridaním do svojich kníh skontrolujte vygenerované zápisy.