Los libros contables alojados ahora resuelven los includes de precios gestionados

Aceptémoslo: tus posiciones ya están perfectamente registradas en tu libro contable. Son los precios los que te mantienen atrapado en un ciclo de reescritura sin fin.

Esa asimetría es la tarea más antigua y más frustrante de la contabilidad de texto plano. Escribes una compra una vez, y queda fijada para siempre: 120 NWRB {41.80 USD, 2024-03-12} bloquea de forma permanente una cantidad, un coste y una fecha. Nada de lo que ocurra después cambia esos hechos. Un precio, sin embargo, es exactamente lo contrario: es correcto durante exactamente un día y luego, silenciosamente, se vuelve incorrecto. Peor aún, es incorrecto de una forma que ninguna comprobación de saldo detectará jamás, porque un libro contable con precios obsoletos sigue cuadrando a la perfección.

Históricamente, la forma de Beancount de manejar esto ha sido obtener los precios con un script y hacer commit de su salida. Funciona, y mucha gente lo ha automatizado. Pero a fin de cuentas, sigue siendo un script que hay que vigilar, un cron job que mantener y un archivo que fusionar constantemente.

Se acabó. Para los libros contables alojados en beancount.io, nuestro motor ahora gestiona esta resolución de forma nativa. Esta entrada cubre exactamente lo que acabamos de publicar, lo que evitamos deliberadamente tocar y, igual de importante, lo que aún no hemos construido.

Lo que se ha publicado​

Un libro contable alojado en beancount.io ahora puede llevar una directiva include que apunta a una URL en lugar de a un nombre de archivo local:

; main.bean, in a hosted beancount.io ledger.
;
; This page is Spanish, 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"

Atención: tendrás que iniciar sesión antes de acceder a esa URL. Las solicitudes anónimas redirigen a la página de inicio de sesión. Esta página está en español, así que el ejemplo cotiza en euros, la moneda en la que los lectores de aquí suelen llevar sus libros. Una vez autenticado, abre https://beancount.io/prices/AAPL-EUR y confirma que estás viendo directivas price estándar. Luego añade esa línea a tu libro contable alojado.

Si lees en otro idioma, usa en su lugar la moneda habitual de ese idioma, y solo cuando el catálogo la liste como cotización:

• English: USD, https://beancount.io/prices/AAPL-USD
• 中文: CNY, https://beancount.io/prices/AAPL-CNY. Esa URL no es un par listado. Es el cierre no ajustado AAPL-USD de Databento, cruzado con el USD-CNY del 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 y Български: EUR, https://beancount.io/prices/AAPL-EUR. Los libros búlgaros abiertos este año están en euros; el catálogo también cotiza BGN si algún archivo más antiguo todavía lo usa.
• فارسی, Русский y Українська: el catálogo no tiene IRR, RUB ni UAH, así que no hay par que abrir. Elige una cotización que sí esté listada.

El catálogo en https://beancount.io/prices/ está detrás de ese mismo inicio de sesión. AAPL-USD en sí es una cotización directa de Databento, no un cruce. Otras acciones de primer nivel funcionan igual: cambia el ticker y mantén la moneda de cotización de tu idioma. ACME-USD devuelve un 404.

El include de Beancount upstream técnicamente espera un nombre de archivo, así que un include de URL es un comportamiento estricto del motor alojado. Nunca pretende ser Beancount puro. Esto es exactamente lo que hace nuestro motor bajo el capó:

• Materializa el feed como un archivo virtual de solo lectura. La URL se resuelve a través del propio camino de resolución de includes del motor —aterrizando exactamente donde lo habría hecho un archivo local—, de modo que cada directiva conserva una ubicación de origen real. Tus bytes originales nunca se reescriben. El archivo que escribiste sigue siendo el archivo que escribiste.
• Validación estricta del payload. El cuerpo obtenido se valida como solo precios. Permitimos estrictamente directivas price, comentarios y cuatro claves de metadatos específicas (price-source, price-kind, observed-at y provisional). Cualquier otra cosa rechaza el cuerpo entero. No hay ingesta parcial, lo que significa que un feed malicioso nunca puede colar una transacción en tus libros.
• Caché inteligente. Los feeds se almacenan en caché como una revisión inmutable con un puntero móvil. Los ciclos de refresco se guían por marcas de tiempo en lugar de por la expiración de la caché, lo que garantiza que una caída upstream no borre tu última revisión buena.
• Frescura auditable. La frescura se calcula dinámicamente cuando se lee el libro contable (reciente, obsoleta o no disponible) junto con la hora de observación reportada por el feed. Un precio que no puedes fechar es un precio que no puedes auditar.
• Estrictamente de solo lectura. Las entradas gestionadas no se pueden editar ni eliminar (intentarlo lanza un error que nombra la fuente). Además, no cuentan contra tus límites de directivas: no dejamos que los feeds se coman el presupuesto de tu libro contable.

Nada de esto cambia lo que significa fundamentalmente una directiva price en Beancount. El único trabajo del motor es poner precios correctos, fechados y atribuibles delante del cargador.

Tu propio precio siempre gana​

Esto es decisivo para cualquiera que se tome en serio su libro contable, así que seamos cristalinos:

Para la misma fecha y el mismo par de materias primas (incluido su recíproco), un precio que hayas escrito tú mismo siempre gana sobre el feed gestionado.

No "normalmente", y no "solo si pones tu include al final". Esta decisión de ensombrecimiento ocurre antes de que se construya el mapa de precios, lo que significa que es completamente independiente de dónde esté el include en tu archivo. Ponlo arriba, ponlo abajo o divídelo en tres archivos: tu precio escrito a mano siempre gana.

La regla del recíproco es fácil de pasar por alto pero vital. Un feed de AAPL-USD es un precio de AAPL en USD. Si escribiste a mano un precio al revés —USD en AAPL, misma fecha— tu entrada sigue venciendo al feed. Lo mismo ocurre con la cotización que hayas incluido, ya sea CNY o JPY.

¿Por qué esta regla? Porque un precio en tu propio archivo es una decisión consciente. Puede ser el cierre exacto que tu bróker imprimió en un extracto que estás conciliando, una cotización contemporánea de un activo poco negociado, o una cifra concreta que tu contable exigió. Un feed no conoce tu contexto. Un sistema que sobrescribe silenciosamente una cifra escrita por un humano deja de ser un libro contable y se convierte en una opinión. El feed está ahí para rellenar huecos; no te corrige.

Los precios mueven la valoración, y nada más​

Esta siguiente tranquilidad es estructural más que una elección de política, y se muestra mejor con números reales. Echa un vistazo a nuestro libro contable de ejemplo sobre cripto, con lotes fechados, staking, posiciones DeFi y airdrops:

Extraigamos una entrada concreta. Llega un airdrop de un token de gobernanza y se registra como ingreso a valor razonable de mercado el día en que aterriza:

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
 

Esos $625.00 de ingreso, y la base de $12.50 por unidad asociada al lote, son ahora hechos inmutables del 2024-03-20. Todas las directivas price del libro contable —ya sean gestionadas, escritas a mano o totalmente ausentes— dejan ambas intactas.

Los precios cambian el valor de mercado; nunca alteran cantidades, base de coste, flujos de caja, comisiones ni ganancias realizadas. Esto es exactamente por lo que un feed de precios es una herramienta segura en la que apoyarse: lo peor que puede hacer un precio erróneo es declarar temporalmente mal lo que vale hoy una posición. Nunca puede corromper los números firmes que pondrás en tu declaración de impuestos.

Dónde te engaña de verdad un modelo de precios equivocado​

El libro contable de ejemplo de acciones y ETF ilustra la versión más afilada de este mismo punto:

Contiene un split de acciones 4 por 1, registrado de la forma correcta: como un cambio de cantidad que preserva la base total sin tocar ninguna cuenta de ingresos:

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}
 

Ambos lados equivalen a $5,016.00. El valor de mercado permanece inalterado a lo largo del split ($7,440.00 de cualquier manera), y la fecha de adquisición entre llaves sobrevive, que es lo que mantiene una venta de esas acciones en 2026 clasificada como a largo plazo.

La trampa habitual es registrar un split como un evento de precio, apoyándose fuertemente en una serie de precios "ajustada por split" para que las cuentas cuadren. Eso solo funciona mientras todos los precios que consultes alguna vez hayan sido ajustados exactamente de la misma manera. En el momento en que una cifra no ajustada llega a tu libro contable —un recibo de confirmación antiguo, una captura de pantalla o un feed de terceros que no reexpresa los históricos— la posición pasa de repente a valorarse por cuatro veces su valor real. Peor aún, el número de acciones del libro contable ya no coincide con el extracto de tu bróker, lo que significa que tus aserciones de saldo de fin de año fallarán silenciosamente.

Este es el verdadero argumento para apoyarse en un feed de precios con una fuente declarada, un tipo declarado y una hora de observación visible. No se trata solo de comodidad; se trata de saber exactamente qué convención matemática están usando tus números importados.

(Una nota rápida sobre los embeds: el visor de libros contables alojados muestra los saldos de las cuentas a coste y actualmente no ofrece controles de valoración en la página. Los libros contables de arriba pretenden mostrar la mecánica subyacente: los lotes, el split, las ventas. Ambos son públicos, y puedes clonarlos y ejecutarlos localmente.)

Lo que aún no está aquí​

Creemos que un changelog es peor que inútil si promete de más. Así que aquí está la verdad sin adornos sobre lo que todavía no hemos construido, sin plazos asociados:

• La autenticación es obligatoria. Las solicitudes anónimas a https://beancount.io/prices/<ALIAS> te redirigirán a una página de inicio de sesión.
• Sin soporte para la CLI local. La CLI local bea lee archivos del disco, lo que significa que un include de URL fallará localmente como un glob de archivo no coincidente. Añadir soporte de cargador a la CLI está en nuestro roadmap.
• Sin superficie de API. Actualmente no tenemos un campo REST, GraphQL o MCP para precios gestionados.
• Sin panel de UI. Todavía no hay una pantalla de "conectar un feed" ni una etiqueta de frescura en la UI. (Los datos de frescura que calcula nuestro motor actualmente no tienen dónde mostrarse).
• Sin snapshots, exportaciones ni endpoints de refresco manual.

Lo que hemos publicado hoy es estrictamente la capa del motor: resolución de includes, validación, caché de revisiones, reglas de precedencia y cálculo de frescura. Es la infraestructura fundacional sobre la que tiene que apoyarse todo lo demás, que es exactamente por lo que la construimos primero.

Dónde mirar a continuación​

Ambos libros contables incrustados arriba forman parte de nuestra galería de ejemplos: seis patrones completamente desarrollados que puedes clonar y ejecutar localmente. (Ambos se distribuyen intencionadamente con archivos de precios estáticos incluidos en el repositorio, lo que garantiza que una clonación hecha dentro de dos años produzca exactamente el mismo informe que produce hoy). Todo lo demás que publicamos aterriza directamente en nuestro changelog.

Si estás perfectamente contento manteniendo los precios al día con tu propio fetcher, sigue con él. Sigue siendo la mejor respuesta para un libro contable estrictamente local. La propia documentación de obtención de precios de Beancount y la herramienta mantenida beanprice son los mejores lugares para empezar.

Mantén aburrida la parte aburrida​

Merece la pena automatizar los precios precisamente porque son la única parte de un libro contable de texto plano que se pudre con el tiempo. Beancount.io está construido para darte contabilidad de texto plano que sigue siendo tuya: auditable, controlada por versiones y nunca reescrita a tus espaldas. Ese era el estándar básico que un feed gestionado tenía que cumplir antes de que estuviéramos dispuestos a publicarlo.

Empieza gratis y mantén tus libros en archivos que puedas leer de verdad.