Guida Completa alla Gestione dei Conti in Beancount e Fava

Il tuo piano dei conti è la spina dorsale del tuo registro Beancount. Una gerarchia di conti ben progettata rende ogni report più chiaro, ogni query più veloce e ogni stagione fiscale meno dolorosa. In questa guida, esamineremo tutto ciò che devi sapere sulla creazione, lettura, aggiornamento e chiusura dei conti in Beancount e Fava, dai fondamenti per principianti ai modelli avanzati.

I Cinque Tipi di Conto​

Beancount utilizza il modello standard di contabilità a partita doppia con esattamente cinque tipi di conto radice:

L'equazione contabile fondamentale vale sempre:

Attività + Spese + Patrimonio Netto + Reddito + Passività = 0

Un'euristica utile: se gli importi sono rilevanti solo per un periodo di tempo (es. "Quanto ho speso per il cibo questo mese?"), usa Reddito o Spese. Se rappresentano un saldo in corso (es. "Quanto c'è nel mio conto corrente?"), usa Attività o Passività.

Convenzioni di Denominazione dei Conti​

I nomi dei conti in Beancount sono identificatori gerarchici separati da due punti. Le regole sono:

• Devono iniziare con uno dei cinque tipi radice: Assets, Liabilities, Equity, Income, Expenses
• Ogni componente inizia con una lettera maiuscola o un numero
• I componenti possono contenere lettere, numeri e trattini (nessuno spazio o trattino basso)
• Sono richiesti almeno due componenti (es. Expenses:Food, non solo Expenses)
• I due punti (:) separano i livelli gerarchici

; Nomi di conto validi
Assets:US:BofA:Checking
Liabilities:CA:RBC:CreditCard
Equity:Retained-Earnings
Income:US:Acme:Salary
Expenses:Food:Groceries
Assets:Crypto:BTC-Holdings
 
; Nomi di conto non validi
assets:checking          ; tipo radice in minuscolo
Assets:my checking       ; spazi non consentiti
Expenses                 ; solo un componente

Il modello di denominazione raccomandato per i conti dello stato patrimoniale è:

Tipo : Paese : Istituto : Conto : Sottoconto

Ad esempio: Assets:US:Vanguard:401k:VTSAX o Liabilities:US:Chase:Sapphire.

Per conti di spesa e reddito, utilizza invece una denominazione basata sulla categoria:

Expenses:Food:Groceries
Expenses:Housing:Utilities:Electric
Income:US:Employer:Salary

Personalizzare i Nomi delle Radici​

Puoi rinominare i cinque tipi radice per localizzazione o preferenza personale:

option "name_assets"       "Actifs"
option "name_liabilities"  "Passifs"
option "name_equity"       "Capital"
option "name_income"       "Revenus"
option "name_expenses"     "Depenses"

Creazione dei Conti (Direttiva Open)​

Ogni conto deve essere dichiarato con una direttiva open prima di poter registrare transazioni su di esso. La sintassi completa è:

YYYY-MM-DD open Account [ValutaVincolata,...] ["MetodoDiCarico"]

Apertura Base​

2014-05-01 open Assets:US:BofA:Checking

Con Vincoli di Valuta​

Limitare le valute previene la registrazione accidentale della valuta sbagliata:

2014-05-01 open Assets:US:BofA:Checking       USD
2014-05-01 open Assets:Cash                    USD,CAD,EUR
2012-03-01 open Assets:US:ETrade:Main:ITOT     ITOT

Con Metodi di Carico​

Per i conti di investimento, specifica come vengono abbinate le partite quando vendi:

2014-02-11 open Assets:US:ETrade:IVV   IVV   "FIFO"
2014-02-11 open Assets:US:Schwab:AAPL  AAPL  "LIFO"
2014-02-11 open Assets:US:Fidelity     GOOG  "STRICT"

Metodi di carico disponibili:

Con Metadati​

2013-03-14 open Assets:US:BTrade:HOOLI
  category: "taxable"
  institution: "BTrade Corp"
  account-number: "XX-1234-5678"

Scegliere le Date di Apertura in Modo Strategico​

• Usa la tua data di nascita per conti universali come Expenses:Groceries (questo ti dà somme a vita)
• Usa la data di inizio del rapporto di lavoro per i conti di reddito legati al lavoro
• Usa la data effettiva di creazione del conto per conti specifici dell'istituto (conti bancari, carte di credito)

Apertura Automatica con un Plugin​

Se vuoi saltare le direttive open manuali durante la prototipazione:

plugin "beancount.plugins.auto_accounts"

Questo genera automaticamente le direttive open per qualsiasi conto a cui si fa riferimento nelle transazioni. Tuttavia, ciò riduce il rilevamento degli errori di battitura, quindi non è raccomandato per la produzione.

Elencare e Interrogare i Conti​

Usare bean-query (BQL)​

# Elenca tutti i conti con i saldi
bean-query ledger.beancount "SELECT account, units(sum(position)) GROUP BY 1"
 
# Elenca solo i conti spesa
bean-query ledger.beancount "SELECT account WHERE account ~ 'Expenses'"
 
# Estratto conto con saldo progressivo
bean-query ledger.beancount \
  "SELECT date, account, position, balance WHERE account ~ 'BofA:Checking'"
 
# Vista giornale per un conto specifico
bean-query ledger.beancount "JOURNAL 'Assets:US:BofA:Checking'"

Usare bean-report​

# Bilancio di verifica (tutti i conti con saldi finali)
bean-report ledger.beancount balances
 
# Stato patrimoniale
bean-report ledger.beancount balsheet
 
# Conto economico
bean-report ledger.beancount income
 
# Giornale per un conto specifico
bean-report ledger.beancount journal -a Assets:US:BofA:Checking

Usare Fava​

Fava fornisce una ricca interfaccia visiva per esplorare i conti:

• Pagina Stato Patrimoniale: albero interattivo di tutte le Attività, Passività e Patrimonio Netto
• Pagina Conto Economico: albero interattivo di tutti i Redditi e le Spese
• Pagina Conto: clicca su qualsiasi nome di conto per vedere le schede Giornale, Variazioni e Saldi
• Barra dei filtri: usa espressioni regolari per mostrare solo i conti corrispondenti (es. Assets:US)

Aggiornamento dei Conti (Rinomina e Riorganizzazione)​

Beancount non ha una direttiva di rinomina incorporata, ma esistono diversi approcci.

1. Trova e Sostituisci​

La semplice ricerca e sostituzione funziona, ma fai attenzione: Assets:Bank corrisponderebbe anche a Assets:Bank:Cash. Usa pattern che rispettino i confini delle parole:

sed -i 's/Assets:US:OldBank:Checking/Assets:US:NewBank:Checking/g' *.beancount

2. Il Plugin rename_accounts​

Il pacchetto beancount_reds_plugins fornisce un potente plugin di rinomina:

plugin "beancount_reds_plugins.rename_accounts.rename_accounts" "{
  'Expenses:Taxes' : 'Income:Taxes',
  'Assets:House:Capital-Improvements' : 'Expenses:House:Appliances',
}"

Questo plugin:

• Usa la corrispondenza di sottostringhe (Expenses:Taxes:Federal diventa automaticamente Income:Taxes:Federal)
• Supporta regex con backreference
• Genera automaticamente le direttive Open per i conti rinominati
• Non modifica i tuoi file sorgente -- cambia solo la rappresentazione in memoria
• Può essere attivato/disattivato commentando la riga del plugin

3. Modello Chiudi e Riapri​

Per le migrazioni di conti reali (es. cambio banca):

; Vecchio conto
2010-01-01 open Assets:US:OldBank:Checking  USD
 
; Chiudi il vecchio, apri il nuovo
2024-06-15 close Assets:US:OldBank:Checking
2024-06-15 open Assets:US:NewBank:Checking  USD
 
; Trasferisci il saldo rimanente
2024-06-15 * "Trasferimento alla nuova banca"
  Assets:US:OldBank:Checking    -5000.00 USD
  Assets:US:NewBank:Checking     5000.00 USD

Chiusura dei Conti​

La direttiva close segna un conto come non più attivo:

2016-11-28 close Liabilities:CreditCard:CapitalOne

Cosa Fa la Chiusura​

• Genera un errore se si verificano registrazioni dopo la data di chiusura
• Filtra il conto dai report al di fuori del suo periodo attivo
• Indica a Fava di nascondere il conto dalle viste ad albero (configurabile)

Quando Chiudere i Conti​

• Quando chiudi un conto bancario o una carta di credito reale
• Quando cambi datore di lavoro
• Quando consolidi o riorganizzi il tuo piano dei conti
• Quando vendi una proprietà o chiudi una posizione di investimento

Assert Sempre Saldo Zero Prima di Chiudere​

Beancount non verifica automaticamente un saldo zero alla chiusura. Aggiungi un assert manuale:

2023-12-31 balance Assets:US:OldBank:Savings  0.00 USD
2023-12-31 close Assets:US:OldBank:Savings

Organizzare il Tuo Piano dei Conti​

Inizia in Modo Semplice, Perfeziona nel Tempo​

Non hai bisogno del piano dei conti perfetto dal primo giorno. Inizia con categorie ampie e suddividile man mano che le tue esigenze di reporting crescono. L'autore di Beancount riferisce di avere oltre 250 conti spesa, tutti creati organicamente nel tempo.

Modelli di Organizzazione Comuni​

Modello 1: Per Istituto (per i conti dello stato patrimoniale)

Assets:US:BofA:Checking
Assets:US:BofA:Savings
Assets:US:Vanguard:401k:VTSAX
Assets:US:Vanguard:401k:VBTLX
Liabilities:US:Amex:Platinum
Liabilities:US:Chase:Sapphire

Modello 2: Per Categoria (per i conti di reddito e spesa)

Expenses:Food:Groceries
Expenses:Food:Restaurant
Expenses:Food:Coffee
Expenses:Housing:Rent
Expenses:Housing:Insurance
Expenses:Housing:Utilities:Electric
Expenses:Housing:Utilities:Water
Expenses:Transport:Subway
Expenses:Transport:Gas
Expenses:Health:Medical
Expenses:Health:Dental

Modello 3: Per Geografia (per finanze multinazionali)

Assets:US:BofA:Checking
Assets:CA:RBC:Checking
Assets:UK:HSBC:Current
Income:US:Acme:Salary
Income:CA:Freelance:Consulting

Modello 4: Per Proprietà o Progetto (per immobili o aziende)

Assets:US:Loft4530:Property
Income:US:Loft4530:Rental
Expenses:Loft4530:Electricity
Expenses:Loft4530:Insurance
Expenses:Loft4530:Maintenance

Modello 5: Rispecchiamento dei Conti Correlati (stesso componente istituto)

Assets:US:ETrade:Cash
Assets:US:ETrade:AAPL
Income:US:ETrade:Dividends
Income:US:ETrade:PnL
Expenses:US:ETrade:Commissions

Quanto Dovrebbero Essere Profonde le Gerarchie?​

• 2-3 livelli è comune per le categorie di spesa (Expenses:Food:Restaurant)
• 3-4 livelli per articoli patrimoniali strutturati (Assets:US:Vanguard:401k:VTSAX)
• Evita di superare i 5 livelli a meno che tu non abbia una forte ragione di reporting
• Le gerarchie profonde funzionano bene quando Fava le comprime nelle viste ad albero

Un Esempio Reale​

Ecco un piano dei conti pratico per la finanza personale:

; ── Attività ──
Assets:US:BofA:Checking         USD
Assets:US:BofA:Savings          USD
Assets:US:Vanguard:401k:VTSAX  VTSAX
Assets:US:Vanguard:Roth:VTSAX  VTSAX
Assets:US:ETrade:Cash           USD
Assets:US:ETrade:AAPL           AAPL
Assets:Cash:Wallet              USD
 
; ── Passività ──
Liabilities:US:Amex:Platinum    USD
Liabilities:US:Chase:Freedom    USD
Liabilities:US:BofA:Mortgage    USD
 
; ── Reddito ──
Income:US:Employer:Salary
Income:US:Employer:Bonus
Income:US:Employer:Match401k
Income:US:ETrade:Dividends
Income:US:BofA:Interest
 
; ── Spese ──
Expenses:Food:Groceries
Expenses:Food:Restaurant
Expenses:Food:Coffee
Expenses:Housing:Rent
Expenses:Housing:Insurance
Expenses:Housing:Utilities:Electric
Expenses:Housing:Utilities:Water
Expenses:Transport:Subway
Expenses:Transport:Taxi
Expenses:Transport:Gas
Expenses:Health:Medical
Expenses:Health:Dental
Expenses:Health:Pharmacy
Expenses:Shopping:Clothing
Expenses:Shopping:Electronics
Expenses:Entertainment:Streaming
Expenses:Entertainment:Books
Expenses:Travel:Flights
Expenses:Travel:Hotels
Expenses:Taxes:Federal
Expenses:Taxes:State
Expenses:Taxes:SocialSecurity
Expenses:Taxes:Medicare
 
; ── Patrimonio Netto ──
Equity:Opening-Balances
Equity:Retained-Earnings

Funzionalità Specifiche di Fava​

Indicatori di Aggiornamento​

Una delle migliori funzionalità di Fava per la gestione dei conti. Aggiungi questi metadati a qualsiasi conto:

2014-05-01 open Assets:US:BofA:Checking  USD
  fava-uptodate-indication: TRUE

Fava mostra poi dei punti colorati accanto al conto:

• Punto verde: l'ultima voce è un assert di saldo positivo (conto riconciliato)
• Punto rosso: l'ultima voce è un assert di saldo fallito (richiede attenzione)
• Punto giallo: l'ultima voce esiste ma non è un assert di saldo (non ancora riconciliato)
• Punto grigio: nessuna attività nel periodo di lookback

Configura la soglia del grigio:

2016-06-14 custom "fava-option" "uptodate-indicator-grey-lookback-days" "60"

Controlli della Vista ad Albero​

Controlla come Fava visualizza i conti:

; Mostra i conti chiusi nell'albero
2016-06-14 custom "fava-option" "show-closed-accounts" "true"
 
; Mostra i conti con zero transazioni
2016-06-14 custom "fava-option" "show-accounts-with-zero-transactions" "true"
 
; Mostra i conti con saldo zero
2016-06-14 custom "fava-option" "show-accounts-with-zero-balance" "true"

Pattern di Compressione​

Comprimi i conti profondamente annidati per impostazione predefinita:

; Comprimi tutti i conti a 3+ livelli di profondità
2016-06-14 custom "fava-option" "collapse-pattern" ".*:.*:.*"
 
; Comprimi sottoalberi specifici
2016-06-14 custom "fava-option" "collapse-pattern" "Assets:US:Vanguard:.*"

Includi Figli nel Giornale del Conto​

Quando visualizzi il giornale di un conto in Fava, includi le registrazioni dei conti figli:

2016-06-14 custom "fava-option" "account-journal-include-children" "true"

Inverti i Segni per Leggibilità​

Per impostazione predefinita, reddito e passività vengono mostrati come numeri negativi (il loro segno naturale). Per visualizzarli come positivi:

2016-06-14 custom "fava-option" "invert-income-liabilities-equity" "true"

Gestione dei Documenti​

Fava integra la gestione dei documenti con la tua gerarchia di conti. Imposta una directory per i documenti:

option "documents" "/percorso/dei/documenti"

Quindi organizza i file per percorso del conto:

/percorso/dei/documenti/
  Assets/
    US/
      BofA/
        Checking/
          2024-01-15.estratto-conto-gennaio.pdf
          2024-02-15.estratto-conto-febbraio.pdf
  Liabilities/
    US/
      Amex/
        Platinum/
          2024-03-15.fattura-marzo.pdf

I file che iniziano con YYYY-MM-DD vengono scoperti automaticamente da Fava e appaiono nella vista del giornale del conto.

Errori Comuni e Come Evitarli​

1. Errori di Battitura nei Nomi dei Conti​

Un semplice errore di battitura come Expenses:Grocries crea un nuovo conto non intenzionale.

Soluzione: Non usare il plugin auto_accounts in produzione. Richiedi direttive open esplicite. Beancount segnalerà immediatamente un errore per qualsiasi conto non dichiarato:

ERROR: Riferimento non valido al conto sconosciuto 'Expenses:Grocries'

2. Dimenticare i Vincoli di Valuta​

Senza vincoli di valuta, puoi registrare accidentalmente EUR su un conto solo USD.

Soluzione: Specifica sempre le valute nelle direttive open:

2014-01-01 open Assets:US:BofA:Checking  USD

3. Non Eseguire Assert di Saldo Regolarmente​

Senza assert di saldo regolari, gli errori possono passare inosservati per mesi.

Soluzione: Aggiungi assert di saldo mensili per ogni conto attivo:

2024-01-01 balance Assets:US:BofA:Checking   5,432.10 USD
2024-02-01 balance Assets:US:BofA:Checking   4,890.55 USD
2024-03-01 balance Assets:US:BofA:Checking   6,123.00 USD

4. Convenzioni di Denominazione Incoerenti​

Mescolare modelli (es. Expenses:Food vs Expenses:US:Food) rende confuse le query e i report.

Soluzione: Scegli una convenzione e mantienila. Usa prefissi paese per i conti patrimoniali, denominazione basata sulla categoria per redditi e spese.

5. Chiudere Senza Assert di Saldo Zero​

La direttiva close non verifica il saldo. Potresti chiudere un conto che ha ancora soldi.

Soluzione: Associa sempre la chiusura a un assert di saldo:

2023-12-31 balance Assets:US:OldBank:Savings  0.00 USD
2023-12-31 close Assets:US:OldBank:Savings

Modelli Avanzati​

Consigli per la Multivaluta​

Dichiara le tue valute operative per colonne di report dedicate:

option "operating_currency" "USD"
option "operating_currency" "EUR"

Per i conti multivaluta, elenca tutte le valute consentite:

2014-01-01 open Assets:Cash  USD,CAD,EUR

Gli assert di saldo con più valute devono essere eseguiti una valuta alla volta:

2024-01-01 balance Assets:Cash     562.00 USD
2024-01-01 balance Assets:Cash     210.00 CAD
2024-01-01 balance Assets:Cash      60.00 EUR

Pad e Saldo per la Configurazione Iniziale​

Usa la direttiva pad per stabilire i saldi di apertura senza calcolare manualmente gli importi:

2000-05-28 open Assets:US:BofA:Checking  USD
2000-05-28 pad Assets:US:BofA:Checking  Equity:Opening-Balances
2024-07-01 balance Assets:US:BofA:Checking  12,345.67 USD

Beancount sintetizza automaticamente la transazione di rettifica. Un'importante avvertenza: gli assert di saldo verificano il saldo all'inizio della data specificata. Quindi un pad il 2 gennaio necessita di un assert di saldo il 3 gennaio o successivo.

Metadati dei Conti per la Categorizzazione​

Usa i metadati sulle direttive open per report personalizzati:

2014-01-01 open Assets:US:BofA:Checking  USD
  category: "liquid"
  tax-status: "taxable"
 
2014-01-01 open Assets:US:Vanguard:401k  USD
  category: "retirement"
  tax-status: "tax-deferred"

Interroga i metadati con BQL:

SELECT account, META("category") WHERE META("tax-status") = "taxable"

Note per la Cronologia del Conto​

Allega note datate al giornale di qualsiasi conto:

2024-03-20 note Assets:US:BofA:Checking "Chiamato per addebito contestato, rif. #12345"
2024-06-01 note Liabilities:US:Chase:Sapphire "Commissione annuale annullata dopo chiamata alla retention"

Queste note appaiono nel giornale del conto in Fava, fornendo una traccia di audit.

Conti di Monitoraggio e Accantonamento​

Beancount non ha le registrazioni virtuali di Ledger, ma puoi usare sottoconti per l'accantonamento:

; Monitora il fondo di emergenza all'interno del conto corrente
Assets:US:BofA:Checking:EmergencyFund    USD
Assets:US:BofA:Checking:Operating        USD
 
; Monitora i rimborsi
Assets:Receivables:Employer:Travel       USD
Assets:Receivables:Friend:SharedDinner   USD

Categorie di Spesa Agevoli per le Tasse​

Struttura i conti spesa per facilitare la preparazione fiscale:

Expenses:Health:Medical:Deductible
Expenses:Charity:Deductible
Expenses:Business:Office
Expenses:Business:Equipment
Expenses:Education:Professional

Prontuario Rapido​

Riepilogo​

Gestire bene i conti è il fondamento di una contabilità Beancount efficace. Ecco i punti chiave:

1. Usa sempre direttive open esplicite -- catturano errori di battitura e impongono disciplina
2. Aggiungi vincoli di valuta per prevenire errori di valuta incrociata
3. Usa una convenzione di denominazione coerente -- per istituto per lo stato patrimoniale, per categoria per redditi/spese
4. Inizia in modo semplice e perfeziona -- suddividi i conti man mano che le tue esigenze di reporting crescono
5. Esegui assert di saldo regolarmente -- la riconciliazione mensile coglie gli errori presto
6. Chiudi i conti correttamente -- con un assert di saldo zero
7. Sfrutta le funzionalità di Fava -- indicatori di aggiornamento, pattern di compressione e integrazione dei documenti
8. Usa i metadati per categorizzazione e reporting personalizzati

Buona contabilità!