Importa un CSV bancari a Beancount amb bea

Un CSV bancari normal no necessita cap importador de Python. Mapa les seves columnes amb --csv, anomena el compte d'origen amb --account, categoritza les files amb --rules, i després previsualitza i aplica les entrades amb bea import.

Necessites un llibre existent. Si comences llibres nous, segueix la guia d'inici ràpid de la CLI. Conserva l'exportació bancària original per poder comparar-la amb la previsualització.

1. Mapa les columnes del CSV​

Desa aquesta mostra com a statement.csv, i després executa les ordres següents des del mateix directori:

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

Els imports utilitzen la convenció de signe del banc: la despesa és negativa i un dipòsit és positiu. La moneda per defecte és la moneda operativa del llibre, per tant aquest fitxer no necessita cap columna de moneda. Posa una columna de descripció del banc a narration i mantén payee per al comerciant.

Crea el llibre i obre el subcompte de combustible utilitzat més avall:

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

La plantilla ja obre Expenses:Groceries i els altres comptes habituals. No obre Expenses:Transport:Fuel, per tant la segona ordre l'obre abans de la importació. Les opcions globals com ara --file van abans del subcomandament.

2. Previsualitza les entrades​

Desa aquestes regles de categorització com a rules.toml, i després previsualitza:

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

Les regles coincideixen primer amb el payee, després amb la narració, ignorant les majúscules. La primera regla que coincideix guanya. Les files que cap regla no coincideix es registren a Expenses:Uncategorized amb la marca ! per a revisió posterior. La guia IMPORTING documenta la referència completa de mapatge, incloent-hi el parell debit i credit, la columna category, i la lectura de capçaleres amb --csv auto.

Encara no s'escriu res al llibre. La previsualització informa 3 ready, 0 exact duplicates, 0 possible duplicates i surt amb 0. La seva columna RULE anomena el patró guanyador per fila, o unmatched per a la fila Unknown Shop. Revisa les dates, els payees, els imports d'origen amb signe, els comptes de destinació, les coincidències duplicades i el diff de fitxer proposat. Corregeix una regla o categoria incorrecta, i torna a previsualitzar. Obre qualsevol compte que falti abans d'aplicar la importació: una regla que anomena un compte que el llibre no obre falla la validació.

3. Aplica les entrades revisades​

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"

El mapatge de columnes es recorda per llibre, fila de capçalera i compte d'origen, per tant --apply es torna a executar sense marques i informa utilitzant el mapatge de columnes recordat. Recalcula la previsualització contra els fitxers actuals, valida el llibre candidat complet abans d'escriure, i escriu 3 entrades. bea check informa cap error. La cua ! llista la única fila no coincident: Unknown Shop amb mystery a -9.99 USD. Una comprovació que passa només prova que el llibre equilibra i valida. No diu res sobre si aquesta fila pertany a Expenses:Uncategorized, per tant recategoritza-la deliberadament al teu llibre. La comprovació acaba a 930.01 USD: el saldo inicial de 1,000 USD menys la despesa de 69.99 USD.

4. Les importacions repetides no afegeixen res​

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

La previsualització informa 0 ready, 3 exact duplicates, i l'execució escriu 0 entrades amb sortida 0. Cada fila escrita porta metadades import-id amb un hash de contingut, per tant el fitxer idèntic coincideix amb cada fila. Conserva aquestes metadades quan editis entrades importades. La importació afegeix entrades; no actualitza ni suprimeix una transacció existent. Fes correccions deliberadament al teu llibre i executa bea check després. La importació massiva de JSON amb bea add transactions no té detecció de duplicats.

5. Resol possibles duplicats​

Una descàrrega posterior pot repetir una fila amb narració o IDs bancaris diferents. La data, el payee normalitzat i l'import d'origen amb signe encara la marquen com a possible coincidència:

Un ID bancari diferent no descarta un duplicat. Els bancs poden canviar els IDs en descàrregues posteriors. Dues compres reals també poden compartir data, payee i import, per tant una possible coincidència és evidència i no prova. Bea no endevina amb un model d'IA i mai categoritza per tu més enllà de les teves regles.

El --duplicates review per defecte es nega a aplicar coincidències no resoltes. En una execució de verificació, un segon fitxer que repeteix la fila 2026-08-02 Whole Foods -20.00 USD sota una narració diferent es previsualitzava com 1 possible duplicat, i --apply va sortir amb 4 sense escriure res. Després de revisar cada possible coincidència, tria una d'aquestes alternatives:

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

Tria include per preservar compres repetides legítimes. La decisió s'aplica a totes les possibles coincidències en aquesta invocació. Els duplicats exactes continuen sent saltats. Els conflictes d'ID encara bloquegen l'escriptura. --no-input i --yes no eviten aquesta revisió. Una decisió intencionada de saltar cada fila surt amb 0 sense addicions al llibre.

6. Utilitza un importador de Python per a altres formats​

Per a formats que el mapatge de columnes no pot expressar, com ara OFX o QIF o un CSV amb una disposició inusual, bea import crida un importador configurat utilitzant la interfície actual de Beangulp: identify(filepath), account(filepath) i extract(filepath, existing). L'importador és responsable de l'anàlisi i la categorització específics del banc. Ha de proporcionar imports explícits als registres del compte d'origen perquè la coincidència de duplicats utilitzi els imports reals del banc. Un importador de Python continua sent el camí avançat per a aquests formats. Per a un CSV natiu del banc, prova primer --csv.

Per a una primera pràctica, desa la configuració d'exemple de CSV categoritzat com a importers.py al costat del teu llibre arrel. Utilitza només Beancount i la biblioteca estàndard de Python, per tant funciona amb la instal·lació de Homebrew. El seu bank.csv d'exemple utilitza un import signat del compte corrent: una despesa de dinar de -5.25 USD i un dipòsit de salari de 1,000 USD. La configuració d'exemple espera exactament les seves columnes documentades. Només executa configuracions de Python que confiïs.

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

La teva configuració importers.py exporta CONFIG = [importer, ...]. Si diversos importadors reconeixen el fitxer, selecciona'n un per nom. Un nom desconegut llista els noms configurats. Un importador conegut que no reconeix el fitxer ho informa per separat.

La CLI recorda el camí de configuració per a aquest llibre arrel. Les execucions futures trien el --config explícit, després el camí recordat, després importers.py al costat de l'arrel. La sortida anomena el camí i d'on prové.

--apply recalcula la previsualització contra els fitxers actuals. Valida el llibre candidat complet abans d'escriure. Un fallada de validació deixa el llibre original sense canvis i surt amb 1. Un canvi concurrent al llibre surt amb 4; inspecciona el canvi i executa una previsualització nova abans de tornar a provar.

Mantén les importacions repetibles​

Per defecte, la coincidència de duplicats comprova les metadades bank_id, fitid, transaction_id i imported_id dins del compte d'origen de l'importador. Utilitza opcions repetides --id-key KEY per substituir aquest conjunt.

Una fila amb un ID bancari estable s'escriu amb metadades import-id que anomenen el seu tipus, com ara un prefix bank: o ofx:. Una fila sense un ID s'escriu amb un hash de contingut csv:sha256: sobre la seva data, import, descripció i compte, per tant re-importar el mateix fitxer salta cada fila. Les entrades escrites abans d'aquesta convenció poden portar encara metadades bea_import_id, i aquestes continuen coincidint en la re-importació. Les possibles coincidències es comproven contra les transaccions existents i les files acceptades al mateix lot.

Els payees, les narracions i les metadades de cadena substitueixen els salts de línia amb espais abans de previsualitzar i escriure. Les cometes i les barres invertides mantenen el seu contingut. Per tant, el text del comerciant importat es manté llegible en una sola línia del llibre.

Escriu a un fitxer inclòs​

Mantén --file apuntant a l'arrel i selecciona la destinació amb --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 ja ha d'existir i estar inclòs per l'arrel. El seu camí és relatiu al directori arrel. El camí d'exportació continua sent relatiu al teu directori de treball. La previsualització identifica el fitxer que canviarà.

Utilitza importacions en un script​

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

Tria skip només quan aquesta sigui la teva política intencionada per a possibles coincidències. JSON retorna la previsualització i el recompte d'escriptures dins de data. Les aplicacions refusades posen la previsualització a error.result a stderr, amb written: 0. Sempre comprova l'estat de sortida. Consulta la referència de JSON i codis de sortida abans de programar importacions no supervisades.

Resol un importador​

Les configuracions d'importador s'executen al motor gestionat. Si una configuració importa Beangulp, instal·la la biblioteca del sistema libmagic i habilita Beangulp allà una vegada:

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 informa les funcionalitats habilitades. Instal·lar un importador de banc al costat del frontend bea no el fa disponible dins del motor. Una configuració que importa paquets addicionals necessita aquestes dependències al motor; habilitar només Beangulp no les instal·la. Utilitza el mapador de CSV o els convertidors següents quan aquestes dependències d'importador no estiguin disponibles.

Per a una excepció d'importador, posa --debug abans de l'ordre per mostrar el seu traceback. La sortida de l'importador es captura a importer_output perquè no corrompi JSON. En mode de depuració JSON, el traceback és error.traceback.

Per a una conversió puntual sense un importador de Python, prova el convertidor de CSV o el convertidor d'OFX i QIF. Revisa les entrades generades abans d'afegir-les als teus llibres.