Plugins nativos esenciales de Beancount que debes conocer

2 de enero de 2026 · 11 min de lectura

Mike Thrift

Marketing Manager

El poder de Beancount no reside solo en su formato de texto plano, sino en su extensibilidad a través de complementos (plugins). Los complementos nativos son módulos integrados que mejoran la funcionalidad de Beancount, automatizan tareas tediosas y aplican las mejores prácticas contables. En esta guía completa, exploraremos todos los complementos nativos disponibles en Beancount y cómo utilizarlos de manera efectiva.

¿Qué son los complementos de Beancount?

Los complementos de Beancount son módulos de Python que procesan las entradas de su libro mayor para añadir capacidades de automatización, validación o transformación. Se ejecutan durante la fase de carga de su archivo de libro mayor y pueden:

Automatizar tareas repetitivas (p. ej., crear declaraciones de cuentas)
Validar la integridad de los datos (p. ej., verificar transacciones duplicadas)
Transformar entradas (p. ej., generar entradas de precios a partir de transacciones)
Aplicar reglas contables (p. ej., una sola materia prima por cuenta)

Cómo usar complementos

Para habilitar un complemento en su archivo Beancount, añada una directiva plugin en la parte superior de su libro mayor:

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"

Algunos complementos aceptan opciones de configuración:

plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"

Categorías de complementos nativos

Los complementos nativos de Beancount se dividen en cuatro categorías principales:

1. Complementos de automatización

2. Complementos de validación

3. Complementos de transformación

4. Meta-complementos

1. Complementos de automatización

Estos complementos automatizan tareas repetitivas de contabilidad, ahorrándole tiempo y reduciendo los errores manuales.

`auto_accounts` - Declaraciones automáticas de cuentas

Qué hace: Inserta automáticamente directivas Open para las cuentas que aparecen en las transacciones pero que no han sido declaradas explícitamente.

Por qué usarlo: Elimina la necesidad de declarar manualmente cada cuenta antes de usarla. Es perfecto para comenzar rápidamente o para usuarios que prefieren un código base mínimo.

Ejemplo:

plugin "beancount.plugins.auto_accounts"

2026-01-01 * "Coffee shop"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

Sin el complemento, tendría que añadir manualmente:

2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash

Cuándo usarlo: Ideal para principiantes o para aquellos que desean un libro mayor menos detallado. Sin embargo, las declaraciones de cuenta explícitas pueden ayudar a detectar errores tipográficos.

`close_tree` - Cierre automático de la jerarquía de cuentas

Qué hace: Cuando cierra una cuenta principal, este complemento cierra automáticamente todas sus cuentas descendientes.

Por qué usarlo: Mantiene la coherencia en su jerarquía de cuentas. Si cierra Assets:Investments, todas las subcuentas como Assets:Investments:Stocks y Assets:Investments:Bonds se cerrarán automáticamente.

Ejemplo:

plugin "beancount.plugins.close_tree"

2025-06-30 close Assets:Investments

; Estas se cerrarán automáticamente:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

Cuándo usarlo: Al reestructurar su jerarquía de cuentas o al cerrar categorías completas de cuentas.

`implicit_prices` - Generación automática de entradas de precios

Qué hace: Sintetiza directivas Price a partir de los apuntes de transacciones que incluyen costes (@) o precios (@@).

Por qué usarlo: Alimenta su base de datos de precios automáticamente a partir de sus transacciones, lo que permite informes precisos del valor de mercado sin entradas de precios manuales.

Ejemplo:

plugin "beancount.plugins.implicit_prices"

2026-01-02 * "Buy AAPL shares"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

Esto genera automáticamente:

2026-01-02 price AAPL  150.00 USD

Cuándo usarlo: Esencial para el seguimiento de inversiones y la contabilidad multidivisa donde se desea un historial de precios automático.

2. Complementos de validación

Estos complementos aplican la integridad de los datos y las mejores prácticas contables, detectando errores antes de que se conviertan en problemas.

`noduplicates` - Detección de transacciones duplicadas

Qué hace: Verifica que no existan dos transacciones idénticas calculando y comparando hashes de los datos de las transacciones.

Por qué usarlo: Evita entradas duplicadas accidentales, especialmente al importar transacciones desde múltiples fuentes.

Ejemplo:

plugin "beancount.plugins.noduplicates"

2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

; Esto activaría un error:
2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

Cuándo usarlo: Siempre recomendado, especialmente si está importando desde extractos bancarios o utilizando múltiples fuentes de datos.

`check_commodity` - Validación de declaración de materias primas (commodities)

Qué hace: Asegura que todas las materias primas utilizadas en su libro mayor tengan las directivas Commodity correspondientes.

Por qué usarlo: Obliga a realizar declaraciones explícitas de materias primas, ayudándole a mantener una lista limpia de activos y divisas.

Ejemplo:

plugin "beancount.plugins.check_commodity"

2015-01-01 commodity USD
2020-01-01 commodity AAPL

; Esto activaría un error sin una declaración de commodity:
2026-01-02 * "Buy Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

Cuándo usarlo: Recomendado para mantener un seguimiento estricto de las materias primas y evitar errores tipográficos en los símbolos de cotización (tickers).

`check_average_cost` - Validación de la Base de Costo

Qué hace: Verifica que la base de costo se preserve adecuadamente en las transacciones, especialmente cuando se utiliza la contabilización de costo promedio.

Por qué usarlo: Asegura que su contabilidad de costos se mantenga precisa para informes fiscales y cálculos de ganancias de capital.

Cuándo usarlo: Crítico para portafolios de inversión y cualquier escenario donde el seguimiento preciso del costo sea importante.

`check_closing` - Validación de Cierre de Saldo

Qué hace: Expande los metadatos de closing en verificaciones de saldo, asegurando que las posiciones queden en cero después de las operaciones de cierre.

Por qué usarlo: Confirma que cuando vende una posición completa, el saldo sea realmente cero (que no queden acciones fraccionarias).

Ejemplo:

plugin "beancount.plugins.check_closing"

2026-01-02 * "Close entire AAPL position" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15000.00 USD
  Income:Investments:Gains   -500.00 USD

La etiqueta #closing le indica al plugin que verifique que su posición de AAPL sea cero después de esta transacción.

Cuándo usarlo: Al vender posiciones completas para asegurar que no quede ningún remanente.

`coherent_cost` - Verificación de Consistencia de Divisa/Costo

Qué hace: Valida que las divisas no se usen de forma inconsistente — tanto con como sin anotaciones de costo.

Por qué usarlo: Evita mezclar divisas puras (como 100 USD) con divisas con costo (como 100 USD {1.2 CAD}), lo cual puede causar errores contables.

Cuándo usarlo: Recomendado para libros contables multidivisa para mantener la consistencia.

`leafonly` - Aplicación de Cuentas Hoja

Qué hace: Asegura que solo las cuentas hoja (cuentas sin subcuentas) reciban asientos.

Por qué usarlo: Impone una jerarquía de cuentas limpia donde las cuentas de resumen como Expenses:Food no tienen asientos directos, solo sus subcuentas como Expenses:Food:Groceries y Expenses:Food:Restaurants.

Ejemplo:

plugin "beancount.plugins.leafonly"

; This would trigger an error:
2026-01-02 * "Grocery shopping"
  Expenses:Food              50.00 USD  ; Error: Should post to a leaf account
  Assets:Cash               -50.00 USD

; Correct way:
2026-01-02 * "Grocery shopping"
  Expenses:Food:Groceries    50.00 USD  ; Correct: Posting to leaf account
  Assets:Cash               -50.00 USD

Cuándo usarlo: Cuando desee mantener una contabilidad jerárquica estricta con una categorización clara.

`nounused` - Detección de Cuentas sin Uso

Qué hace: Identifica cuentas que fueron abiertas pero nunca se usaron realmente en ninguna transacción.

Por qué usarlo: Le ayuda a limpiar sus declaraciones de cuentas e identificar posibles errores tipográficos o cuentas abandonadas.

Cuándo usarlo: Periódicamente, para auditar y limpiar su estructura de cuentas.

`onecommodity` - Un Instrumento por Cuenta

Qué hace: Obliga a que cada cuenta contenga solo un tipo de instrumento (commodity).

Por qué usarlo: Evita mezclar diferentes activos en la misma cuenta, lo cual es generalmente una mejor práctica contable.

Ejemplo:

plugin "beancount.plugins.onecommodity"

2026-01-02 * "Buy stocks"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD

; This would trigger an error:
2026-01-03 * "Buy more stocks"
  Assets:Investments         5 GOOGL @ 140 USD  ; Error: Different commodity
  Assets:Cash              -700.00 USD

Cuándo usarlo: Cuando prefiera una separación estricta de cuentas (una cuenta por cada acción/activo).

`sellgains` - Validación de Ganancias de Capital

Qué hace: Compara las ganancias de capital declaradas con las ganancias calculadas a partir de las ventas de lotes, asegurando que sus cálculos de pérdidas y ganancias sean precisos.

Por qué usarlo: Detecta errores en los cálculos manuales de ganancias de capital, algo crítico para informes fiscales precisos.

Ejemplo:

plugin "beancount.plugins.sellgains"

2026-01-02 * "Sell AAPL shares"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; Plugin validates this is correct

El plugin verificará: Ingresos por venta (1500) - Base de costo (1400) = Ganancias (100)

Cuándo usarlo: Esencial para cualquier persona que opere con acciones, criptomonedas u otros activos donde las ganancias de capital sean importantes.

`unique_prices` - Verificación de Unicidad de Precios

Qué hace: Asegura que solo haya una entrada de precio por instrumento por fecha.

Por qué usarlo: Evita datos de precios conflictivos que podrían dar lugar a valoraciones incorrectas.

Cuándo usarlo: Recomendado al ingresar precios manualmente o al importar desde múltiples fuentes de precios.

3. Plugins de Transformación

Estos plugins modifican o mejoran los datos de su libro contable de formas útiles.

`currency_accounts` - Cuentas de Intercambio de Divisas

Qué hace: Implementa cuentas de intercambio de divisas para rastrear conversiones de divisas de forma explícita.

Por qué usarlo: Proporciona un seguimiento detallado de las transacciones de conversión de divisas, útil para estándares contables que lo requieren.

Cuándo usarlo: Cuando necesite rastrear ganancias/pérdidas por cambio de divisas por separado o cumplir con requisitos contables específicos.

`commodity_attr` - Validación de Atributos de Instrumentos

Qué hace: Valida que las directivas de instrumentos (commodities) tengan los atributos requeridos (como export, name, etc.).

Por qué usarlo: Asegura que los metadatos de sus instrumentos estén completos y sean consistentes.

Cuándo usarlo: Cuando mantiene metadatos detallados de instrumentos para fines de informes o exportación.

4. Meta-Plugins

Estos plugins son colecciones de otros plugins para mayor comodidad.

`auto` - Todos los plugins automáticos

Qué hace: Activa una colección de plugins "flexibles" o automáticos en una sola directiva.

Cuándo usarlo: Configuración rápida para usuarios que desean la máxima automatización con la mínima configuración.

`pedantic` - Todos los plugins de validación

Qué hace: Activa todos los plugins de validación estricta a la vez.

Por qué usarlo: Impone la máxima integridad de datos y rigor contable. Ideal para libros mayores de producción o cuando la precisión es primordial.

Ejemplo:

plugin "beancount.plugins.pedantic"

; Esto es equivalente a activar:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

Cuándo usarlo: Para libros mayores de producción donde se desea la máxima validación y se está dispuesto a mantener prácticas contables más estrictas.

Configuraciones de plugins recomendadas

Para principiantes

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"

Este conjunto mínimo proporciona automatización al tiempo que evita errores comunes.

Para inversores

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_average_cost"
plugin "beancount.plugins.unique_prices"

Se centra en el seguimiento de inversiones y en la precisión de las ganancias de capital.

Para contabilidad estricta

plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"

Máxima validación para entornos de producción.

Configuración predeterminada en Beancount.io

En Beancount.io, incluimos el plugin auto_accounts por defecto en todos los nuevos archivos de libro mayor:

plugin "beancount.plugins.auto_accounts"

Esto proporciona un excelente equilibrio entre facilidad de uso y funcionalidad para comenzar rápidamente.

Mejores prácticas

Comience con lo mínimo, añada según sea necesario: Comience con auto_accounts y noduplicates, luego añada plugins de validación a medida que su libro mayor madure.
Pruebe los plugins individualmente: Al añadir varios plugins, actívelos uno a la vez para comprender sus efectos.
Lea los mensajes de error cuidadosamente: Los errores de los plugins a menudo señalan problemas contables reales que necesitan solución.
Use pedantic para producción: Una vez que su flujo de trabajo esté establecido, considere activar la validación estricta.
Combine con plugins personalizados: Los plugins nativos funcionan junto con plugins personalizados como el plugin de pronóstico para obtener la máxima funcionalidad.

Más allá de los plugins nativos

Si bien los plugins nativos proporcionan la funcionalidad principal, el ecosistema de Beancount incluye muchos plugins desarrollados por la comunidad para necesidades especializadas:

fava.plugins.forecast - Para el pronóstico de transacciones recurrentes
fava.plugins.link_documents - Para vincular transacciones con archivos de recibos
Importadores personalizados para formatos CSV específicos de bancos
Calculadoras e informes específicos de impuestos

Explore el ecosistema de Beancount para ver más opciones.

Conclusión

Los plugins nativos de Beancount transforman la contabilidad en texto plano de un proceso manual a un sistema de gestión financiera automatizado, validado y robusto. Al comprender y aprovechar estas herramientas integradas, usted puede:

✅ Automatizar tareas de contabilidad tediosas
✅ Detectar errores antes de que se conviertan en problemas
✅ Mantener una integridad de datos estricta
✅ Generar informes financieros precisos
✅ Centrarse en los conocimientos financieros en lugar de la entrada de datos

Comience a experimentar con estos plugins en su libro mayor hoy mismo. Empiece con auto_accounts e implicit_prices, y luego añada gradualmente plugins de validación a medida que sus prácticas contables maduren.

¿Listo para probar estos plugins? ¡Diríjase a Beancount.io y comience a usarlos en su archivo de libro mayor hoy mismo!

Fuentes

¿Tiene preguntas sobre los plugins de Beancount? Únase a la discusión en nuestro foro de la comunidad o consulte nuestra documentación.

References:

Share on Twitter Follow @beancount_io

¿Qué son los complementos de Beancount?​

Cómo usar complementos​

Categorías de complementos nativos​

1. Complementos de automatización​

2. Complementos de validación​

3. Complementos de transformación​

4. Meta-complementos​

1. Complementos de automatización​

auto_accounts - Declaraciones automáticas de cuentas​

close_tree - Cierre automático de la jerarquía de cuentas​

implicit_prices - Generación automática de entradas de precios​

2. Complementos de validación​

noduplicates - Detección de transacciones duplicadas​

check_commodity - Validación de declaración de materias primas (commodities)​

check_average_cost - Validación de la Base de Costo​

check_closing - Validación de Cierre de Saldo​

coherent_cost - Verificación de Consistencia de Divisa/Costo​

leafonly - Aplicación de Cuentas Hoja​

nounused - Detección de Cuentas sin Uso​

onecommodity - Un Instrumento por Cuenta​

sellgains - Validación de Ganancias de Capital​

unique_prices - Verificación de Unicidad de Precios​

3. Plugins de Transformación​

currency_accounts - Cuentas de Intercambio de Divisas​

commodity_attr - Validación de Atributos de Instrumentos​

4. Meta-Plugins​

auto - Todos los plugins automáticos​

pedantic - Todos los plugins de validación​

Configuraciones de plugins recomendadas​

Para principiantes​

Para inversores​

Para contabilidad estricta​

Configuración predeterminada en Beancount.io​

Mejores prácticas​

Más allá de los plugins nativos​

Conclusión​

Fuentes​

Comience con Beancount.io

Primeros pasos

Funciones

Comunidad

Legal

¿Qué son los complementos de Beancount?

Cómo usar complementos

Categorías de complementos nativos

1. Complementos de automatización

2. Complementos de validación

3. Complementos de transformación

4. Meta-complementos

1. Complementos de automatización

`auto_accounts` - Declaraciones automáticas de cuentas

`close_tree` - Cierre automático de la jerarquía de cuentas

`implicit_prices` - Generación automática de entradas de precios

2. Complementos de validación

`noduplicates` - Detección de transacciones duplicadas

`check_commodity` - Validación de declaración de materias primas (commodities)

`check_average_cost` - Validación de la Base de Costo

`check_closing` - Validación de Cierre de Saldo

`coherent_cost` - Verificación de Consistencia de Divisa/Costo

`leafonly` - Aplicación de Cuentas Hoja

`nounused` - Detección de Cuentas sin Uso

`onecommodity` - Un Instrumento por Cuenta

`sellgains` - Validación de Ganancias de Capital

`unique_prices` - Verificación de Unicidad de Precios

3. Plugins de Transformación

`currency_accounts` - Cuentas de Intercambio de Divisas

`commodity_attr` - Validación de Atributos de Instrumentos

4. Meta-Plugins

`auto` - Todos los plugins automáticos

`pedantic` - Todos los plugins de validación

Configuraciones de plugins recomendadas

Para principiantes

Para inversores

Para contabilidad estricta

Configuración predeterminada en Beancount.io

Mejores prácticas

Más allá de los plugins nativos

Conclusión

Fuentes