I Ledger Ospitati Ora Risolvono gli Include di Prezzi Gestiti

Ammettiamolo: le tue partecipazioni sono già perfettamente registrate nel tuo ledger. Sono i prezzi a tenerti intrappolato in un ciclo di riscritture senza fine.

Questa asimmetria è il compito più antico e frustrante della contabilità in testo semplice. Scrivi un acquisto una volta, ed è fissato per sempre: 120 NWRB {41.80 USD, 2024-03-12} blocca permanentemente una quantità, un costo e una data. Nulla di ciò che accade dopo cambia questi fatti. Un prezzo, invece, è l'esatto opposto—è corretto per esattamente un giorno, e poi diventa silenziosamente sbagliato. Peggio ancora, è sbagliato in un modo che nessun controllo di saldo catturerà mai, perché un ledger con prezzi obsoleti continua a bilanciarsi perfettamente.

Storicamente, il modo Beancount di gestire questo è stato recuperare i prezzi con uno script e committare l'output. Funziona, e molte persone lo hanno automatizzato. Ma alla fine della giornata, è comunque uno script che devi accudire, un cron job che devi mantenere, e un file che continui a fare merge.

Basta. Per i ledger ospitati su beancount.io, il nostro motore ora gestisce questa risoluzione in modo nativo. Questo post copre esattamente cosa è appena stato rilasciato, cosa abbiamo deliberatamente evitato di toccare e—altrettanto importante—cosa non abbiamo ancora costruito.

Cosa È Stato Rilasciato​

Un ledger beancount.io ospitato ora può contenere una direttiva include che punta a un URL invece che a un nome di file locale:

; main.bean, in a hosted beancount.io ledger.
;
; This page is Italian, so the quote currency is EUR. On another language of
; this site, use the currency in the list under the fence.
 
option "title" "Taxable brokerage"
option "operating_currency" "EUR"
 
; Only the hosted engine resolves the URL form, and upstream `include` takes a
; file glob — so the line is shown commented out here and this file still
; loads if you copy it to your own machine. Uncomment it in a hosted ledger.
; include "https://beancount.io/prices/AAPL-EUR"

Attenzione: Devi effettuare l'accesso prima di visitare quell'URL. Le richieste anonime reindirizzano alla pagina di login. Questa pagina è in italiano, quindi l'esempio quota in euro — la valuta in cui i lettori qui tengono più spesso i libri contabili. Una volta autenticato, apri https://beancount.io/prices/AAPL-EUR e conferma che stai guardando direttive price standard. Poi aggiungi quella riga al tuo ledger ospitato.

Se leggi in un'altra lingua, usa invece la valuta abituale di quella lingua, e solo quando il catalogo la elenca come quotazione:

• English: USD, https://beancount.io/prices/AAPL-USD
• 中文: CNY, https://beancount.io/prices/AAPL-CNY. Quell'URL non è una coppia elencata. È la chiusura non aggiustata di AAPL-USD di Databento, incrociata con il USD-CNY della BCE.
• 日本語: JPY, https://beancount.io/prices/AAPL-JPY
• 한국어: KRW, https://beancount.io/prices/AAPL-KRW
• Deutsch, Français, Español, Italiano, Nederlands, Català, Português, Slovenčina e Български: EUR, https://beancount.io/prices/AAPL-EUR. I libri contabili bulgari aperti quest'anno sono in euro; il catalogo quota anche BGN se un file più vecchio lo usa ancora.
• فارسی, Русский e Українська: il catalogo non ha IRR, RUB o UAH, quindi non c'è una coppia da aprire. Scegli una quotazione che elenca.

Il catalogo su https://beancount.io/prices/ si trova dietro lo stesso login. AAPL-USD stesso è una quotazione diretta di Databento, non un incrocio. Altre azioni di fascia 1 funzionano allo stesso modo — cambia il ticker, mantieni la valuta di quotazione per la tua lingua. ACME-USD restituisce un 404.

L'include di Beancount upstream tecnicamente si aspetta un nome di file, quindi un include di URL è un comportamento rigoroso del motore ospitato. Non pretende mai di essere Beancount puro. Ecco esattamente cosa fa il nostro motore sotto il cofano:

• Materializza il feed come file virtuale in sola lettura. L'URL viene risolto attraverso il percorso di risoluzione degli include del motore stesso—atterrando esattamente dove sarebbe atterrato un file locale—così ogni direttiva mantiene una posizione sorgente reale. I tuoi byte originali non vengono mai riscritti. Il file che hai scritto rimane il file che hai scritto.
• Validazione rigorosa del payload. Il corpo recuperato viene validato come solo prezzi. Consentiamo rigorosamente direttive price, commenti e quattro chiavi di metadati specifiche (price-source, price-kind, observed-at e provisional). Qualsiasi altra cosa rifiuta l'intero corpo. Non c'è ingestion parziale, il che significa che un feed malintenzionato non può mai contrabbandare una transazione nei tuoi libri contabili.
• Caching intelligente. I feed vengono memorizzati nella cache come revisione immutabile con un puntatore mobile. I cicli di aggiornamento sono guidati da timestamp piuttosto che dalla scadenza della cache, assicurando che un'interruzione upstream non cancelli la tua ultima revisione valida.
• Freschezza verificabile. La freschezza viene calcolata dinamicamente quando il ledger viene letto (recente, obsoleto o non disponibile) insieme al tempo di osservazione riportato dal feed. Un prezzo che non puoi datare è un prezzo che non puoi verificare.
• Rigorosamente in sola lettura. Le voci gestite non possono essere modificate o eliminate (tentare di farlo genera un errore che nomina la fonte). Inoltre, non contano ai fini dei tuoi limiti di direttive—non lasciamo che i feed consumino il budget del tuo ledger.

Nulla di tutto ciò cambia ciò che una direttiva price significa fondamentalmente in Beancount. L'unico compito del motore è mettere prezzi corretti, datati e attribuibili davanti al loader.

I Tuoi Prezzi Vincono Sempre​

Questo è il punto decisivo per chiunque prenda sul serio il proprio ledger, quindi chiariamo bene:

Per la stessa data e la stessa coppia di commodity (incluso il suo reciproco), un prezzo che hai scritto tu stesso vince sempre sul feed gestito.

Non "di solito", e non "solo se metti il tuo include per ultimo". Questa decisione di shadowing avviene prima che la mappa dei prezzi venga costruita, il che significa che è completamente indipendente da dove si trova l'include nel tuo file. Mettilo in cima, mettilo in fondo, o dividilo su tre file—il tuo prezzo scritto a mano vince sempre.

La regola del reciproco è facile da trascurare ma vitale. Un feed di AAPL-USD è un prezzo di AAPL in USD. Se hai scritto a mano un prezzo al contrario — USD in AAPL, stessa data — la tua voce batte comunque il feed. Lo stesso vale per qualunque quotazione tu abbia incluso, CNY o JPY inclusi.

Perché questa regola? Perché un prezzo nel tuo file è una decisione consapevole. Potrebbe essere la chiusura esatta che il tuo broker ha stampato su un estratto conto che stai riconciliando, una quotazione contemporanea per un asset poco scambiato, o una cifra specifica richiesta dal tuo commercialista. Un feed non conosce il tuo contesto. Un sistema che sovrascrive silenziosamente una cifra scritta da un umano smette di essere un ledger e diventa un'opinione. Il feed è lì per riempire le lacune; non ti corregge.

I Prezzi Muovono la Valutazione, e Nient'Altro​

Questa prossima rassicurazione è strutturale piuttosto che una scelta politica, ed è meglio mostrata con numeri reali. Dai un'occhiata al nostro ledger di esempio crypto, con lotti datati, staking, posizioni DeFi e airdrop:

Prendiamo una voce specifica. Un airdrop di governance-token arriva e viene registrato come reddito al fair market value del giorno in cui atterra:

2024-03-20 * "Uniswap" "Receive UNI governance token airdrop"
  Assets:Crypto:Wallet:MetaMask:UNI       50.00 UNI {12.50 USD, 2024-03-20}
  Income:Crypto:Airdrops                -625.00 USD
 

Quei $625,00 di reddito, e la base di $12,50 per unità associata al lotto, sono ora fatti immutabili relativi al 2024-03-20. Ogni direttiva price nel ledger—che sia gestita, scritta a mano o completamente assente—lascia entrambi intatti.

I prezzi cambiano il valore di mercato; non alterano mai quantità, base di costo, flussi di cassa, commissioni o plusvalenze realizzate. Questo è esattamente il motivo per cui un feed di prezzi è uno strumento sicuro su cui appoggiarsi: il peggio assoluto che un prezzo sbagliato può fare è dichiarare temporaneamente in modo errato quanto vale oggi una posizione. Non può mai corrompere i numeri solidi che metterai nella tua dichiarazione dei redditi.

Dove un Modello di Prezzo Sbagliato Ti Trae Davvero in Inganno​

Il ledger di esempio di azioni ed ETF illustra la versione più netta di questo stesso punto:

Contiene un frazionamento azionario 4-per-1, registrato nel modo corretto—come variazione di quantità che preserva la base totale senza toccare alcun conto di reddito:

2025-07-15 * "Broker" "NWRB 4-for-1 share split — quantity change, not income"
  Assets:Brokerage:NWRB                   -120 NWRB {41.80 USD, 2024-03-12}
  Assets:Brokerage:NWRB                    480 NWRB {10.45 USD, 2024-03-12}
 

Entrambi i lati equivalgono a $5.016,00. Il valore di mercato rimane invariato attraverso il frazionamento ($7.440,00 in entrambi i casi), e la data di acquisizione tra parentesi graffe sopravvive—che è ciò che mantiene una vendita del 2026 di quelle azioni classificata come a lungo termine.

La trappola comune è registrare un frazionamento come evento di prezzo, appoggiandosi pesantemente a una serie di prezzi "aggiustata per il frazionamento" per far quadrare i conti. Funziona solo finché ogni prezzo che guardi è stato aggiustato esattamente allo stesso modo. Nel momento in cui una cifra non aggiustata entra nel tuo ledger—una vecchia ricevuta di conferma, uno screenshot, o un feed di terze parti che non ricalcola gli storici—la posizione è improvvisamente valutata quattro volte il suo valore effettivo. Peggio ancora, il numero di azioni nel ledger non corrisponde più all'estratto conto del tuo broker, il che significa che le tue assertion di saldo di fine anno falliranno silenziosamente.

Questo è il vero argomento per affidarsi a un feed di prezzi con una fonte dichiarata, un tipo dichiarato e un tempo di osservazione visibile. Non è solo una questione di comodità; è una questione di sapere esattamente quale convenzione matematica stanno usando i tuoi numeri importati.

(Una nota veloce sugli embed: il visualizzatore di ledger ospitato renderizza i saldi dei conti al costo e attualmente non offre controlli di valutazione sulla pagina. I ledger sopra sono pensati per mostrare i meccanismi sottostanti—i lotti, il frazionamento, le vendite. Entrambi sono pubblici, e puoi clonarli ed eseguirli localmente.)

Cosa Non C'È Ancora​

Crediamo che un changelog sia peggio che inutile se promette troppo. Quindi ecco la verità senza filtri su cosa non abbiamo ancora costruito, senza tempistiche allegate:

• L'autenticazione è obbligatoria. Le richieste anonime a https://beancount.io/prices/<ALIAS> ti rimbalzeranno su una pagina di login.
• Nessun supporto CLI locale. La CLI locale bea legge i file dal disco, il che significa che un include di URL fallirà localmente come glob di file non corrispondente. Aggiungere il supporto del loader alla CLI è nella nostra roadmap.
• Nessuna superficie API. Attualmente non abbiamo un campo REST, GraphQL o MCP per i prezzi gestiti.
• Nessuna dashboard UI. Non c'è ancora una schermata "connetti-un-feed" e nessuna etichetta di freschezza nella UI. (I dati di freschezza che il nostro motore calcola attualmente non hanno dove essere visualizzati).
• Nessuno snapshot, export o endpoint di aggiornamento manuale.

Quello che abbiamo rilasciato oggi è rigorosamente il livello del motore: risoluzione degli include, validazione, caching delle revisioni, regole di precedenza e calcolo della freschezza. È l'infrastruttura fondamentale su cui tutto il resto deve poggiare, che è esattamente il motivo per cui l'abbiamo costruita per prima.

Dove Guardare Ora​

Entrambi i ledger incorporati sopra fanno parte della nostra galleria di esempi—sei pattern completamente elaborati che puoi clonare ed eseguire localmente. (Entrambi vengono intenzionalmente forniti con file di prezzi statici, già committati, assicurando che un clone fatto tra due anni produca esattamente lo stesso report che produce oggi). Tutto il resto che rilasciamo atterra direttamente sul nostro changelog.

Se sei perfettamente soddisfatto di mantenere i prezzi aggiornati con il tuo fetcher, continua così. Rimane la risposta migliore per un ledger strettamente locale. La documentazione sul recupero dei prezzi di Beancount stesso e lo strumento mantenuto beanprice sono i posti migliori da cui iniziare.

Mantieni Noiosa la Parte Noiosa​

I prezzi vale la pena automatizzarli proprio perché sono l'unica parte di un ledger in testo semplice che marcisce nel tempo. Beancount.io è costruito per darti una contabilità in testo semplice che rimane tua—verificabile, sotto controllo di versione e mai riscritta alle tue spalle. Questo era lo standard di base che un feed gestito doveva soddisfare prima che fossimo disposti a rilasciarlo.

Inizia gratuitamente, e mantieni i tuoi libri contabili in file che puoi effettivamente leggere.