Configuração de Opções no Beancount

O comportamento do Beancount pode ser personalizado usando diretivas option colocadas no topo do seu arquivo de livro razão principal. Esses pares chave-valor controlam tudo, desde os nomes das suas contas raiz até como as conversões de moeda são tratadas. Configurar adequadamente essas opções é essencial para adaptar o Beancount às suas necessidades específicas. ⚙️

Opções de Configuração Principais

Estas opções controlam a configuração fundamental do seu livro razão.

Configurações Básicas

Estas são algumas das opções mais comuns que você irá definir.

option "title" "Livro Razão Pessoal"
option "render_commas" "TRUE"
option "plugin_processing_mode" "raw"

• title: Define o título para relatórios e interfaces web.
• render_commas: Se TRUE, os números nos relatórios serão formatados com separadores de milhares (por exemplo, 1.000.000,00).
• plugin_processing_mode: Controla como os plugins são carregados. raw carrega apenas os plugins que você especifica explicitamente, enquanto default inclui um conjunto padrão de plugins úteis.

Personalização do Nome da Conta

Você pode renomear os cinco tipos de conta fundamentais do Beancount. Isso é puramente cosmético e altera a forma como eles aparecem nos relatórios.

option "name_assets" "Ativos"
option "name_liabilities" "Passivos"
option "name_equity" "Patrimônio Líquido"
option "name_income" "Receitas"
option "name_expenses" "Despesas"

Configuração da Conta de Patrimônio Líquido

O Beancount cria automaticamente várias contas de patrimônio líquido especiais para lidar com saldos iniciais e cálculos de receita. Você pode especificar nomes personalizados para essas contas.

option "account_previous_balances" "Saldos-Iniciais"
option "account_previous_earnings" "Ganhos:Anteriores"
option "account_current_earnings" "Ganhos:Atuais"
option "account_previous_conversions" "Conversões:Anteriores"
option "account_current_conversions" "Conversões:Atuais"
option "account_rounding" "Arredondamento"

• account_previous_balances: A conta usada para injetar saldos iniciais no seu livro razão.
• account_current_earnings: A conta que acumula todos os totais de receitas e despesas para o período atual, calculando efetivamente sua receita líquida.
• account_rounding: A conta onde pequenas discrepâncias de arredondamento automatizado são lançadas.

Configurações de Precisão e Tolerância

Estas opções controlam como o Beancount lida com arredondamentos e pequenos desequilíbrios nas transações.

Configuração de Tolerância Padrão

O Beancount pode inferir automaticamente uma tolerância para transações com múltiplas moedas ou custos, permitindo pequenas diferenças de arredondamento sem causar erros.

option "inferred_tolerance_default" "USD:0.01"
option "inferred_tolerance_multiplier" "1.1"
option "infer_tolerance_from_cost" "True"

• inferred_tolerance_default: Define a tolerância padrão para uma determinada moeda. Você pode usar *:0.5 para definir um padrão para todas as moedas.
• inferred_tolerance_multiplier: Um fator aplicado à tolerância para fornecer uma margem de erro ligeiramente maior.
• infer_tolerance_from_cost: Se True, a tolerância será inferida do número de dígitos no custo.

Método de Lançamento

Esta opção define como o Beancount lida com transações onde uma perna é inferida.

option "booking_method" "SIMPLE"

• SIMPLE: Permite que apenas uma commodity seja automaticamente equilibrada por transação. Este é o método recomendado e mais comum.
• FULL: Permite que múltiplas commodities sejam equilibradas, o que é um método mais complexo e raramente necessário.

Gestão de Moeda

A configuração correta da moeda é vital para relatórios precisos.

Moeda Operacional

Você pode declarar uma ou mais "moedas operacionais". Estas são as principais moedas em que você transaciona e deseja ver nos relatórios.

option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"

Declarar moedas operacionais diz ao Beancount para criar colunas dedicadas para elas nos relatórios, tornando mais fácil ver sua posição financeira em suas moedas mais usadas. Definir conversion_currency como NOTHING desativa a coluna de conversão automática, o que geralmente é preferível para relatórios mais limpos.

Gestão de Documentos

O Beancount pode vincular transações a arquivos externos, como recibos ou faturas. A opção documents especifica a(s) pasta(s) raiz onde esses arquivos são armazenados.

option "documents" "/path/to/documents/archive"

Requisitos:

• Os arquivos devem ser nomeados usando o formato AAAA-MM-DD.descrição.ext (por exemplo, 2025-07-28.pedido-amazon.pdf).
• Você pode especificar várias opções documents para diferentes pastas.
• Os caminhos podem ser absolutos ou relativos ao arquivo de livro razão principal.

Sistema de Plugins

A funcionalidade do Beancount pode ser estendida com plugins.

Configuração do Plugin

Você habilita um plugin especificando seu caminho de módulo.

option "plugin" "beancount.plugins.module_name"

Como mencionado anteriormente, a opção plugin_processing_mode controla se o Beancount carrega apenas os plugins especificados (raw) ou também um conjunto padrão (default).

Limites e Restrições Técnicas

Estas opções controlam aspectos técnicos do analisador do Beancount.

Tratamento de Strings

Você pode definir um limite para o número de linhas permitidas em uma string de várias linhas para evitar erros de análise.

option "long_string_maxlines" "64"

Funcionalidades Experimentais

O Beancount às vezes inclui funcionalidades experimentais que você pode habilitar com uma opção. Por exemplo, para habilitar a sintaxe de tolerância explícita:

option "experiment_explicit_tolerances" "True"

Isso permite que você especifique a tolerância diretamente em um lançamento de transação, assim: 532.23 ~ 0.001 USD.

Controles de Comportamento do Sistema

Estas opções são para manter a compatibilidade ou comportamentos específicos do sistema.

Suporte Legado

Esta opção habilita os valores de tolerância fixos antigos para compatibilidade com versões anteriores de livros razão.

option "use_legacy_fixed_tolerances" "True"

As tolerâncias legadas fixas eram:

• Diretivas Balance/Pad: 0.015 unidades
• Transações: 0.005 unidades

Configuração Recomendada ✅

Para a maioria dos usuários, a seguinte configuração fornece um ponto de partida robusto e sensato.

Configuração Básica

option "title" "Livro Razão Pessoal"
option "operating_currency" "USD"  // Altere para sua moeda principal
option "documents" "/home/user/Documents/beancount" // Altere para o caminho de seus documentos
option "render_commas" "TRUE"

Controle de Precisão

option "inferred_tolerance_default" "USD:0.01" // Altere para sua moeda principal
option "inferred_tolerance_multiplier" "1.1"
option "infer_tolerance_from_cost" "True"

Estrutura da Conta

option "account_previous_balances" "Patrimônio Líquido:Saldos-Iniciais"
option "account_current_earnings" "Patrimônio Líquido:Ganhos-Atuais"
option "account_rounding" "Despesas:Arredondamento"

Esta configuração fornece uma base sólida para um novo livro razão do Beancount, garantindo relatórios claros, controle de precisão sensato e uma estrutura lógica de conta de patrimônio líquido.