Qué es Beancount: contabilidad de doble entrada en texto

Esta guía sintetiza las mejores prácticas para la contabilidad en texto plano usando Beancount, una potente herramienta de contabilidad en texto plano de código abierto. Cubre la filosofía fundacional, la sintaxis de básica a avanzada, casos prácticos para activos complejos y estrategias de gestión de libros a largo plazo.

Parte 1: El "Por Qué" - Fundamentos de una Contabilidad Inteligente​

Antes de sumergirse en el "cómo", es crucial entender el "por qué". Una contabilidad eficaz es la base de la gestión financiera personal y un paso necesario hacia la claridad y la libertad financieras.

Más Allá del Seguimiento de Gastos: El Camino hacia la Claridad Financiera​

Las aplicaciones sencillas de seguimiento de gastos te dicen a dónde fue tu dinero. Un sistema contable robusto te dice eso y mucho más: proporciona una imagen completa de tu salud financiera, incluyendo tu patrimonio neto, tu flujo de caja y el rendimiento de tus inversiones. El objetivo principal es la observabilidad: obtener una comprensión clara y basada en datos de tu vida financiera, que te permita tomar decisiones informadas, evaluar el riesgo y avanzar hacia metas a largo plazo como la jubilación.

¿Por Qué Partida Doble? El Poder de un Sistema Equilibrado​

A diferencia de la contabilidad por partida simple (una simple lista de gastos), el método de partida doble registra cada transacción como un flujo de valor entre al menos dos cuentas. Su principio fundamental es la ecuación contable básica:

$\text{Activos} = \text{Pasivos} + \text{Patrimonio (Valor Neto)}$

Este sistema garantiza que tus libros estén siempre cuadrados, reduciendo drásticamente los errores. Proporciona una imagen financiera completa al generar informes esenciales como el Balance General (lo que posees y debes) y el Estado de Resultados (lo que has ganado y gastado).

Parte 2: Primeros Pasos con Beancount​

Beancount es una potente herramienta basada en Python para la contabilidad en texto plano.

Tu Primer Vistazo con Fava en Beancount.io​

Beancount.io ofrece un entorno potente que combina el motor de Beancount con una aplicación móvil (iOS, Android) y una aplicación web: Fava, una fantástica interfaz web para visualizar tu libro. No se necesita instalación. Cuando usas la plataforma, interactúas directamente con un editor de texto para tu archivo de libro (por ejemplo, main.bean) y ves los informes generados por Fava actualizarse en tiempo real.

Fava toma el texto plano que escribes y lo convierte en gráficos interactivos, estados financieros y listas de transacciones filtrables, dándote una visión clara de tus informes financieros.

O Comienza en la Terminal con bea​

Si prefieres trabajar desde una shell, bea es la línea de comandos de Beancount.io. No se necesita cuenta: instálala con brew install bex-co/tap/bea o uv tool install beancount-io, y crea, valida, consulta y genera informes sobre el mismo archivo de texto plano. El inicio rápido de la CLI te consigue un primer libro en unos minutos, y Tu primer mes con bea cierra un mes completo de principio a fin.

Los Cinco Tipos de Cuenta Principales​

Beancount usa cinco tipos de cuenta de nivel superior, que forman la estructura de tu libro:

La Ecuación de Beancount​

Beancount aplica su propia versión de la ecuación contable, en la que la suma de todos los apuntes de todo tu libro es igual a cero:

$\text{Activos} + \text{Gastos} + \text{Pasivos} + \text{Ingresos} + \text{Patrimonio} = 0$

Por eso, por convención, las cuentas de Income, Liabilities y Equity tienen valores negativos: son las fuentes de fondos que incrementan tus Assets y Expenses.

Parte 3: El Lenguaje de Beancount - Sintaxis Básica​

Todas las entradas de Beancount son directivas que comienzan con una fecha.

Definiendo Cuentas (open) y Commodities​

Antes de poder usar una cuenta, debes declararla con la directiva open. También puedes especificar opcionalmente las monedas o "commodities" que contendrá.

; YYYY-MM-DD open Account:Name [Commodity1, Commodity2, ...]
2020-01-01 open Assets:Bank:US:Chase:Checking      USD
2020-01-01 open Liabilities:CreditCard:US:Discover USD
2020-01-01 open Expenses:Food:Groceries
2020-01-01 open Income:Salary:Google

Las commodities pueden ser monedas del mundo real (por ejemplo, USD, JPY) o cualquier unidad personalizada que definas, como millas de aerolíneas (MILES_UA) o tickers de acciones (HOOL).

Registrando Tu Primera Transacción (*)​

Las transacciones son la entrada más común. Comienzan con una fecha, una bandera (* para una transacción completa o ! para una incompleta), un beneficiario opcional y una descripción. Cada línea que sigue (indentada con dos espacios) es un "apunte" a una cuenta.

; YYYY-MM-DD * "Payee" "Description"
;   Account1      Amount Commodity
;   Account2     -Amount Commodity
 
2024-07-28 * "Trader Joe's" "Weekly groceries"
  Expenses:Food:Groceries     125.50 USD
  Liabilities:CreditCard:US:Discover  -125.50 USD

Por comodidad, si una transacción tiene solo dos apuntes, puedes omitir el importe en la segunda línea, y Beancount lo calculará automáticamente.

2024-07-28 * "Trader Joe's" "Weekly groceries"
  Expenses:Food:Groceries     125.50 USD
  Liabilities:CreditCard:US:Discover

Cuadre a nivel de transacción: Más importante para el uso diario, cada transacción individual también debe cuadrar: la suma de todos los apuntes dentro de una sola transacción debe ser igual a cero. Si una transacción no cuadra, Beancount mostrará un error como este:

Manejo de Transacciones en Múltiples Divisas (@ y @@)​

Beancount destaca en la contabilidad multidivisa.

• Usa @ para especificar un precio de conversión por unidad.
• Usa @@ para especificar el costo total de la conversión.

; Buying a flight in EUR with a USD card
2024-08-01 * "Lufthansa" "Flight to Berlin"
  Expenses:Travel:Flights      500.00 EUR @@ 545.00 USD  ; 500 EUR cost me 545 USD in total
  Liabilities:CreditCard:US:Discover  -545.00 USD

Parte 4: Garantizando la Precisión - El Arte de la Conciliación​

Una práctica clave para mantener un libro preciso es la conciliación regular. Esto implica comparar los saldos de tu libro de Beancount con los extractos oficiales de tus instituciones financieras.

Automatizando Comprobaciones con Aserciones de Saldo (balance)​

La directiva balance es tu herramienta principal para las comprobaciones automatizadas. Afirmas que en una fecha determinada, una cuenta tenía un saldo específico. Beancount generará un error si su saldo calculado no coincide con tu aserción. Esto es invaluable para localizar errores rápidamente.

Nota: La aserción de saldo comprueba el estado de la cuenta al comienzo del día especificado (antes de cualquier transacción de ese día).

; From your monthly credit card statement
2024-08-01 balance Liabilities:CreditCard:US:Discover  -1432.78 USD

Vinculando Documentos de Apoyo (document)​

Puedes enlazar archivos externos como extractos bancarios o recibos, creando un rastro auditable. Fava hace que estos enlaces sean clicables.

2024-08-01 document Liabilities:CreditCard:US:Discover "statements/discover-2024-07.pdf"

Corrigiendo Errores e Inicializando Saldos​

Cuando comienzas tu libro o encuentras una discrepancia que no puedes rastrear, necesitas hacer un ajuste. La práctica estándar es usar una cuenta especial de Equity.

; Initializing a cash account when starting your ledger
2020-01-01 * "Initial Balance" "Setting up cash account"
  Assets:Cash:Wallet           200.00 USD
  Equity:Opening-Balances     -200.00 USD

La cuenta Equity:Opening-Balances contiene importes que entran en tu libro desde fuentes desconocidas o externas.

Para arreglos rápidos en los que la discrepancia exacta no es importante, la directiva pad puede ajustar automáticamente el saldo de una cuenta para cumplir con una aserción balance posterior, registrando la diferencia en una cuenta de patrimonio. Úsala con precaución, ya que puede ocultar problemas mayores. Los ajustes explícitos suelen ser más seguros.

Parte 5: Patrones de Transacción Avanzados y Realistas​

Seguimiento de Deudas: Gestión de Cuentas por Cobrar y Pagar​

La contabilidad de partida doble es perfecta para hacer seguimiento del dinero que te deben (Assets:Receivables) o que debes (Liabilities:Payable).

Ejemplo: Pagas una cena en grupo de $90, y tu amigo Bob te debe su parte de $45.

1. Registrar el gasto inicial y la cuenta por cobrar:

   2024-08-05 * "Dinner Place" "Dinner with Bob"
     Expenses:Food:Restaurant          45.00 USD  ; Your share
     Assets:Receivables:Bob            45.00 USD  ; Bob owes you
     Assets:Bank:US:Chase:Checking    -90.00 USD

2. Cuando Bob te devuelve el dinero:

   2024-08-06 * "Bob" "Paid me back for dinner"
     Assets:Bank:US:Chase:Checking     45.00 USD
     Assets:Receivables:Bob           -45.00 USD

La cuenta Assets:Receivables:Bob ahora está a cero, y tus libros están perfectamente cuadrados.

Activos vs. Gastos: Compra de un Coche y Depreciación​

Una compra grande como un coche no es un simple gasto; es la adquisición de un activo que pierde valor con el tiempo (depreciación).

1. Registrar la compra como un activo:

   2023-01-15 * "Toyota Dealer" "Purchase of a new car"
     Assets:Car:ToyotaCamry         30000.00 USD
     Assets:Bank:US:Chase:Checking -30000.00 USD

2. Registrar la depreciación anual: Supón que estimas que el coche pierde $3,000 de valor cada año. Al final del año, registras esto como un gasto.

   2023-12-31 * "Depreciation" "Annual car value depreciation"
     Expenses:Depreciation:Car      3000.00 USD
     Assets:Car:ToyotaCamry        -3000.00 USD

Después de esta entrada, tu cuenta Assets:Car:ToyotaCamry refleja correctamente el nuevo valor del coche ($27,000), y has contabilizado adecuadamente el costo de uso como gasto de ese año.

Parte 6: Inmersión Profunda - Modelando Activos Complejos del Mundo Real​

Caso de Estudio 1: Contabilidad para Bienes Raíces​

Una casa suele ser tu activo y pasivo más grande. Así es como modelarla.

1. Crear cuentas y una commodity personalizada:

   2022-01-01 commodity HOUSE_123MAIN
     name: "Property at 123 Main St"
   2022-01-01 open Assets:Property:Home:123Main        HOUSE_123MAIN
   2022-01-01 open Liabilities:Mortgage:HomeLoan       USD
   2022-01-01 open Expenses:Home:Interest
   2022-01-01 open Expenses:Home:PropertyTax

2. Registrar la compra: Supongamos que compras una casa de $500k con un pago inicial de $100k y un préstamo de $400k.

   2022-03-15 * "Settlement Company" "Purchase of 123 Main St"
     Assets:Property:Home:123Main          1 HOUSE_123MAIN {500000.00 USD}
     Assets:Bank:DownPayment          -100000.00 USD
     Liabilities:Mortgage:HomeLoan    -400000.00 USD

3. Registrar los pagos mensuales de la hipoteca: Tu pago mensual se compone del principal (reduce el pasivo) y los intereses (un gasto).

   2022-04-01 * "Mortgage Bank" "Monthly Mortgage Payment"
     Liabilities:Mortgage:HomeLoan      800.00 USD   ; Principal
     Expenses:Home:Interest            1200.00 USD   ; Interest
     Assets:Bank:US:Chase:Checking    -2000.00 USD

4. Seguimiento de la apreciación (ganancias no realizadas): El valor de mercado de una casa cambia. Para hacer seguimiento de esto sin afectar tu patrimonio neto oficial (ya que la ganancia no se realiza hasta que vendes), puedes usar una directiva de precio con una moneda "virtual".

   Para activos de mercado y pares de divisas compatibles, Live Prices puede mantener cotizaciones de valoración en un libro alojado. Las propiedades individuales todavía necesitan tus propias tasaciones y precios con fecha, como en el ejemplo siguiente.

   ; The purchase price is the real cost basis
   2022-03-15 price HOUSE_123MAIN   500000.00 USD
    
   ; An updated market estimate is an unrealized gain
   2024-01-01 price HOUSE_123MAIN   550000.00 USD.UNREALIZED

Esto te permite ver el valor estimado en los gráficos de Fava sin inflar indebidamente tu balance general.

Explora un libro de ejemplo de bienes raíces en vivo con seguimiento de hipoteca, depreciación y venta de propiedad:

Caso de Estudio 2: Seguimiento de Unidades de Acciones Restringidas (RSUs)​

Las RSU son una forma común de compensación en acciones. Su contabilidad implica hacer seguimiento de la concesión inicial, los eventos de consolidación y la retención de impuestos.

1. Configuración inicial: Crea commodities para las acciones consolidadas (HOOL) y no consolidadas (HOOL.UNVEST), junto con cada cuenta que toquen las entradas posteriores. Declararlas todas de antemano es lo que hace que las dos transacciones siguientes se carguen por sí solas.

   2021-01-01 commodity HOOL
   2021-01-01 commodity HOOL.UNVEST
   2021-01-01 open Assets:Brokerage:Etrade:HOOL          HOOL
   2021-01-01 open Assets:Grant:Unvested                 HOOL.UNVEST
   2021-01-01 open Income:Grant:Awards                   HOOL.UNVEST
   2021-01-01 open Expenses:Grant:Vested                 HOOL.UNVEST
   2021-01-01 open Income:Salary:Hooli:RSU               USD
   2021-01-01 open Expenses:Taxes:Federal                USD
   2021-01-01 open Expenses:Taxes:State                  USD

2. Registrar la concesión inicial: Esta transacción muestra la concesión total moviéndose a una cuenta de activo no consolidado. Todavía no hay nada sujeto a impuestos, así que toda la entrada está denominada en la commodity de seguimiento HOOL.UNVEST.

   2021-02-01 * "Hooli" "Initial RSU Grant"
     Assets:Grant:Unvested        1000 HOOL.UNVEST
     Income:Grant:Awards         -1000 HOOL.UNVEST

3. Registrar un evento de consolidación: Esta es la transacción clave. Cuando las acciones se consolidan, reconoces un ingreso, el empleador retiene acciones para pagar el impuesto, y tú te quedas con el resto. Supón que 100 acciones se consolidan a $150.00, entonces:

   • Compensación bruta: 100 × $150.00 = $15,000.00
   • Acciones retenidas para impuestos: 40 × $150.00 = $6,000.00 (federal $4,800.00 + estatal $1,200.00)
   • Acciones que conservas: 60 × $150.00 = $9,000.00 de base de costo
   • Efectivo para ti: $0.00 — toda la retención se paga en acciones

   Esos importes son la entrada, y cuadran: $6,000.00 de impuestos más $9,000.00 de acciones retenidas es exactamente los $15,000.00 de ingreso.

   2022-02-01 * "Hooli" "RSU Vesting Event"
     ; Ordinary income: 100 shares * $150.00
     Income:Salary:Hooli:RSU                   -15000.00 USD
     ; Tax withheld, funded by 40 of the 100 shares (40 * $150.00 = $6,000.00)
     Expenses:Taxes:Federal                      4800.00 USD
     Expenses:Taxes:State                        1200.00 USD
     ; The 60 shares you keep, at their $150.00 vesting-day basis
     Assets:Brokerage:Etrade:HOOL                  60 HOOL {150.00 USD}
     ; Retire the 100 unvested units the grant was tracking
     Assets:Grant:Unvested                       -100 HOOL.UNVEST
     Expenses:Grant:Vested                        100 HOOL.UNVEST

Esta única transacción cuadrada modela todo el evento: la concesión no consolidada se reduce, se reconoce el ingreso, se retienen impuestos, y las 60 acciones netas consolidadas aparecen en tu cuenta de corretaje con la base de costo correcta para futuros cálculos de ganancias de capital.

Vale la pena copiar dos detalles en tu propio libro. Primero, escribe la retención cuenta por cuenta en lugar de dejar que una cuenta de cuadre general la absorba — si los apuntes federal y estatal no suman el valor de las acciones retenidas, la transacción no cuadrará y Beancount te lo dirá. Segundo, no dejes una línea en blanco entre apuntes: una línea en blanco termina la transacción, y Beancount reporta un error de sintaxis en los apuntes que la siguen.

Si tu empleador vende las acciones retenidas en el mercado abierto en lugar de recuperarlas al precio de consolidación, la venta es una transacción separada — una reducción de Assets:Brokerage:Etrade:HOOL contra efectivo — y cualquier diferencia entre el precio de venta y la base de $150.00 es una pequeña ganancia o pérdida de capital. Mantenla fuera de la entrada de consolidación.

Parte 7: Gestión de Proyectos para Tu Libro Mayor​

A medida que tu libro crece, la organización se vuelve clave.

Usando Control de Versiones (Git) para Proteger Tus Datos​

Dado que tu libro es un archivo de texto, es perfecto para el control de versiones con Git. Esto te da un historial completo de todos los cambios, protegiéndote de borrados o errores accidentales. Advertencia: Tus datos financieros son altamente sensibles. Usa un repositorio privado en servicios como GitHub/GitLab, o aloja el tuyo propio.

Organizando con Etiquetas (#) y Enlaces (^)​

Beancount ofrece dos formas de agrupar transacciones más allá de las cuentas:

• Etiquetas (#): Úsalas para eventos o proyectos. Puedes filtrar todas las transacciones relacionadas con un viaje específico, por ejemplo. 2024-07-20 * "Hotel" "Vienna" #trip-europe-2024
• Enlaces (^): Úsalos para conectar transacciones financieramente relacionadas que ocurren en momentos diferentes, como un retiro de efectivo y la comisión bancaria asociada.

Una Estrategia Escalable para Estructurar Tus Archivos (include)​

Un único archivo enorme es difícil de manejar. Usa la directiva include para dividir tu libro en múltiples archivos. main.bean:

; Main ledger file
 
; Global options
option "title" "My Personal Ledger"
option "operating_currency" "USD"
 
; Include account declarations and other files
include "accounts.bean"
include "years/2023.bean"
include "years/2024.bean"
include "events/trip-europe-2024.bean"

Una estrategia de organización robusta, en orden de precedencia:

1. Por evento: Crea un archivo separado para un evento importante y autónomo (por ejemplo, trip-europe-2024.bean).
2. Por categoría/beneficiario: Para transacciones muy regulares y recurrentes como facturas de servicios o salario, agrúpalas en su propio archivo (por ejemplo, recurring-rent.bean).
3. Por cuenta: Para transacciones estrechamente vinculadas a una cuenta específica (intereses, comisiones, pagos de tarjeta de crédito), considera un archivo específico de cuenta.
4. Por fecha: Para todas las demás transacciones generales, una simple división por año (2024.bean) o mes (2024/07.bean) es efectiva.

Parte 8: Conclusión​

Beancount ofrece una curva de aprendizaje pronunciada pero recompensa el esfuerzo con un poder, flexibilidad y control incomparables sobre tus datos financieros. Al adoptar los principios de la contabilidad de partida doble y las herramientas prácticas que ofrece Beancount, puedes pasar del simple seguimiento de gastos a un sistema completo, preciso y revelador de gestión financiera personal. Tu libro se convierte en un activo permanente, privado e invaluable para entender tu pasado y planificar tu futuro.

Primeros Pasos con Beancount.io​

Beancount.io es una plataforma moderna de gestión financiera basada en la nube que transforma tus registros de transacciones basados en texto en estados financieros completos, incluyendo estados de resultados, balances generales y balances de comprobación. Al combinar la fiabilidad de los archivos de texto plano con potentes herramientas de visualización, Beancount.io te ayuda a mantener un control preciso sobre tu vida financiera mientras obtienes información valiosa sobre el rendimiento de tus inversiones.

Comienza tu viaje financiero con Beancount.io — consulta los planes y precios actuales para saber qué incluye cada nivel.

Explora el libro en vivo →

Explora el libro en vivo →

Explora el libro en vivo →