Plugin Nativi Essenziali di Beancount che Dovresti Conoscere

La potenza di Beancount risiede non solo nel suo formato in testo semplice, ma nella sua estensibilità tramite plugin. I plugin nativi sono moduli integrati che migliorano le funzionalità di Beancount, automatizzano attività noiose e impongono le migliori pratiche contabili. In questa guida completa, esploreremo tutti i plugin nativi disponibili in Beancount e come usarli efficacemente.

Cosa Sono i Plugin di Beancount?​

I plugin di Beancount sono moduli Python che elaborano le voci del tuo registro per aggiungere automazione, validazione o capacità di trasformazione. Vengono eseguiti durante la fase di caricamento del file del registro e possono:

• Automatizzare attività ripetitive (es. creare dichiarazioni di conti)
• Validare l'integrità dei dati (es. controllare la presenza di transazioni duplicate)
• Trasformare voci (es. generare voci di prezzo dalle transazioni)
• Imporre regole contabili (es. una merce per conto)

Come Usare i Plugin​

Per abilitare un plugin nel tuo file Beancount, aggiungi una direttiva plugin all'inizio del tuo registro:

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"

Alcuni plugin accettano opzioni di configurazione:

plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"

Categorie di Plugin Nativi​

I plugin nativi di Beancount rientrano in quattro categorie principali:

1. Plugin di Automazione​

2. Plugin di Validazione​

3. Plugin di Trasformazione​

4. Meta-Plugin​

1. Plugin di Automazione​

Questi plugin automatizzano attività contabili ripetitive, facendoti risparmiare tempo e riducendo gli errori manuali.

auto_accounts - Dichiarazioni Automatiche dei Conti​

Cosa fa: Inserisce automaticamente le direttive Open per i conti che compaiono nelle transazioni ma non sono stati dichiarati esplicitamente.

Perché usarlo: Elimina la necessità di dichiarare manualmente ogni conto prima di usarlo. Perfetto per iniziare rapidamente o per utenti che preferiscono codice boilerplate minimo.

Esempio:

plugin "beancount.plugins.auto_accounts"
 
2026-01-01 * "Caffetteria"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

Senza il plugin, dovresti aggiungere manualmente:

2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash

Quando usarlo: Ideale per principianti o per chi desidera un registro meno verboso. Tuttavia, le dichiarazioni esplicite dei conti possono aiutare a individuare errori di battitura.

close_tree - Chiusura Automatica della Gerarchia dei Conti​

Cosa fa: Quando chiudi un conto padre, questo plugin chiude automaticamente tutti i suoi conti discendenti.

Perché usarlo: Mantiene la coerenza nella tua gerarchia di conti. Se chiudi Assets:Investments, tutti i sottoconti come Assets:Investments:Stocks e Assets:Investments:Bonds verranno chiusi automaticamente.

Esempio:

plugin "beancount.plugins.close_tree"
 
2025-06-30 close Assets:Investments
 
; Questi verranno chiusi automaticamente:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

Quando usarlo: Quando ristrutturi la tua gerarchia di conti o chiudi intere categorie di conti.

implicit_prices - Generazione Automatica di Voci di Prezzo​

Cosa fa: Sintetizza le direttive Price dalle registrazioni di transazioni che includono costi (@) o prezzi (@@).

Perché usarlo: Popola automaticamente il tuo database dei prezzi dalle tue transazioni, consentendo un reporting accurato del valore di mercato senza voci di prezzo manuali.

Esempio:

plugin "beancount.plugins.implicit_prices"
 
2026-01-02 * "Acquisto azioni AAPL"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

Questo genera automaticamente:

2026-01-02 price AAPL  150.00 USD

Quando usarlo: Essenziale per il monitoraggio degli investimenti e la contabilità multivaluta in cui desideri una cronologia automatica dei prezzi.

2. Plugin di Validazione​

Questi plugin impongono l'integrità dei dati e le migliori pratiche contabili, rilevando gli errori prima che diventino problemi.

noduplicates - Rilevamento Transazioni Duplicate​

Cosa fa: Verifica che non ci siano due transazioni identiche calcolando e confrontando gli hash dei dati della transazione.

Perché usarlo: Previene voci duplicate accidentali, specialmente quando si importano transazioni da più fonti.

Esempio:

plugin "beancount.plugins.noduplicates"
 
2026-01-02 * "Pagamento affitto"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD
 
; Questo attiverebbe un errore:
2026-01-02 * "Pagamento affitto"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

Quando usarlo: Sempre consigliato, specialmente se stai importando da estratti conto bancari o utilizzando più fonti di dati.

check_commodity - Validazione Dichiarazione delle Merci​

Cosa fa: Assicura che tutte le merci utilizzate nel tuo registro abbiano corrispondenti direttive Commodity.

Perché usarlo: Impone dichiarazioni esplicite delle merci, aiutandoti a mantenere un elenco pulito di attività e valute.

Esempio:

plugin "beancount.plugins.check_commodity"
 
2015-01-01 commodity USD
2020-01-01 commodity AAPL
 
; Questo attiverebbe un errore senza una dichiarazione della merce:
2026-01-02 * "Acquisto Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

Quando usarlo: Consigliato per mantenere un monitoraggio rigoroso delle merci e prevenire errori di battitura nei simboli ticker.

check_average_cost - Validazione della Base di Costo​

Cosa fa: Verifica che la base di costo sia correttamente preservata nelle transazioni, specialmente quando si utilizza la contabilità a costo medio.

Perché usarlo: Assicura che la tua contabilità dei costi rimanga accurata per la dichiarazione fiscale e i calcoli delle plusvalenze.

Quando usarlo: Fondamentale per i portafogli di investimento e qualsiasi scenario in cui sia importante un monitoraggio accurato dei costi.

check_closing - Validazione della Chiusura del Saldo​

Cosa fa: Espande i metadati closing in controlli di saldo, assicurando che le posizioni siano a zero dopo le operazioni di chiusura.

Perché usarlo: Conferma che quando vendi un'intera posizione, il saldo sia effettivamente zero (nessuna frazione di azioni rimanente).

Esempio:

plugin "beancount.plugins.check_closing"
 
2026-01-02 * "Chiusura posizione AAPL completa" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15000.00 USD
  Income:Investments:Gains   -500.00 USD

Il tag #closing dice al plugin di verificare che la tua posizione AAPL sia zero dopo questa transazione.

Quando usarlo: Quando vendi intere posizioni per assicurarti che non rimanga nulla.

coherent_cost - Controllo di Coerenza Valuta/Costo​

Cosa fa: Convalida che le valute non siano utilizzate in modo incoerente — sia con che senza annotazioni di costo.

Perché usarlo: Previene la mescolanza di valute semplici (come 100 USD) con valute con costo (come 100 USD {1.2 CAD}), che può causare errori contabili.

Quando usarlo: Consigliato per registri multivaluta per mantenere la coerenza.

leafonly - Imposizione dei Conti Foglia​

Cosa fa: Assicura che solo i conti foglia (conti senza figli) ricevano registrazioni.

Perché usarlo: Impone una gerarchia di conti pulita in cui i conti di riepilogo come Expenses:Food non hanno registrazioni dirette, ma solo i loro figli come Expenses:Food:Groceries e Expenses:Food:Restaurants.

Esempio:

plugin "beancount.plugins.leafonly"
 
; Questo attiverebbe un errore:
2026-01-02 * "Spesa al supermercato"
  Expenses:Food              50.00 USD  ; Errore: Dovrebbe registrare su un conto foglia
  Assets:Cash               -50.00 USD
 
; Modo corretto:
2026-01-02 * "Spesa al supermercato"
  Expenses:Food:Groceries    50.00 USD  ; Corretto: Registrazione su conto foglia
  Assets:Cash               -50.00 USD

Quando usarlo: Quando desideri mantenere una contabilità gerarchica rigorosa con una chiara categorizzazione.

nounused - Rilevamento Conti Non Utilizzati​

Cosa fa: Identifica i conti che sono stati aperti ma mai effettivamente utilizzati in alcuna transazione.

Perché usarlo: Ti aiuta a pulire le dichiarazioni dei tuoi conti e identificare potenziali errori di battitura o conti abbandonati.

Quando usarlo: Periodicamente, per verificare e pulire la struttura dei tuoi conti.

onecommodity - Singola Merce per Conto​

Cosa fa: Impone che ogni conto contenga un solo tipo di merce.

Perché usarlo: Previene la mescolanza di diverse attività nello stesso conto, che è generalmente una buona pratica contabile.

Esempio:

plugin "beancount.plugins.onecommodity"
 
2026-01-02 * "Acquisto azioni"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD
 
; Questo attiverebbe un errore:
2026-01-03 * "Acquisto altre azioni"
  Assets:Investments         5 GOOGL @ 140 USD  ; Errore: Merce diversa
  Assets:Cash              -700.00 USD

Quando usarlo: Quando preferisci una separazione rigorosa dei conti (un conto per azione/attività).

sellgains - Validazione delle Plusvalenze​

Cosa fa: Controlla in modo incrociato le plusvalenze dichiarate rispetto alle plusvalenze calcolate dalle vendite di lotti, assicurando che i calcoli di profitto/perdita siano accurati.

Perché usarlo: Rileva errori nei calcoli manuali delle plusvalenze, fondamentale per una dichiarazione fiscale accurata.

Esempio:

plugin "beancount.plugins.sellgains"
 
2026-01-02 * "Vendita azioni AAPL"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; Il plugin convalida che questo sia corretto

Il plugin verificherà: Provento della vendita (1500) - Base di costo (1400) = Plusvalenze (100)

Quando usarlo: Essenziale per chiunque faccia trading di azioni, criptovalute o altri asset in cui le plusvalenze sono importanti.

unique_prices - Controllo Unicità Prezzo​

Cosa fa: Assicura che ci sia una sola voce di prezzo per merce per data.

Perché usarlo: Previene dati di prezzo in conflitto che potrebbero portare a valutazioni errate.

Quando usarlo: Consigliato quando si inseriscono manualmente i prezzi o si importano da più fonti di prezzo.

3. Plugin di Trasformazione​

Questi plugin modificano o migliorano i dati del tuo registro in modi utili.

currency_accounts - Conti per Trading di Valute​

Cosa fa: Implementa conti per il trading di valute per tracciare esplicitamente le conversioni forex.

Perché usarlo: Fornisce un monitoraggio dettagliato delle transazioni di conversione valutaria, utile per gli standard contabili che lo richiedono.

Quando usarlo: Quando hai bisogno di tracciare separatamente le plusvalenze/perdite forex o soddisfare specifici requisiti contabili.

commodity_attr - Validazione Attributi Merce​

Cosa fa: Convalida che le direttive sulle merci abbiano gli attributi richiesti (come export, name, ecc.).

Perché usarlo: Assicura che i metadati delle tue merci siano completi e coerenti.

Quando usarlo: Quando mantieni metadati dettagliati sulle merci per scopi di reporting o esportazione.

4. Meta-Plugin​

Questi plugin sono raccolte di altri plugin per comodità.

auto - Tutti i Plugin Automatici​

Cosa fa: Abilita una raccolta di plugin "rilassati" o automatici in un'unica direttiva.

Quando usarlo: Configurazione rapida per utenti che desiderano la massima automazione con una configurazione minima.

pedantic - Tutti i Plugin di Validazione​

Cosa fa: Abilita tutti i plugin di validazione rigorosa in una volta sola.

Perché usarlo: Impone la massima integrità dei dati e rigore contabile. Ottimo per registri di produzione o quando l'accuratezza è fondamentale.

Esempio:

plugin "beancount.plugins.pedantic"
 
; Questo è equivalente ad abilitare:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

Quando usarlo: Per registri di produzione in cui desideri la massima validazione e sei disposto a mantenere pratiche contabili più rigorose.

Configurazioni Consigliate dei Plugin​

Per Principianti​

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"

Questo set minimo fornisce automazione prevenendo errori comuni.

Per Investitori​

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_average_cost"
plugin "beancount.plugins.unique_prices"

Si concentra sul monitoraggio degli investimenti e l'accuratezza delle plusvalenze.

Per Contabilità Rigorosa​

plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"

Massima validazione per ambienti di produzione.

Configurazione Predefinita su Beancount.io​

Su Beancount.io, includiamo il plugin auto_accounts per impostazione predefinita in tutti i nuovi file di registro:

plugin "beancount.plugins.auto_accounts"

Questo fornisce un ottimo equilibrio tra facilità d'uso e funzionalità per iniziare rapidamente.

Migliori Pratiche​

1. Inizia in modo minimo, aggiungi secondo necessità: Inizia con auto_accounts e noduplicates, poi aggiungi plugin di validazione man mano che il tuo registro matura.

2. Testa i plugin individualmente: Quando aggiungi più plugin, abilitali uno alla volta per comprenderne gli effetti.

3. Leggi attentamente i messaggi di errore: Gli errori dei plugin spesso indicano problemi contabili reali che devono essere risolti.

4. Usa pedantic per la produzione: Una volta stabilito il tuo flusso di lavoro, considera di abilitare la validazione rigorosa.

5. Combina con plugin personalizzati: I plugin nativi funzionano insieme a plugin personalizzati come il plugin forecast per la massima funzionalità.

Oltre i Plugin Nativi​

Mentre i plugin nativi forniscono funzionalità di base, l'ecosistema Beancount include molti plugin sviluppati dalla comunità per esigenze specializzate:

• fava.plugins.forecast - Per la previsione di transazioni ricorrenti
• fava.plugins.link_documents - Per collegare transazioni a file di ricevute
• Importatori personalizzati per formati CSV specifici della banca
• Calcolatori e report fiscali specifici

Esplora l'ecosistema Beancount per ulteriori opzioni.

Conclusione​

I plugin nativi di Beancount trasformano la contabilità in testo semplice da un processo manuale in un sistema di gestione finanziaria automatizzato, validato e robusto. Comprendendo e sfruttando questi strumenti integrati, puoi:

• ✅ Automatizzare noiose attività contabili
• ✅ Rilevare errori prima che diventino problemi
• ✅ Mantenere una rigorosa integrità dei dati
• ✅ Generare report finanziari accurati
• ✅ Concentrarti sugli approfondimenti finanziari piuttosto che sull'immissione di dati

Inizia a sperimentare con questi plugin nel tuo registro oggi. Inizia con auto_accounts e implicit_prices, poi aggiungi gradualmente plugin di validazione man mano che le tue pratiche contabili maturano.

Pronto a provare questi plugin? Vai su Beancount.io e inizia a usarli nel tuo file di registro oggi!

Fonti​

• Riferimento API Plugin Beancount
• Guida alla Scrittura di Script e Plugin Beancount
• Plugin e Opzioni Beancount di Bryan Alves
• Repository GitHub di Beancount

Hai domande sui plugin di Beancount? Unisciti alla discussione sul nostro forum della comunità o consulta la nostra documentazione.

Esplora un registro di esempio di criptovaluta dal vivo: