I Ledger Ospitati Ora Risolvono gli Include di Prezzi Gestiti

I tuoi titoli sono già nel ledger. I loro prezzi sono la parte che continui a riscrivere.

Questa asimmetria è il lavoretto più antico della contabilità plain-text. Un acquisto viene scritto una volta ed è vero per sempre: 120 NWRB {41.80 USD, 2024-03-12} registra una quantità, un costo e una data, e nulla di ciò che accade in seguito cambia alcuno dei tre. Un prezzo è l'opposto — corretto per un giorno, poi silenziosamente sbagliato, e sbagliato in un modo che nessun controllo di bilancio catturerà mai, perché un prezzo obsoleto quadra perfettamente lo stesso. La risposta di Beancount stesso è sempre stata quella di recuperarli con uno strumento e commettere l'output, cosa che funziona e che molti hanno automatizzato. Resta comunque uno script che possiedi, una voce di cron che mantieni e un file che unisci.

Il motore del ledger di beancount.io ora fa quella risoluzione da sé, per i ledger ospitati da noi. Questo articolo riguarda ciò che è stato effettivamente rilasciato, ciò che deliberatamente non tocca e — altrettanto importante — ciò che non è ancora costruito.

Cosa è stato rilasciato​

Un ledger beancount.io ospitato può portare un include il cui target è un URL invece di un nome di file:

; main.bean, in un ledger beancount.io ospitato.
;
; La riga gestita è mostrata commentata di proposito: l'`include` a monte accetta un
; glob di file, quindi questo file si carica ancora se lo copi sulla tua macchina. Solo
; il motore ospitato risolve la forma con URL.
 
option "title" "Taxable brokerage"
option "operating_currency" "USD"
 
include "accounts.bean"
; include "https://beancount.io/prices/ACME-USD"
 
include "transactions/purchases.bean"
include "transactions/sales.bean"

L'include di Beancount a monte accetta un nome di file — "il percorso specificato può essere un nome di file assoluto o relativo" è tutta la specifica — quindi un include con URL non è Beancount puro e non finge mai di esserlo. È un comportamento del motore ospitato, ed ecco precisamente cosa ne fa il motore:

• Materializza il feed come file virtuale di sola lettura. L'URL si risolve attraverso il percorso di risoluzione degli include del motore stesso, esattamente dove sarebbe atterrato un file locale, così ogni direttiva mantiene una posizione sorgente reale. I tuoi byte non vengono mai riscritti. Il file che hai scritto resta il file che hai scritto.
• Il corpo recuperato è validato come solo-prezzi. Direttive price, commenti e quattro chiavi di metadati consentite — price-source, price-kind, observed-at e provisional — e nient'altro. Qualsiasi cosa oltre questo rigetta l'intero corpo. Non c'è ingestione parziale, quindi un feed non può mai introdurre di nascosto una transazione nei tuoi libri.
• I feed sono messi in cache come revisione immutabile più puntatore mobile. L'aggiornamento è guidato da un timestamp invece che dalla scadenza della cache, il che significa che un'interruzione a monte non può portarsi via la tua ultima revisione buona. Un aggiornamento fallito non sostituisce mai una revisione buona con nulla.
• La freschezza è calcolata quando il ledger viene letto, non memorizzata: recent, stale o unavailable, insieme al tempo di osservazione che il feed stesso ha riportato. Un prezzo che non puoi datare è un prezzo che non puoi verificare.
• Le voci gestite sono di sola lettura. Modificarne o eliminarne una viene rifiutato con un errore che nomina la fonte gestita, e non contano contro i limiti delle direttive — al feed non è permesso consumare il budget del tuo ledger.

Tutto in quell'elenco gira all'interno del servizio del ledger ospitato. Nulla di esso cambia ciò che significa una direttiva price: stabilisce ancora il tasso di cambio tra una commodity base e una commodity quotata, esattamente come lo definisce il riferimento del linguaggio. Il compito del motore è solo quello di mettere direttive corrette, datate e attribuibili davanti al loader.

Il tuo prezzo vince sempre​

Questa è la parte che decide se un feed è utilizzabile da qualcuno che prende sul serio il proprio ledger, quindi va enunciata con precisione.

Per la stessa data e la stessa coppia di commodity — e per la coppia reciproca — un prezzo che hai scritto tu vince sul feed gestito, indipendentemente dall'ordine degli include.

Non "di solito", e non "se metti il tuo include per ultimo". La decisione di shadowing viene presa prima che la mappa dei prezzi sia costruita, quindi non dipende da dove si trova l'include nel file. Spostalo in cima, spostalo in fondo, dividilo su tre file: la risposta è la stessa.

; include "https://beancount.io/prices/ACME-USD"   ; forma del motore ospitato, di nuovo mostrata commentata
 
; Un prezzo che hai scritto tu, per la stessa data e coppia.
; Questo vince — sopra l'include o sotto, non fa differenza.
2026-09-16 price ACME 93.40 USD

(ACME è l'emittente fittizio del ledger di esempio più in basso; il numero è inventato, non un'osservazione di mercato.)

Perché quella regola e non l'altra: un prezzo nel tuo file è una decisione. Potrebbe essere la chiusura che il tuo broker ha stampato sull'estratto conto con cui stai facendo la riconciliazione, una quotazione coeva per una posizione poco scambiata, o una cifra che il tuo commercialista ti ha chiesto di usare. Un feed non sa nulla di tutto ciò, e un sistema che sovrascrive silenziosamente una cifra redatta da una persona ha smesso di essere un ledger e ha iniziato a essere un'opinione. Il feed riempie le lacune; non ti corregge.

I prezzi muovono la valutazione, e nient'altro​

La seconda rassicurazione è strutturale piuttosto che una scelta di policy, e vale la pena mostrarla con numeri reali invece di affermarla. Ecco il ledger di esempio per le crypto — lotti datati, staking, mining, posizioni DeFi, airdrop:

Prendi una voce da esso. Un airdrop di token di governance 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 riguardanti il 2024-03-20. Ogni direttiva price nel ledger — gestita, scritta a mano o del tutto assente — lascia entrambe intatte. I prezzi cambiano il valore di mercato; non cambiano mai quantità, base di costo, flussi di cassa, commissioni o plusvalenze realizzate. Ecco perché un feed di prezzi è una cosa sicura di cui accettare aiuto in primo luogo: il peggio che un prezzo sbagliato può fare è riportare erroneamente quanto vale oggi una posizione, e non può mai corrompere il numero che metterai su una dichiarazione dei redditi.

Dove un modello di prezzo sbagliato ti induce davvero in errore​

Il ledger di esempio di azioni ed ETF rende la versione più incisiva dello stesso punto:

Contiene uno split azionario 4-a-1, e lo split è 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 sono $5.016,00. Il valore di mercato è invariato attraverso lo split — 120 azioni a $62,00 il giorno prima, 480 azioni a $15,50 il giorno dopo, $7.440,00 in entrambi i casi — e la data di acquisizione nelle parentesi graffe sopravvive, ed è ciò che mantiene a lungo termine una vendita di quelle azioni nel 2026.

L'errore comune è registrare uno split come evento di prezzo e affidarsi a una serie "rettificata per lo split" per far quadrare la valutazione. Funziona solo finché ogni prezzo che vedi è stato rettificato allo stesso modo. Nel momento in cui arriva una cifra non rettificata — una vecchia conferma, uno screenshot, una serie di terze parti che non ridetermina nulla — la posizione è valutata al quadruplo del suo valore, e il numero di azioni nel ledger non corrisponde più all'estratto conto del broker, quindi l'asserzione di fine anno che l'avrebbe catturato non può scattare.

Questo è il vero argomento a favore di un feed di prezzi con una fonte dichiarata, un tipo dichiarato e un tempo di osservazione visibile: non la comodità, ma il sapere sotto quale convenzione è stato calcolato il numero che hai appena importato. Il file dei prezzi del ledger di esempio è deliberatamente non rettificato e lo dichiara, e le sue due direttive che scavallano lo split sono scritte come un controllo che puoi verificare a occhio.

Una nota onesta sul cliccare dentro uno dei due embed: il visualizzatore di ledger ospitato rende i saldi dei conti al costo, e non offre alcun controllo di valutazione sulla pagina. I ledger qui sopra servono a mostrarti i ledger — i lotti, lo split, le vendite a lotto specifico — non una valutazione di mercato che il visualizzatore attualmente non disegna. Entrambi sono pubblici, ed entrambi possono essere clonati ed eseguiti localmente.

Cosa non c'è ancora​

Una voce di changelog vale meno di niente se ti lascia credere qualcosa che non è vero, quindi ecco l'altra metà, in modo chiaro e senza alcuna data attaccata a nulla di tutto ciò.

• L'endpoint dei prezzi non è pubblico. Una richiesta anonima a https://beancount.io/prices/<ALIAS> viene reindirizzata alla pagina di login. Non esiste un catalogo pubblico di alias.
• Quindi questo non è qualcosa che puoi incollare nel tuo file oggi. Il motore risolve l'include; la rotta che risolve non è ancora aperta. Quando lo sarà, quella sarà una sua propria voce di changelog.
• La CLI locale bea non risolve gli include con URL. Legge i file dal disco, quindi un include con URL fallisce localmente come un glob di file che non corrisponde a nessun file. Il supporto del loader nella CLI è un seguito già nominato.
• Non c'è alcuna superficie API. Nessun campo REST, GraphQL o MCP per i prezzi gestiti.
• Non c'è alcuna superficie di dashboard. Nessuna schermata di connessione di un feed e nessuna etichetta di freschezza nell'interfaccia; la freschezza che il motore calcola non ha ancora un posto dove essere mostrata.
• Snapshot ed export non sono costruiti, e nemmeno un catalogo di strumenti o un endpoint di aggiornamento manuale.

Ciò che è stato rilasciato è lo strato del motore: la risoluzione degli include, la validazione, la cache delle revisioni, la regola di precedenza e il calcolo della freschezza. Questa è la parte su cui tutto il resto deve reggersi, ed è la parte più difficile da cambiare in seguito, ed è per questo che è andata per prima.

Dove guardare dopo​

Entrambi i ledger qui sopra fanno parte della galleria di esempi, sei schemi elaborati che puoi clonare ed eseguire localmente — entrambi questi due includono di proposito file di prezzi statici e versionati, così una copia fatta tra due anni produce ancora il report che produce oggi. Tutto il resto che rilasciamo atterra sul changelog.

Se stai ancora tenendo aggiornati i prezzi con un tuo fetcher, quella resta la risposta giusta per un ledger locale, e la documentazione sul recupero dei prezzi di Beancount stesso più lo strumento mantenuto beanprice sono il punto da cui iniziare.

Mantieni noiosa la parte noiosa​

Il motivo per cui vale la pena automatizzare i prezzi è che sono l'unica parte di un ledger plain-text che decade da sola. Beancount.io ti offre una contabilità plain-text che resta tua — verificabile, sotto controllo di versione e mai riscritta alle tue spalle, che è esattamente lo standard che un feed gestito doveva soddisfare prima che ne rilasciassimo uno. Inizia gratis e tieni i tuoi libri in file che puoi leggere.