# 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](https://beancount.io/it/docs/Basics/syntax) 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](https://beancount.io/it/docs/Tips/amortize).

## 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.

```beancount
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](https://beancount.io/it/docs/introduction-to-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](https://beancount.io/it/docs/Basics/beancount-query-language) 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](https://beancount.io/it/docs/Basics/inventories) 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](https://beancount.io/it/docs/industry-specific-setups) 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.

```beancount
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](https://beancount.io/it/docs/Basics/inventories).

## 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.

```beancount
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](https://beancount.io/it/docs/Tips/budgets).

## 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](https://beancount.io/it/docs/Tips/ui-features) 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.

```beancount
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.

```beancount
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](https://beancount.io/it/docs/Tips/forecast-plugin)
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](https://beancount.io/it/docs/Basics/precision) 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.

```beancount
2026-06-30 price VTI   271.40 USD
```

[Prezzi in Tempo Reale](https://beancount.io/it/docs/live-prices) 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](https://beancount.io/it/docs/Tips/filtering-and-searching).

## 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.

```beancount
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](https://beancount.io/it/docs/help-center) indicizza ogni guida su questo
sito, e il [Promemoria](https://beancount.io/it/docs/Basics/cheatsheet) mette la sintassi per ogni direttiva
a confronto.
