Importa esportazioni bancarie con la CLI

Usa bea import per visualizzare in anteprima un'esportazione bancaria, esaminare i duplicati e aggiungere le voci validate al tuo registro locale.

Ti servono un registro esistente e un importatore Python per il formato di esportazione esatto della tua banca. Se stai iniziando una nuova contabilità, segui la Guida rapida CLI. Conserva l'esportazione bancaria originale così puoi confrontarla con l'anteprima.

1. Scegli un importatore​

Un importatore legge il file della banca e fornisce i conti delle transazioni. Bea non indovina il formato né categorizza gli acquisti con un modello di intelligenza artificiale.

La configurazione importers.py esporta CONFIG = [importer, ...]. Gli importatori usano l'interfaccia Beangulp corrente: identify(filepath), account(filepath), e extract(filepath, existing). Le registrazioni del conto sorgente necessitano di importi espliciti per il confronto dei duplicati.

Per una prima prova pratica, salva la configurazione CSV categorizzata di esempio come importers.py accanto al tuo registro principale. Usa solo Beancount e la libreria standard di Python, quindi funziona con l'installazione Homebrew.

Salva questo esempio come bank.csv nella stessa directory:

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

L'esempio usa un importo firmato del conto corrente: la spesa è negativa e il deposito è positivo. Category fornisce l'altro conto. Entrambe le categorie sono nel template USD creato da bea init.

Usa un importatore scritto per la tua banca quando importi il suo CSV, OFX o QIF nativo. La configurazione di esempio prevede esattamente le colonne sopra. Esegui solo configurazioni Python di cui ti fidi.

2. Anteprima delle voci​

Esegui questo comando dalla directory che contiene main.bean:

bea import bank.csv --config importers.py

Nulla viene ancora scritto nel registro. Esamina le date, i beneficiari, gli importi sorgente firmati, i conti di destinazione, le corrispondenze duplicate e la diff del file proposta nell'anteprima.

Per l'esempio, l'anteprima dovrebbe contenere una spesa per pasti di 5,25 USD e un deposito stipendio di 1.000 USD. Correggi una categoria errata nell'importatore o nei dati sorgente, quindi ripeti l'anteprima. Apri eventuali conti mancanti prima di applicare l'importazione.

Se più importatori riconoscono il file, selezionane uno per nome:

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

Un nome sconosciuto elenca i nomi configurati. Un importatore noto che non riconosce il file lo segnala separatamente.

3. Applica le voci esaminate​

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

La CLI ricorda il percorso di configurazione per questo registro principale. Le esecuzioni future scelgono il --config esplicito, poi il percorso ricordato, poi importers.py accanto al registro principale. L'output indica il percorso e la sua origine.

--apply ricalcola l'anteprima sui file correnti. Valida l'intero registro candidato prima di scrivere. Un errore di validazione lascia il registro originale invariato ed esce con codice 1. Una modifica concorrente del registro esce con codice 4; esamina la modifica e fai una nuova anteprima prima di riprovare.

4. Risolvi possibili duplicati​

Ripetendo la stessa importazione di esempio si saltano le sue voci esistenti. Un'esportazione sovrapposta può anche contenere righe che richiedono una decisione:

Un ID bancario diverso non esclude un duplicato. Le banche possono cambiare gli ID nei download successivi. Anche due acquisti reali possono condividere data, beneficiario e importo.

Dopo aver esaminato ogni possibile corrispondenza, scegli una di queste alternative:

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

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

La decisione si applica a tutte le corrispondenze possibili in quella invocazione. I duplicati esatti rimangono saltati. I conflitti di ID bloccano comunque la scrittura.

Il default --duplicates review rifiuta di applicare corrispondenze non risolte. Esce con codice 4 e nomina le righe di anteprima interessate. --no-input e --yes non aggirano quella revisione. Una decisione intenzionale di saltare ogni riga esce con codice 0 senza aggiunte al registro.

Mantieni le importazioni ripetibili​

Per impostazione predefinita, la corrispondenza duplicati controlla i metadati bank_id, fitid, transaction_id e imported_id nel conto sorgente dell'importatore. Usa opzioni ripetute --id-key KEY per sostituire quel set.

La CLI scrive anche i metadati bea_import_id per identificare la riga nell'esportazione originale. Conservali quando modifichi voci importate. Le corrispondenze possibili vengono controllate rispetto alle transazioni esistenti e alle righe accettate nello stesso batch.

I beneficiari, le narrazioni e i metadati stringa sostituiscono i ritorni a capo con spazi prima dell'anteprima e della scrittura. Virgolette e backslash mantengono il loro contenuto. Il testo del commerciante importato resta quindi leggibile su una singola riga di registro.

L'importazione aggiunge voci; non aggiorna né elimina una transazione esistente. Apporta correzioni deliberatamente nel tuo registro ed esegui bea check dopo. L'inserimento JSON in blocco con bea add transactions non ha rilevamento duplicati.

Scrivi in un file incluso​

Tieni --file puntato al registro principale e seleziona la destinazione con --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 deve già esistere ed essere incluso dal registro principale. Il suo percorso è relativo alla directory principale. Il percorso di esportazione rimane relativo alla tua directory di lavoro. L'anteprima identifica il file che verrà modificato.

Usa le importazioni in uno script​

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

Scegli skip solo quando è la tua politica intenzionale per corrispondenze possibili. JSON restituisce l'anteprima e il conteggio delle scritture dentro data. Le applicazioni rifiutate inseriscono l'anteprima in error.result su stderr, con written: 0. Controlla sempre lo stato di uscita. Vedi il riferimento JSON e codici di uscita prima di programmare importazioni non presidiate.

Risolvi problemi con un importatore​

Se la configurazione importa pacchetti di terze parti, questi pacchetti devono essere nell'ambiente Python che esegue bea. Per esempio:

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

Aggiungi --with YOUR_IMPORTER_PACKAGE per un importatore bancario installato separatamente. Questo usa un ambiente separato da Homebrew.

Per un'eccezione dell'importatore, metti --debug prima del comando per mostrare il traceback:

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

L'output dell'importatore viene catturato in importer_output così non corrompe JSON. In modalità debug JSON, il traceback è error.traceback.

Per una conversione una tantum senza importatore Python, prova il convertitore CSV o il convertitore OFX e QIF. Esamina le voci generate prima di aggiungerle ai tuoi libri.