Importa exportacions bancàries amb la CLI

Utilitza bea import per previsualitzar una exportació bancària, revisar els duplicats i afegir les entrades validades al teu llibre major local.

Necessites un llibre major existent i un importador Python per al format exacte de l'exportació del teu banc. Si comences llibres nous, segueix la guia ràpida de la CLI. Conserva l'exportació bancària original per poder comparar-la amb la previsualització.

1. Tria un importador​

Un importador llegeix el fitxer del banc i proporciona els comptes de les transaccions. Bea no endevina el format ni categoritza les compres amb un model d'IA.

La teva configuració importers.py exporta CONFIG = [importer, ...]. Els importadors utilitzen la interfície actual de Beangulp: identify(filepath), account(filepath) i extract(filepath, existing). Els assentaments de comptes font necessiten imports explícits per a la coincidència de duplicats.

Per a una primera pràctica, desa la configuració CSV d'exemple com a importers.py al costat del teu llibre major arrel. Utilitza només la biblioteca estàndard de Beancount i de Python, de manera que funciona amb la instal·lació de Homebrew.

Desa aquesta mostra com a bank.csv al mateix directori:

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

La mostra utilitza un import de compte corrent signat: la despesa és negativa i un dipòsit és positiu. Category proporciona el compte. Ambdues categories són a la plantilla USD creada per bea init.

Utilitza un importador escrit per al teu banc quan importis el seu format natiu CSV, OFX o QIF. La configuració d'exemple espera exactament les columnes anteriors. Només executa configuracions Python de confiança.

2. Previsualitza les entrades​

Executa això des del directori que conté main.bean:

bea import bank.csv --config importers.py

Encara no s'escriu res al llibre major. Revisa les dates, els beneficiaris, els imports font signats, els comptes de destinació, les coincidències de duplicats i la diferència de fitxer proposada a la previsualització.

Per a la mostra, la previsualització hauria de contenir una despesa de restauració de 5,25 USD i un dipòsit de sou de 1.000 USD. Corregeix una categoria incorrecta a l'importador o a les dades font, i després previsualitza de nou. Obre qualsevol compte que falti abans d'aplicar la importació.

Si diversos importadors reconeixen el fitxer, selecciona'n un pel nom:

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

Un nom desconegut llista els noms configurats. Un importador conegut que no reconeix el fitxer ho informa per separat.

3. Aplica les entrades revisades​

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

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

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

4. Resol possibles duplicats​

Repetir la mateixa importació de mostra omet les seves entrades existents. Una exportació superposada també pot contenir files que necessiten una decisió:

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, beneficiari i import.

Després de revisar cada possible coincidència, tria una d'aquestes alternatives:

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

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

La decisió s'aplica a totes les possibles coincidències en aquesta invocació. Els duplicats exactes romanen omesos. Els conflictes d'ID encara bloquegen l'escriptura.

El valor per defecte --duplicates review rebutja aplicar coincidències no resoltes. Surt amb codi 4 i nomena les files de previsualització afectades. --no-input i --yes no eviten aquesta revisió. Una decisió intencionada d'ometre cada fila surt amb codi 0 sense afegir res al llibre major.

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 font de l'importador. Utilitza opcions --id-key KEY repetides per substituir aquest conjunt.

La CLI també escriu la metadada bea_import_id per identificar la fila a l'exportació original. Conserva-la quan editis les entrades. Les possibles coincidències es comproven contra transaccions existents i files acceptades al mateix lot.

Els beneficiaris, les narracions i les metadades de cadena substitueixen els salts de línia per espais abans de previsualitzar i escriure. Les cometes i les barres invertides conserven els seus continguts. Per tant, el text de mercaderia importat es manté llegible en una única línia del llibre major.

Importar afegeix entrades; no actualitza ni esborra cap transacció existent. Fes les correccions deliberadament al teu llibre major i executa bea check després. L'entrada JSON per lots amb bea add transactions no té detecció de duplicats.

Escriu a un fitxer inclòs​

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

Utilitza importacions en un script​

bea --json --no-input import bank.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 rebutjades posen la previsualització a error.result a stderr, amb written: 0. Comprova sempre l'estat de sortida. Consulta la referència de JSON i codis de sortida abans de programar importacions sense supervisió.

Resol problemes d'un importador​

Si la configuració importa paquets de tercers, aquests paquets han de ser a l'entorn Python que executa bea. Per exemple:

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

Afegeix --with YOUR_IMPORTER_PACKAGE per a un importador bancari instal·lat per separat. Això utilitza un entorn separat de Homebrew.

Per a una excepció d'importador, posa --debug abans de la comanda per mostrar la traça:

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

La sortida de l'importador es captura a importer_output perquè no corrompi el JSON. En mode de depuració JSON, la traça és error.traceback.

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