Plugins Nativos Essenciais do Beancount que Você Deve Conhecer

Atualizado em 2026-09-15.

O poder do Beancount reside não apenas no seu formato de texto simples, mas na sua extensibilidade através de plugins. Os plugins nativos são módulos integrados que melhoram a funcionalidade do Beancount, automatizam tarefas tediosas e impõem as melhores práticas contabilísticas. Neste guia abrangente, exploraremos todos os plugins nativos disponíveis no Beancount e como usá-los eficazmente.

Para a sintaxe de diretivas sobre a qual estes plugins operam, consulte a referência de sintaxe do Beancount. Para fluxos de trabalho reais da comunidade que combinam plugins com importadores e Fava, consulte a vitrine da comunidade. As opções de ledger que interagem com plugins encontram-se na configuração de Opções.

O Que São Plugins do Beancount?​

Os plugins do Beancount são módulos Python que processam as suas entradas de ledger para adicionar capacidades de automatização, validação ou transformação. Eles são executados durante a fase de carregamento do seu ficheiro de ledger e podem:

• Automatizar tarefas repetitivas (por exemplo, criar declarações de contas)
• Validar a integridade dos dados (por exemplo, verificar transações duplicadas)
• Transformar entradas (por exemplo, gerar entradas de preço a partir de transações)
• Impor regras contabilísticas (por exemplo, uma mercadoria por conta)

Como Usar Plugins​

Para ativar um plugin no seu ficheiro Beancount, adicione uma diretiva plugin no topo do seu ledger:

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

Alguns plugins aceitam opções de configuração:

; @m49-fragment dateless
plugin "beancount.plugins.check_commodity" "{'Assets:Trading': '.*'}"

Categorias de Plugins Nativos​

Os plugins nativos do Beancount dividem-se em quatro categorias principais:

1. Plugins de Automatização​

2. Plugins de Validação​

3. Plugins de Transformação​

4. Meta-Plugins​

1. Plugins de Automatização​

Estes plugins automatizam tarefas contabilísticas repetitivas, poupando tempo e reduzindo erros manuais.

auto_accounts - Declarações Automáticas de Contas​

O que faz: Insere automaticamente diretivas Open para contas que aparecem em transações, mas que não foram explicitamente declaradas.

Porquê usar: Elimina a necessidade de declarar manualmente cada conta antes de a usar. Perfeito para começar rapidamente ou para utilizadores que preferem menos código boilerplate.

Exemplo:

plugin "beancount.plugins.auto_accounts"
 
2026-01-01 * "Cafetaria"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

Sem o plugin, teria de adicionar manualmente:

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

Quando usar: Ideal para principiantes ou para quem prefere um ledger menos verboso. No entanto, declarações de contas explícitas podem ajudar a detetar erros de digitação.

close_tree - Fecho Automático da Hierarquia de Contas​

O que faz: Quando fecha uma conta-mãe, este plugin fecha automaticamente todas as suas contas descendentes.

Porquê usar: Mantém a consistência na hierarquia de contas. Se fechar Assets:Investments, todas as subcontas como Assets:Investments:Stocks e Assets:Investments:Bonds serão fechadas automaticamente.

Exemplo:

plugin "beancount.plugins.close_tree"
 
2025-06-30 close Assets:Investments
 
; Serão fechadas automaticamente:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

Quando usar: Ao reestruturar a hierarquia de contas ou fechar categorias inteiras de contas.

implicit_prices - Geração Automática de Entradas de Preço​

O que faz: Sintetiza diretivas Price a partir de lançamentos de transações que incluem custos (@) ou preços (@@).

Porquê usar: Preenche automaticamente a sua base de dados de preços a partir das transações, permitindo relatórios precisos de valor de mercado sem entradas de preço manuais.

Exemplo:

plugin "beancount.plugins.implicit_prices"
 
2026-01-02 * "Comprar ações AAPL"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

Isto gera automaticamente:

2026-01-02 price AAPL  150.00 USD

Quando usar: Essencial para o acompanhamento de investimentos e contabilidade multimoeda onde deseja histórico de preços automático.

2. Plugins de Validação​

Estes plugins impõem a integridade dos dados e as melhores práticas contabilísticas, detetando erros antes de se tornarem problemas.

noduplicates - Deteção de Transações Duplicadas​

O que faz: Verifica que não existem duas transações idênticas calculando e comparando hashes dos dados das transações.

Porquê usar: Previne entradas duplicadas acidentais, especialmente ao importar transações de múltiplas fontes.

Exemplo:

; @m49-fragment expected-failure
plugin "beancount.plugins.noduplicates"
 
2026-01-02 * "Pagamento de renda"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD
 
; Isto acionaria um erro:
2026-01-02 * "Pagamento de renda"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

Quando usar: Sempre recomendado, especialmente se estiver a importar de extratos bancários ou a usar múltiplas fontes de dados.

check_commodity - Validação de Declaração de Mercadoria​

O que faz: Garante que todas as mercadorias usadas no seu ledger têm diretivas Commodity correspondentes.

Porquê usar: Impõe declarações explícitas de mercadorias, ajudando a manter uma lista limpa de ativos e moedas.

Exemplo:

; @m49-fragment expected-failure
plugin "beancount.plugins.check_commodity"
 
2015-01-01 commodity USD
2020-01-01 commodity AAPL
 
; Isto acionaria um erro sem uma declaração de mercadoria:
2026-01-02 * "Comprar Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

Quando usar: Recomendado para manter um acompanhamento rigoroso de mercadorias e prevenir erros de digitação em símbolos de ticker.

check_average_cost - Validação de Base de Custo​

O que faz: Verifica que a base de custo é devidamente preservada nas transações, especialmente ao usar o regime de custo médio.

Porquê usar: Garante que a sua contabilidade de custos permanece precisa para relatórios fiscais e cálculos de mais-valias.

Quando usar: Crítico para carteiras de investimento e qualquer cenário onde o acompanhamento preciso de custos é importante.

check_closing - Validação de Fecho de Saldo​

O que faz: Expande os metadados closing em verificações de saldo, garantindo que as posições ficam a zero após fecho de transações.

Porquê usar: Confirma que, ao vender uma posição inteira, o saldo é verdadeiramente zero (sem frações de ações remanescentes).

Exemplo:

plugin "beancount.plugins.check_closing"
 
2026-01-02 * "Fechar posição inteira AAPL" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15500.00 USD
  Income:Investments:Gains    -500.00 USD

A tag #closing diz ao plugin para verificar que a sua posição AAPL é zero após esta transação.

Quando usar: Ao vender posições inteiras para garantir que nada é deixado para trás.

coherent_cost - Verificação de Consistência Moeda/Custo​

O que faz: Valida que as moedas não são usadas de forma inconsistente — tanto com como sem anotações de custo.

Porquê usar: Previne a mistura de moedas simples (como 100 USD) com moedas com custo (como 100 USD {1.2 CAD}), que pode causar erros contabilísticos.

Quando usar: Recomendado para ledgers multimoeda para manter consistência.

leafonly - Reforço de Contas de Nível Final​

O que faz: Garante que apenas contas de nível final (contas sem filhas) recebem lançamentos.

Porquê usar: Impõe uma hierarquia de contas limpa onde contas resumo como Expenses:Food não têm lançamentos diretos, apenas as suas filhas como Expenses:Food:Groceries e Expenses:Food:Restaurants.

Exemplo:

; @m49-fragment expected-failure
plugin "beancount.plugins.leafonly"
 
; Isto acionaria um erro:
2026-01-02 * "Compras de supermercado"
  Expenses:Food              50.00 USD  ; Erro: Deve lançar para uma conta de nível final
  Assets:Cash               -50.00 USD
 
; Forma correta:
2026-01-02 * "Compras de supermercado"
  Expenses:Food:Groceries    50.00 USD  ; Correto: Lançamento para conta de nível final
  Assets:Cash               -50.00 USD

Quando usar: Quando pretende manter uma contabilidade hierárquica rigorosa com categorização clara.

nounused - Deteção de Contas Não Utilizadas​

O que faz: Identifica contas que foram abertas mas nunca usadas em transações.

Porquê usar: Ajuda a limpar as declarações de contas e identificar possíveis erros de digitação ou contas abandonadas.

Quando usar: Periodicamente, para auditar e limpar a estrutura de contas.

onecommodity - Uma Única Mercadoria por Conta​

O que faz: Impõe que cada conta detenha apenas um tipo de mercadoria.

Porquê usar: Previne a mistura de diferentes ativos na mesma conta, o que é geralmente uma boa prática contabilística.

Exemplo:

; @m49-fragment expected-failure
plugin "beancount.plugins.onecommodity"
 
2026-01-02 * "Comprar ações"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD
 
; Isto acionaria um erro:
2026-01-03 * "Comprar mais ações"
  Assets:Investments         5 GOOGL @ 140 USD  ; Erro: Mercadoria diferente
  Assets:Cash              -700.00 USD

Quando usar: Quando prefere separação rigorosa de contas (uma conta por ação/ativo).

sellgains - Validação de Mais-Valias​

O que faz: Cruza as mais-valias declaradas com os ganhos calculados das vendas por lotes, garantindo que os cálculos de lucro/prejuízo são precisos.

Porquê usar: Detecta erros em cálculos manuais de mais-valias, crítico para relatórios fiscais precisos.

Exemplo:

plugin "beancount.plugins.sellgains"
 
2026-01-02 * "Vender ações AAPL"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; O plugin valida que isto está correto

O plugin verificará: Proventos da venda (1500) - Base de custo (1400) = Ganhos (100)

Quando usar: Essencial para quem negocia ações, criptomoedas ou outros ativos onde as mais-valias são importantes.

unique_prices - Verificação de Unicidade de Preços​

O que faz: Garante que existe apenas uma entrada de preço por mercadoria por data.

Porquê usar: Previne dados de preços conflituosos que podem levar a valorações incorretas.

Quando usar: Recomendado ao inserir preços manualmente ou importar de múltiplas fontes de preços.

check_drained - Validação de Contas Esvaziadas​

O que faz: Sinaliza contas que ainda detêm saldo (incluindo moedas sem preço ou lotes remanescentes) quando esperava que estivessem vazias após transferências ou fechos.

Porquê usar: Detecta saldos residuais que as asserções de balance e as tags #closing podem não apanhar — especialmente útil após movimentos multimercadoria.

Estado (verificado 2026-09-15): Presente na árvore Beancount 3.x em beancount/plugins/check_drained.py na linha PyPI atual (3.2.3).

Quando usar: Após grandes reorganizações de carteira ou ao fechar contas de corretor.

3. Plugins de Transformação​

Estes plugins modificam ou melhoram os dados do seu ledger de formas úteis.

currency_accounts_conta - Contas de Negociação de Moedas​

O que faz: Implementa contas de negociação de moedas para monitorizar explicitamente conversões forex.

Porquê usar: Fornece um acompanhamento detalhado das transações de conversão de moeda, útil para normas contabilísticas que o exigem.

Quando usar: Quando precisa de monitorizar ganhos/perdas forex separadamente ou cumprir requisitos contabilísticos específicos.

commodity_attr - Validação de Atributos de Mercadoria​

O que faz: Valida que as diretivas de mercadoria têm os atributos necessários (como export, name, etc.).

Porquê usar: Garante que os seus metadados de mercadoria estão completos e consistentes.

Quando usar: Quando mantém metadados de mercadoria detalhados para fins de relatórios ou exportação.

4. Meta-Plugins​

Estes plugins são coleções de outros plugins por conveniência.

auto - Todos os Plugins Automáticos​

O que faz: Ativa uma coleção de plugins "permissivos" ou automáticos numa única diretiva.

Quando usar: Configuração rápida para utilizadores que desejam máxima automatização com configuração mínima.

pedantic - Todos os Plugins de Validação​

O que faz: Ativa todos os plugins de validação rigorosos de uma só vez.

Porquê usar: Impõe máxima integridade de dados e rigor contabilístico. Ótimo para ledgers de produção ou quando a precisão é primordial.

Exemplo:

plugin "beancount.plugins.pedantic"
 
; Isto é equivalente a ativar:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

Quando usar: Para ledgers de produção onde deseja máxima validação e está disposto a manter práticas contabilísticas mais rigorosas.

Configurações de Plugins Recomendadas​

Para Principiantes​

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

Este conjunto mínimo fornece automatização enquanto previne erros comuns.

Para Investidores​

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"

Foca-se no acompanhamento de investimentos e precisão das mais-valias.

Para Contabilidade Rigorosa​

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

Validação máxima para ambientes de produção.

Configuração Padrão no Beancount.io​

No Beancount.io, incluímos o plugin auto_accounts por predefinição em todos os novos ficheiros de ledger:

plugin "beancount.plugins.auto_accounts"

Isto fornece um excelente equilíbrio entre facilidade de uso e funcionalidade para começar rapidamente.

Estado dos plugins verificado em 2026-09-15​

Contra a árvore beancount/plugins ativa na ` no Beancount 3.2.3 (PyPI, 2026-09-15):

Nada nesse conjunto nativo foi removido entre o rascunho original deste guia e a data acima. Os plugins comunitários (não nativos) continuam a pertencer à lista Awesome Beancount plugins e à vitrine da comunidade — trate os repositórios de terceiros como versões independentes e verifique a última versão de cada repositório antes de ativar num ledger de produção.

Melhores Práticas​

1. Comece mínimo, adicione conforme necessário: Comece com auto_accounts e noduplicates, depois adicione plugins de validação à medida que o seu ledger amadurece.

2. Teste os plugins individualmente: Ao adicionar múltiplos plugins, ative-os um de cada vez para entender os seus efeitos.

3. Leia as mensagens de erro cuidadosamente: Os erros de plugins apontam frequentemente para problemas contabilísticos reais que precisam de ser corrigidos.

4. Use pedantic para produção: Uma vez estabelecido o seu fluxo de trabalho, considere ativar validação rigorosa.

5. Combine com plugins personalizados: Os plugins nativos funcionam em conjunto com plugins personalizados como o plugin de previsão (forecast) para funcionalidade máxima.

Além dos Plugins Nativos​

Embora os plugins nativos forneçam funcionalidade principal, o ecossistema Beancount inclui muitos plugins desenvolvidos pela comunidade para necessidades especializadas:

• fava.plugins.forecast - Para previsão de transações recorrentes
• fava.plugins.link_documents - Para ligar transações a ficheiros de recibos
• Importadores personalizados para formatos CSV específicos de bancos
• Calculadoras e relatórios específicos de impostos

Explore o ecossistema Beancount para mais opções, e a vitrine da comunidade para ver como as pessoas combinam plugins nativos com importadores e Fava.

Conclusão​

Os plugins nativos do Beancount transformam a contabilidade em texto simples de um processo manual para um sistema de gestão financeira automatizado, validado e robusto. Ao compreender e aproveitar estas ferramentas integradas, pode:

• ✅ Automatizar tarefas contabilísticas tediosas
• ✅ Detetar erros antes de se tornarem problemas
• ✅ Manter integridade rigorosa dos dados
• ✅ Gerar relatórios financeiros precisos
• ✅ Focar-se em insights financeiros em vez de entrada de dados

Comece a experimentar estes plugins no seu ledger hoje. Comece com auto_accounts e implicit_prices, depois adicione gradualmente plugins de validação à medida que as suas práticas contabilísticas amadurecem.

Pronto para experimentar estes plugins? Vá ao Beancount.io e comece a usá-los no seu ficheiro de ledger hoje!

Fontes​

• Referência da API de Plugins do Beancount
• Guia de Scripting e Plugins do Beancount
• Plugins e Opções do Beancount por Bryan Alves
• Repositório GitHub do Beancount

Tem perguntas sobre plugins Beancount? Junte-se à discussão no nosso fórum da comunidade ou consulte a nossa documentação.

Explore um exemplo de ledger de criptomoedas ao vivo: