Glossario di Beancount e della contabilità in testo semplice

La contabilità in testo semplice prende in prestito il vocabolario della partita doppia e aggiunge qualche parola propria di Beancount. Questo glossario definisce i termini che incontrerai leggendo questi documenti o il tuo file di registro, ciascuno con un breve esempio dove è utile. Ogni voce ha il proprio link, così puoi indicare a un collega direttamente una definizione.

Conto​

Un conto è un contenitore con un nome che traccia un flusso di valore, scritto come una gerarchia separata da due punti sotto uno dei cinque tipi radice: Assets, Liabilities, Equity, Income o Expenses. La gerarchia è l'intera struttura organizzativa delle tue scritture — Assets:US:BofA:Checking e Expenses:Food:Restaurant si ordinano e si aggregano automaticamente. Ogni conto deve essere dichiarato prima di essere utilizzato. Vedi Sintassi del Linguaggio Beancount per le regole di denominazione.

Principio di competenza​

La contabilità per competenza registra i ricavi quando sono guadagnati e le spese quando sono sostenute, indipendentemente da quando il denaro si muove effettivamente. La contabilità per cassa fa l'opposto: riconosce entrambi solo quando il denaro cambia mani. La competenza offre un quadro più veritiero della performance di un periodo, motivo per cui una fattura che hai emesso a marzo appartiene a marzo anche se il cliente paga a maggio.

Ammortamento​

L'ammortamento distribuisce un singolo pagamento consistente sui periodi che effettivamente copre, così ogni mese porta la sua giusta quota del costo. Un premio assicurativo annuale pagato a gennaio è una spesa di tutti e dodici i mesi, non solo di gennaio. In Beancount puoi scrivere le registrazioni di ripartizione a mano o generarle con un plugin — vedi Ammortamento.

Verifica di saldo​

Un'asserzione di saldo è una direttiva balance che stabilisce quale deve essere il saldo di un conto all'inizio di una data specifica, così l'estratto conto bancario diventa un controllo automatico sulle tue scritture. Se il saldo calcolato differisce di più della tolleranza dell'asserzione, Beancount fallisce in modo evidente con gli importi attesi ed effettivi. Quella tolleranza è una unità dell'ultima cifra decimale che hai scritto — 4.27 RGAGX accetta qualsiasi valore da 4.26 a 4.28 — e un ~ prima della valuta imposta la tua. Spolverare un'asserzione per conto per estratto conto è il modo singolo più economico per mantenere un registro affidabile.

2026-01-01 balance Assets:US:BofA:Checking   4,321.00 USD

Beancount​

Beancount è un sistema di contabilità in partita doppia open-source il cui registro è un file di testo semplice che modifichi in qualsiasi editor di testo e validi con uno strumento da riga di comando. Ti offre una sintassi rigorosa e analizzabile, un linguaggio di query e un'interfaccia web, senza un database o un formato di file proprietario. Poiché il registro è testo, vive felicemente in Git accanto al tuo codice. Inizia con Introduzione a Beancount.

Linguaggio di interrogazione Beancount​

Beancount Query Language, di solito abbreviato BQL, è il linguaggio simile a SQL che usi per porre domande al tuo registro. Opera sulle direttive analizzate piuttosto che su un database, quindi SELECT account, sum(position) WHERE year = 2026 risponde immediatamente dallo stesso file che modifichi. Leggi la guida al linguaggio di query per la grammatica completa.

Metodo di prenotazione​

Un metodo di booking è la regola che Beancount applica quando una riduzione deve scegliere quali lotti esistenti prelevare. Beancount 3.2.3 accetta sette nomi: STRICT (il predefinito, dove identifichi tu stesso il lotto), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO e AVERAGE. Impostane uno per conto sulla sua direttiva open, o per l'intero file con option "booking_method". Sei dei sette sono implementati: AVERAGE si analizza, ma solleva AVERAGE method is not supported nel momento in cui deve registrare una riduzione. Il metodo che scegli cambia le tue plusvalenze realizzate, quindi scegli quello che la tua giurisdizione fiscale si aspetta e mantienilo stabile. Gestione dell'Inventario esegue tutti e sette sugli stessi lotti e pubblica il registro che fallisce con AVERAGE.

Piano dei conti​

Un piano dei conti è l'elenco completo dei conti che il tuo registro utilizza, insieme alla struttura che li organizza. In Beancount non esiste un file di piano separato — l' insieme delle direttive open è il tuo piano dei conti. Progettarlo bene fin dall'inizio fa risparmiare molte ridenominazioni in seguito; vedi Configurazioni Specifiche per Settore per punti di partenza.

Direttiva di chiusura​

Una direttiva close contrassegna la data dopo la quale un conto non può più essere utilizzato, che è il modo in cui ritiri un conto bancario o un prestito estinto senza eliminare la sua cronologia. Le transazioni passate rimangono valide e rendicontabili; solo le nuove registrazioni vengono rifiutate. Chiudere i conti inutilizzati mantiene i report leggibili man mano che un registro invecchia.

2026-03-31 close Assets:US:OldBank:Checking

Merce​

Una commodity è qualsiasi unità di valore che il tuo registro traccia — una valuta come USD, un ticker azionario come AAPL, un asset crypto come BTC, o qualcosa che inventi come VACATION-DAYS. Beancount non converte mai tra commodity alle tue spalle, quindi un importo è sempre un numero abbinato alla commodity in cui è denominato. Una direttiva commodity opzionale ti permette di allegare metadati come un nome o una classe di asset.

Base di costo​

La base di costo è ciò che hai effettivamente pagato per una partecipazione, registrata nella valuta con cui hai pagato e portata insieme alla partecipazione per tutto il tempo in cui la possiedi. Beancount la scrive tra parentesi graffe — 10 AAPL {150.00 USD} significa dieci azioni acquisite a 150 dollari ciascuna. Raddoppia le graffe e il numero diventa il totale anziché il prezzo unitario, così 10 AAPL {{1,500.00 USD}} registra lo stesso lotto. Poiché la base viaggia con la posizione, le plusvalenze emergono dall'aritmetica quando vendi. Vedi Gestione dell'Inventario.

Direttiva​

Una direttiva è una singola istruzione in un file Beancount, di solito datata, e le direttive sono ciò di cui è fatto un registro. Dodici tipi portano una data: open, close, balance, price, note, document, pad, event, commodity, custom, query e la transazione stessa. Alcune non ne portano e agiscono sul file piuttosto che su un giorno — option, include, plugin e la coppia pushtag/poptag. Beancount ordina quelle datate per data prima dell'elaborazione, così puoi tenerle nell'ordine che si legge meglio; una non datata ha effetto dove è scritta.

Contabilità a partita doppia​

La partita doppia è la pratica di registrare ogni evento economico come almeno due voci corrispondenti, in modo che i loro pesi sommino sempre a zero. Il denaro non viene mai creato o distrutto — si sposta solo tra i conti, motivo per cui la tecnica cattura errori che un elenco a colonna singola non catturerebbe mai. Un peso è l'importo proprio di una registrazione, o il suo costo o prezzo convertito in un'unica valuta, così due gambe in valute diverse si annullano comunque. Beancount applica la regola rigorosamente: una transazione le cui registrazioni non bilanciano è un errore, non un avviso.

2026-03-02 * "Bank" "Buy euros"
  Assets:US:BofA:EUR       100.00 EUR @ 1.08 USD
  Assets:US:BofA:Checking -108.00 USD

Budget a buste​

Il budget a buste mette da parte denaro per uno scopo prima di spenderlo, così ogni categoria ha il proprio limite invece di competere per un unico saldo in comune. Il nome deriva dalle buste di carta che la gente un tempo riempiva di contanti il giorno di paga. In un registro in testo semplice modelli le buste con conti dedicati o direttive di budget — vedi Budget.

Fava​

Fava è l'interfaccia web per Beancount: grafici, stati patrimoniali, conti economici, un editor di query e un modulo di inserimento, serviti dal tuo file di registro. È prevalentemente in lettura e funziona localmente, quindi cambia come vedi le tue scritture senza cambiare come le registri. beancount.io ospita una versione gestita insieme ai propri strumenti; la guida Funzionalità dell'Interfaccia copre cosa puoi fare lì.

Inventario​

Un inventario è la raccolta di posizioni che un conto detiene attualmente, ciascuna con la sua commodity e, dove rilevante, la sua base di costo e data di acquisizione. Un conto titoli che ha acquistato lo stesso titolo tre volte detiene tre lotti separati in un unico inventario, non un unico numero aggregato. Mantenere i lotti distinti è ciò che rende possibili calcoli accurati delle plusvalenze.

Giornale​

Il giornale è l'elenco cronologico di tutto ciò che è accaduto nelle tue scritture — il flusso grezzo delle transazioni, in ordine di data, prima di qualsiasi raggruppamento o sintesi. È la vista che scorri quando vuoi rispondere a "cosa ho effettivamente fatto a marzo?". La pagina del giornale di Fava è di solito il posto più veloce per individuare una voce categorizzata erroneamente.

Registro​

Un registro è l'insieme completo delle scritture contabili di una entità, che in Beancount significa il tuo file di testo semplice (più tutto ciò che include). La parola funge anche da nome dell'intero libro dei conti e del file stesso. Poiché è testo, un registro può essere messo a confronto, revisionato, ramificato e unito come codice sorgente.

Lotto​

Un lotto è una specifica acquisizione di una commodity, identificata dalla sua base di costo e data di acquisizione. Acquistare lo stesso ETF a gennaio e di nuovo a giugno crea due lotti, e vendere in seguito significa scegliere quale lotto stai vendendo. I lotti sono la ragione per cui Beancount può calcolare esattamente le plusvalenze realizzate invece di approssimarle.

2026-06-15 * "Broker" "Buy VTI"
  Assets:US:Broker:VTI     5 VTI {260.00 USD, 2026-06-15}
  Assets:US:Broker:Cash            -1,300.00 USD

Narrazione​

La narrazione è la descrizione in testo libero di cosa riguardava una transazione, scritta come la seconda stringa tra virgolette sulla riga della transazione. È per gli esseri umani: "Affitto mensile", "Spesa e articoli per la casa". Beancount non la analizza, ma è ciò che leggerai quando la voce non avrà più senso tra sei mesi.

Direttiva di apertura​

Una direttiva open dichiara un conto, la data in cui inizia a essere utilizzabile e opzionalmente le commodity che può detenere e il metodo di booking che utilizza. Beancount richiede che ogni conto sia aperto prima della sua prima registrazione, che è ciò che impedisce a un refuso di creare silenziosamente un conto nuovo di zecca. Limitare le commodity consentite trasforma un'altra intera classe di errori in errori veri e propri.

2026-01-01 open Assets:US:Broker:VTI   VTI   "FIFO"

Pad​

Una direttiva pad dice a Beancount di inserire qualsiasi importo sia necessario per far riuscire la prossima asserzione di saldo su un conto, registrando la differenza su un secondo conto. Esiste per esattamente un compito: aprire un registro a metà della sua vita senza ricostruire anni di cronologia. Fare padding oltre quella configurazione iniziale di solito significa che un vero errore viene nascosto.

Beneficiario​

Il payee è con chi hai effettuato la transazione, scritto come la prima stringa tra virgolette su una riga di transazione. Mantenere i payee coerenti — sempre "Whole Foods", mai a volte "WholeFoods" — è ciò che fa funzionare i report basati sul payee e gli importatori automatizzati. Beancount considera il payee opzionale; una transazione può portare solo una narrazione.

Contabilità in testo semplice​

La contabilità in testo semplice è la pratica di tenere le tue scritture in un file di testo leggibile dall'uomo sotto controllo di versione, elaborato da strumenti open-source da riga di comando. Scambia un' interfaccia punta-e-clicca con durabilità, verificabilità e automazione: i tuoi dati sopravvivono a qualsiasi fornitore, ogni cambiamento è un diff revisionabile e qualsiasi script può leggerlo. Beancount, Ledger e hledger sono le tre implementazioni più note.

Plugin​

Un plugin è un modulo Python che Beancount carica mentre elabora il tuo file, permettendogli di aggiungere, trasformare o validare direttive prima che vengano costruiti i report. I plugin sono il modo in cui previsioni, piani di ammortamento e controlli personalizzati vengono implementati senza cambiare il linguaggio principale. Ne abiliti uno con una riga plugin autonoma all'inizio del tuo registro, mai con un option — option "plugin" "…" viene rifiutato con Option 'plugin' may not be set. La guida Plugin di Previsione illustra un esempio reale.

Registrazione​

Una registrazione è una gamba di una transazione: un conto, un importo e opzionalmente un costo o prezzo. Ciò che deve sommare a zero in una transazione non sono gli importi grezzi ma i loro pesi: un importo semplice pesa se stesso, 10 FUND @ 38.46 USD pesa 384.60 USD e 10 FUND {384.61 USD} pesa 3,846.10 USD, perché le parentesi graffe singole contengono il costo di una unità. Al massimo una registrazione può lasciare il suo importo vuoto, nel qual caso Beancount calcola per te la cifra di bilanciamento. Vedi Precisione e Tolleranze per le regole complete sui pesi.

Direttiva prezzo​

Una direttiva price registra il tasso di cambio tra due commodity in una data, che è il modo in cui Beancount converte una partecipazione al suo valore di mercato nei report. Una direttiva price è puro dato di riferimento: non muove denaro e non appartiene a nessuna transazione. Non confonderla con il prezzo @ scritto dentro una registrazione, che è aritmetica — dà a 10 FUND @ 38.46 USD un peso di 384.60 USD e quindi decide se la transazione bilancia. Senza direttive price, un portafoglio bilancia ancora al costo ma non può essere valutato al mercato.

2026-06-30 price VTI   271.40 USD

Prezzi in Tempo Reale fornisce direttive price gestite per gli asset supportati nei registri ospitati. Il tuo prezzo prevale per la stessa data e coppia, inclusa la coppia reciproca. Un prezzo gestito in una data successiva può comunque applicarsi a una valutazione successiva.

Riconciliazione​

La riconciliazione è l'atto di dimostrare che le tue scritture concordano con un registro esterno come un estratto conto bancario o di intermediazione. Nella contabilità in testo semplice è in gran parte meccanica: aggiungi un'asserzione di saldo per ogni data di estratto conto e lascia che lo strumento ti dica se i numeri corrispondono. Un registro che si riconcilia in modo pulito ogni mese è uno da cui puoi pagare le tasse senza timore.

Tag e collegamenti​

I tag e i link sono le due etichette che alleghi alle transazioni per raggrupparle al di fuori della gerarchia dei conti: un tag con # contrassegna un tema come #trip-japan, e un link con ^ collega voci correlate come ^invoice-2026-014 insieme. I tag rispondono a "mostrami tutto in questa categoria"; i link rispondono a "mostrami le voci che appartengono a questo singolo evento". Entrambi sono filtrabili in Fava e interrogabili in BQL — vedi Filtro e Ricerca.

Transazione​

Una transazione è un evento economico datato insieme alle registrazioni che lo registrano, ed è la direttiva che scriverai più spesso. Porta un flag (* per confermata, ! per da rivedere), un payee opzionale, una narrazione e due o più registrazioni i cui pesi sommano a zero. Tutto il resto in un file Beancount esiste per dichiarare, controllare o annotare transazioni.

2026-02-14 * "Blue Bottle" "Coffee with Dana"
  Expenses:Food:Coffee      9.50 USD
  Assets:US:BofA:Checking  -9.50 USD

Ancora bloccato su una parola? Il Centro Assistenza indicizza ogni guida su questo sito, e il Promemoria mette la sintassi per ogni direttiva a confronto.