Glosario de Beancount y contabilidad en texto plano

La contabilidad de texto plano toma prestado vocabulario de la contabilidad por partida doble y añade un puñado de palabras propias de Beancount. Este glosario define los términos que encontrarás al leer esta documentación o tu propio archivo de libro mayor, cada uno con un breve ejemplo cuando resulta útil. Cada entrada tiene su propio enlace, para que puedas señalar directamente a un compañero la definición de un término.

Cuenta​

Una cuenta es un contenedor con nombre que registra un flujo de valor, escrito como una jerarquía separada por dos puntos bajo uno de los cinco tipos raíz: Assets, Liabilities, Equity, Income o Expenses. La jerarquía es toda la estructura organizativa de tus libros — Assets:US:BofA:Checking y Expenses:Food:Restaurant se ordenan y se agregan automáticamente. Cada cuenta debe declararse antes de usarse. Consulta Sintaxis del lenguaje Beancount para las reglas de nomenclatura.

Base devengada​

La contabilidad por base de acumulación registra los ingresos cuando se ganan y los gastos cuando se incurren, independientemente de cuándo se mueva realmente el efectivo. La contabilidad por base de caja hace lo contrario: reconoce ambos solo cuando cambia de manos el dinero. La base de acumulación ofrece una imagen más fiel del desempeño de un período, por lo que una factura que enviaste en marzo pertenece a marzo aunque el cliente pague en mayo.

Amortización​

La amortización reparte un único pago grande entre los períodos que realmente cubre, de modo que cada mes soporta su parte justa del coste. Una prima de seguro anual pagada en enero es un gasto de los doce meses, no solo de enero. En Beancount puedes escribir los asientos divididos a mano o generarlos con un plugin — consulta Amortizar.

Verificación de saldo​

Una aserción de saldo es una directiva balance que establece cuál debe ser el saldo de una cuenta al inicio de una fecha dada, de modo que tu extracto bancario se convierte en una verificación automática de tus libros. Si el saldo calculado difiere en más que la tolerancia de la aserción, Beancount falla de forma ruidosa indicando los importes esperado y real. Esa tolerancia es una unidad del último decimal que escribiste — 4.27 RGAGX acepta cualquier valor entre 4.26 y 4.28 — y un ~ antes de la divisa establece la tuya propia. Sembrar una aserción por cuenta y por extracto es la forma más barata de mantener un libro mayor fiable.

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

Beancount​

Beancount es un sistema de contabilidad por partida doble de código abierto cuyo libro mayor es un archivo de texto plano que editas en cualquier editor de texto y validas con una herramienta de línea de comandos. Te ofrece una sintaxis estricta y parseable, un lenguaje de consulta y una interfaz web, sin base de datos ni formato de archivo propietario. Como el libro mayor es texto, convive felizmente en Git junto a tu código. Empieza con Introducción a Beancount.

Lenguaje de Consultas de Beancount​

El Lenguaje de consulta de Beancount, normalmente abreviado BQL, es el lenguaje similar a SQL que usas para hacer preguntas a tu libro mayor. Se ejecuta sobre las directivas parseadas en lugar de sobre una base de datos, así que SELECT account, sum(position) WHERE year = 2026 responde de inmediato desde el mismo archivo que editas. Lee la guía del lenguaje de consulta para la gramática completa.

Método de registro​

Un método de asignación es la regla que Beancount aplica cuando una reducción tiene que elegir qué lotes existentes consumir. Beancount 3.2.3 acepta siete nombres: STRICT (el predeterminado, en el que identificas el lote tú mismo), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO y AVERAGE. Configura uno por cuenta en su directiva open, o para todo el archivo con option "booking_method". Seis de los siete están implementados: AVERAGE se parsea, pero lanza AVERAGE method is not supported en el momento en que tiene que asignar una reducción. El método que elijas cambia tus ganancias de capital realizadas, así que escoge el que espere tu jurisdicción fiscal y mantenlo estable. Gestión de inventarios ejecuta los siete sobre los mismos lotes y publica el libro mayor que falla con AVERAGE.

Plan de cuentas​

Un catálogo de cuentas es la lista completa de cuentas que usa tu libro mayor, junto con la estructura que las organiza. En Beancount no hay un archivo de catálogo separado — el conjunto de directivas open es tu catálogo de cuentas. Diseñarlo bien desde el principio ahorra muchos renombrados después; consulta Configuraciones específicas por industria para puntos de partida.

Directiva de cierre​

Una directiva close marca la fecha a partir de la cual una cuenta ya no puede usarse, que es como retiras una cuenta bancaria o un préstamo pagado sin eliminar su historial. Las transacciones pasadas siguen siendo válidas y reportables; solo se rechazan los asientos nuevos. Cerrar cuentas sin uso mantiene legibles los informes a medida que envejece un libro mayor.

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

Commodity​

Una commodity es cualquier unidad de valor que registre tu libro mayor — una divisa como USD, un ticker bursátil como AAPL, un criptoactivo como BTC o algo que inventes como VACATION-DAYS. Beancount nunca convierte entre commodities a tus espaldas, así que un importe siempre es un número emparejado con la commodity en la que está denominado. Una directiva commodity opcional te permite adjuntar metadatos como un nombre o una clase de activo.

Base de costo​

La base de coste es lo que realmente pagaste por una posición, registrado en la divisa con la que pagaste y arrastrado junto a la posición mientras la poseas. Beancount la escribe entre llaves — 10 AAPL {150.00 USD} significa diez acciones adquiridas a 150 dólares cada una. Duplica las llaves y el número pasa a ser el total en lugar del precio unitario, así que 10 AAPL {{1,500.00 USD}} registra el mismo lote. Como la base viaja con la posición, las ganancias de capital salen de la aritmética al vender. Consulta Gestión de inventarios.

Directiva​

Una directiva es una instrucción en un archivo de Beancount, normalmente con fecha, y las directivas son de lo que está hecho un libro mayor. Doce tipos llevan fecha: open, close, balance, price, note, document, pad, event, commodity, custom, query y la propia transacción. Algunas no llevan ninguna y actúan sobre el archivo en lugar de sobre un día — option, include, plugin y el par pushtag/poptag. Beancount ordena las que llevan fecha antes de procesarlas, así que puedes mantener esas en el orden que mejor se lea; una sin fecha surte efecto donde está escrita.

Contabilidad de partida doble​

La contabilidad por partida doble es la práctica de registrar cada evento económico como al menos dos asientos que se corresponden, de modo que sus pesos siempre sumen cero. El dinero nunca se crea ni se destruye — solo se mueve entre cuentas, que es por lo que la técnica detecta errores que una lista de una sola columna jamás detectaría. Un peso es el importe propio de un asiento, o su coste o precio convertido de vuelta a una sola divisa, así que dos patas en distintas commodities aún se cancelan. Beancount aplica la regla de forma estricta: una transacción cuyos asientos no cuadran es un error, no una advertencia.

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

Presupuesto de sobres​

El presupuesto por sobres aparta dinero para un propósito antes de gastarlo, de modo que cada categoría tiene su propio límite en lugar de competir por un único saldo común. El nombre viene de los sobres de papel que la gente llenaba de efectivo el día de pago. En un libro mayor de texto plano modelas los sobres con cuentas dedicadas o directivas de presupuesto — consulta Presupuestos.

Fava​

Fava es la interfaz web para Beancount: gráficos, balances, cuentas de resultados, un editor de consultas y un formulario de entrada, servidos desde tu archivo de libro mayor. Es mayormente de lectura y se ejecuta localmente, así que cambia cómo ves tus libros sin cambiar cómo los registras. beancount.io aloja una versión gestionada junto a sus propias herramientas; la guía Funciones de la interfaz cubre lo que puedes hacer allí.

Existencias​

Un inventario es el conjunto de posiciones que mantiene actualmente una cuenta, cada una con su propia commodity y, cuando corresponde, su propia base de coste y fecha de adquisición. Una cuenta de corretaje que compró la misma acción tres veces mantiene tres lotes separados en un inventario, no un único número combinado. Mantener los lotes distintos es lo que hace posible calcular las ganancias con precisión.

Diario​

El diario es la lista cronológica de todo lo que ocurrió en tus libros — el flujo bruto de transacciones, en orden de fecha, antes de cualquier agrupación o resumen. Es la vista que recorres cuando quieres responder «¿qué hice realmente en marzo?». La página de diario de Fava suele ser el lugar más rápido para detectar un asiento mal categorizado.

Libro mayor​

Un libro mayor es el conjunto completo de registros contables de una entidad, que en Beancount significa tu archivo de texto plano (más todo lo que incluya). La palabra sirve tanto de nombre para todo el libro de cuentas como de nombre para el propio archivo. Como es texto, un libro mayor puede compararse con diffs, revisarse, ramificarse y fusionarse como el código fuente.

Lote​

Un lote es una adquisición concreta de una commodity, identificada por su base de coste y su fecha de adquisición. Comprar el mismo ETF en enero y de nuevo en junio crea dos lotes, y vender después implica elegir qué lote estás vendiendo. Los lotes son la razón por la que Beancount puede calcular las ganancias realizadas con exactitud en lugar de aproximarlas.

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

Narración​

La narración es la descripción en texto libre de para qué era una transacción, escrita como la segunda cadena entre comillas en la línea de la transacción. Es para humanos: «Alquiler mensual», «Comestibles y artículos del hogar». Beancount no la parsea, pero es lo que leerás cuando el asiento ya no tenga sentido dentro de seis meses.

Directiva de apertura​

Una directiva open declara una cuenta, la fecha en que empieza a poder usarse y, opcionalmente, las commodities que puede contener y el método de asignación que usa. Beancount exige que cada cuenta se abra antes de su primer asiento, que es lo que evita que un error tipográfico cree silenciosamente una cuenta totalmente nueva. Restringir las commodities permitidas convierte otra clase entera de errores en errores propiamente dichos.

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

Pad​

Una directiva pad le dice a Beancount que inserte el importe que sea necesario para que la siguiente aserción de saldo de una cuenta tenga éxito, registrando la diferencia en una segunda cuenta. Existe para exactamente un propósito: abrir un libro mayor a mitad de su vida sin reconstruir años de historial. Usar pad más allá de esa configuración inicial suele significar que se está tapando un error real.

Beneficiario​

El beneficiario es con quién hiciste la transacción, escrito como la primera cadena entre comillas en una línea de transacción. Mantener los beneficiarios consistentes — siempre "Whole Foods", nunca a veces "WholeFoods" — es lo que hace que funcionen los informes por beneficiario y los importadores automatizados. Beancount trata al beneficiario como opcional; una transacción puede llevar solo una narración.

Contabilidad de texto plano​

La contabilidad de texto plano es la práctica de mantener tus libros en un archivo de texto legible por humanos bajo control de versiones, procesado por herramientas de línea de comandos de código abierto. Cambia una interfaz de apuntar y hacer clic por durabilidad, auditabilidad y automatización: tus datos sobreviven a cualquier proveedor, cada cambio es un diff revisable y cualquier script puede leerlos. Beancount, Ledger y hledger son las tres implementaciones más conocidas.

Plugin​

Un plugin es un módulo de Python que Beancount carga mientras procesa tu archivo, lo que le permite añadir, transformar o validar directivas antes de construir los informes. Los plugins son la forma en que se implementan los pronósticos, los calendarios de amortización y las comprobaciones personalizadas sin cambiar el lenguaje central. Se habilita uno con una línea plugin independiente al inicio de tu libro mayor, nunca con una option — option "plugin" "…" se rechaza con Option 'plugin' may not be set. La guía Plugin de pronóstico recorre un ejemplo real.

Asiento​

Un asiento es una pata de una transacción: una cuenta, un importe y, opcionalmente, un coste o un precio. Lo que tiene que sumar cero a lo largo de una transacción no son los importes brutos sino sus pesos: un importe simple se pesa a sí mismo, 10 FUND @ 38.46 USD pesa 384.60 USD, y 10 FUND {384.61 USD} pesa 3,846.10 USD, porque las llaves simples contienen el coste de una unidad. Como máximo un asiento puede dejar su importe en blanco, en cuyo caso Beancount calcula por ti la cifra compensatoria. Consulta Precisión y tolerancias para todas las reglas de pesos.

Directiva de precio​

Una directiva price registra el tipo de cambio entre dos commodities en una fecha, que es como Beancount convierte una posición a su valor de mercado en los informes. Una directiva price es puro dato de referencia: no mueve dinero y no pertenece a ninguna transacción. No la confundas con el precio @ escrito dentro de un asiento, que es aritmética — da a 10 FUND @ 38.46 USD un peso de 384.60 USD y por tanto decide si la transacción cuadra. Sin directivas de precio, una cartera sigue cuadrando a coste pero no puede valorarse a mercado.

2026-06-30 price VTI   271.40 USD

Precios en vivo proporciona directivas de precio gestionadas para los activos compatibles en libros mayor alojados. Tu propio precio prevalece para la misma fecha y par, incluido el par recíproco. Un precio gestionado en una fecha posterior puede seguir aplicándose a una valoración posterior.

Conciliación​

La conciliación es el acto de demostrar que tus libros coinciden con un registro externo, como un extracto bancario o de corretaje. En la contabilidad de texto plano es en gran medida mecánica: añade una aserción de saldo para cada fecha de extracto y deja que la herramienta te diga si los números coinciden. Un libro mayor que concilia limpiamente cada mes es uno con el que puedes presentar impuestos sin miedo.

Etiquetas y enlaces​

Las etiquetas y los enlaces son las dos marcas que adjuntas a las transacciones para agruparlas fuera de la jerarquía de cuentas: una etiqueta con # marca un tema como #trip-japan, y un enlace con ^ une entradas relacionadas como ^invoice-2026-014. Las etiquetas responden a «muéstrame todo lo de esta categoría»; los enlaces responden a «muéstrame las entradas que pertenecen a este único evento». Ambas son filtrables en Fava y consultables en BQL — consulta Filtrado y búsqueda.

Transacción​

Una transacción es un evento económico con fecha junto con los asientos que lo registran, y es la directiva que escribirás con más frecuencia. Lleva una marca (* para confirmada, ! para necesita revisión), un beneficiario opcional, una narración y dos o más asientos cuyos pesos suman cero. Todo lo demás en un archivo de Beancount existe para declarar, comprobar o anotar transacciones.

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

¿Sigues atascado en una palabra? El Centro de ayuda indexa todas las guías de este sitio, y la Chuleta pone la sintaxis de cada directiva una junto a otra.