Introdução ao Beancount.io

Este guia sintetiza as melhores práticas para contabilidade em texto simples usando a poderosa ferramenta de contabilidade em texto simples e de código aberto, Beancount. Ele cobre a filosofia fundamental, a sintaxe básica a avançada, estudos de caso práticos para ativos complexos e estratégias de gerenciamento de livro-razão de longo prazo.

Parte 1: O "Porquê" - Fundamentos da Contabilidade Inteligente

Antes de mergulhar no "como", é crucial entender o "porquê". Uma contabilidade eficaz é a base da gestão financeira pessoal e um passo necessário para a clareza e a liberdade financeiras.

Além do Rastreamento de Despesas: O Caminho para a Clareza Financeira

Aplicativos simples de rastreamento de despesas informam para onde seu dinheiro foi. Um sistema de contabilidade robusto informa isso e muito mais: ele fornece uma imagem completa de sua saúde financeira, incluindo seu patrimônio líquido, fluxo de caixa e o desempenho de seus investimentos. O objetivo principal é a observabilidade — obter uma compreensão clara e orientada por dados de sua vida financeira, o que permite que você tome decisões informadas, avalie riscos e trabalhe em direção a metas de longo prazo, como a aposentadoria.

Por que Partidas Dobradas? O Poder de um Sistema Balanceado

Ao contrário da contabilidade de entrada única (uma simples lista de despesas), o método de partidas dobradas registra cada transação como um fluxo de valor entre pelo menos duas contas. Seu princípio fundamental é a equação contábil fundamental:

$\text{Ativos} = \text{Passivos} + \text{Patrimônio Líquido}$

Este sistema garante que seus livros estejam sempre equilibrados, reduzindo drasticamente os erros. Ele fornece uma imagem financeira completa, gerando relatórios essenciais como um Balanço Patrimonial (o que você possui e deve) e uma Demonstração do Resultado (o que você ganhou e gastou).

Parte 2: Primeiros Passos com o Beancount

Beancount é uma ferramenta poderosa, baseada em Python, para contabilidade em texto simples.

Sua Primeira Visualização com o Fava no Beancount.io

Beancount.io fornece um ambiente poderoso que combina o mecanismo Beancount com um aplicativo móvel (iOS, Android) e um aplicativo web - Fava, uma interface fantástica baseada na web para visualizar seu livro-razão. Não há necessidade de instalação. Quando você usa a plataforma, você está interagindo diretamente com um editor de texto para seu arquivo de livro-razão (por exemplo, main.bean) e vendo os relatórios gerados pelo Fava serem atualizados em tempo real.

O Fava pega o texto simples que você escreve e o transforma em gráficos interativos, demonstrações financeiras e listas de transações filtráveis, oferecendo uma visão clara de seus relatórios financeiros.

Os Cinco Tipos de Contas Principais

Beancount usa cinco tipos de contas de nível superior, que formam a estrutura de seu livro-razão:

Tipo de Conta	Descrição	Saldo Típico
Ativos	O que você possui (dinheiro, contas bancárias, investimentos, propriedade).	Positivo
Passivos	O que você deve (dívida de cartão de crédito, empréstimos, hipotecas).	Negativo
Receitas	De onde vem o dinheiro (salário, bônus, juros).	Negativo
Despesas	Para onde vai o dinheiro (comida, aluguel, viagens, impostos).	Positivo
Patrimônio	Seu patrimônio líquido; usado para saldos iniciais.	Negativo

A Equação do Beancount

Beancount impõe sua própria versão da equação contábil, onde a soma de todos os lançamentos em todo o seu livro-razão é igual a zero:

$\text{Ativos} + \text{Despesas} + \text{Passivos} + \text{Receitas} + \text{Patrimônio} = 0$

É por isso que, por convenção, as contas de Receitas, Passivos e Patrimônio possuem valores negativos—elas são as fontes de fundos que aumentam seus Ativos e Despesas.

Parte 3: A Linguagem do Beancount - Sintaxe Central

Todas as entradas no Beancount são diretivas que começam com uma data.

Definindo Contas (open) e Mercadorias

Antes de poder usar uma conta, você deve declará-la com a diretiva open. Você também pode, opcionalmente, especificar as moedas ou "mercadorias" que ela conterá.

; AAAA-MM-DD open Conta:Nome [Mercadoria1, Mercadoria2, ...]
2020-01-01 open Ativos:Banco:EUA:Chase:ContaCorrente USD
2020-01-01 open Passivos:CartaoCredito:EUA:Discover USD
2020-01-01 open Despesas:Alimentacao:Supermercado
2020-01-01 open Receitas:Salario:Google

As mercadorias podem ser moedas do mundo real (por exemplo, USD, JPY) ou qualquer unidade personalizada que você definir, como milhas aéreas (MILES_UA) ou tickers de ações (HOOL).

Registrando sua Primeira Transação (*)

As transações são a entrada mais comum. Elas começam com uma data, uma flag (* para uma transação completa ou ! para uma incompleta), um sacado opcional e uma descrição. Cada linha que segue (com indentação de dois espaços) é um "lançamento" em uma conta.

; AAAA-MM-DD * "Sacado" "Descrição"
;   Conta1      Valor Mercadoria
;   Conta2     -Valor Mercadoria

2024-07-28 * "Trader Joe's" "Compras semanais"
  Despesas:Alimentacao:Supermercado     125.50 USD
  Passivos:CartaoCredito:EUA:Discover  -125.50 USD

Para conveniência, se uma transação tiver apenas dois lançamentos, você pode omitir o valor na segunda linha, e o Beancount o calculará automaticamente.

2024-07-28 * "Trader Joe's" "Compras semanais"
  Despesas:Alimentacao:Supermercado     125.50 USD
  Passivos:CartaoCredito:EUA:Discover

Balanço em Nível de Transação: Mais importante para o uso diário, cada transação individual também deve ser balanceada—a soma de todos os lançamentos dentro de uma única transação deve ser igual a zero. Se uma transação não for balanceada, o Beancount mostrará um erro como este:

Lidando com Transações Multimoeda (@ e @@)

Beancount se destaca na contabilidade multimoeda.

• Use @ para especificar um preço de conversão por unidade.
• Use @@ para especificar o custo total da conversão.

; Comprando um voo em EUR com um cartão USD
2024-08-01 * "Lufthansa" "Voo para Berlim"
  Despesas:Viagem:Voos      500.00 EUR @@ 545.00 USD  ; 500 EUR me custaram 545 USD no total
  Passivos:CartaoCredito:EUA:Discover  -545.00 USD

Parte 4: Garantindo a Precisão - A Arte da Conciliação

Uma prática fundamental para manter um livro-razão preciso é a conciliação regular. Isso envolve comparar os saldos em seu livro-razão Beancount com extratos oficiais de suas instituições financeiras.

Automatizando Verificações com Declarações de Saldo (balance)

A diretiva balance é sua ferramenta primária para verificações automatizadas. Você declara que, em uma determinada data, uma conta tinha um saldo específico. O Beancount gerará um erro se o saldo calculado não corresponder à sua declaração. Isso é inestimável para localizar erros rapidamente.

Nota: A declaração de saldo verifica o estado da conta no início do dia especificado (antes de qualquer transação naquele dia).

; Do seu extrato mensal do cartão de crédito
2024-08-01 balance Passivos:CartaoCredito:EUA:Discover  -1432.78 USD

Vinculando Documentos de Suporte (document)

Você pode vincular arquivos externos, como extratos bancários ou recibos, criando um rastro auditável. O Fava torna esses links clicáveis.

2024-08-01 document Passivos:CartaoCredito:EUA:Discover "statements/discover-2024-07.pdf"

Corrigindo Erros e Inicializando Saldos

Quando você inicia seu livro-razão ou encontra uma discrepância que não consegue rastrear, você precisa fazer um ajuste. A prática padrão é usar uma conta Patrimônio especial.

; Inicializando uma conta de caixa ao iniciar seu livro-razão
2020-01-01 * "Saldo Inicial" "Configurando conta de caixa"
  Ativos:Caixa:Carteira           200.00 USD
  Patrimônio:Saldos-Iniciais     -200.00 USD

A conta Patrimônio:Saldos-Iniciais contém valores que entram em seu livro-razão de fontes desconhecidas ou externas.

Para correções rápidas onde a discrepância exata não é importante, a diretiva pad pode ajustar automaticamente o saldo de uma conta para atender a uma declaração balance subsequente, lançando a diferença em uma conta de patrimônio. Use isso com cautela, pois pode ocultar problemas maiores. Ajustes explícitos são geralmente mais seguros.

Parte 5: Padrões de Transação Avançados e Realistas

Rastreando Dívidas: Gerenciando Contas a Receber e a Pagar

A contabilidade de partidas dobradas é perfeita para rastrear o dinheiro que lhe devem (Ativos:ContasAReceber) ou que você deve (Passivos:ContasAPagar).

Exemplo: Você paga um jantar em grupo de $90, e seu amigo Bob lhe deve sua parte de$45.

1. Registre a despesa inicial e o valor a receber:

   2024-08-05 * "Restaurante" "Jantar com Bob"
     Despesas:Alimentacao:Restaurante          45.00 USD  ; Sua parte
     Ativos:ContasAReceber:Bob            45.00 USD  ; Bob lhe deve
     Ativos:Banco:EUA:Chase:ContaCorrente    -90.00 USD

2. Quando Bob lhe paga de volta:

   2024-08-06 * "Bob" "Me pagou pelo jantar"
     Ativos:Banco:EUA:Chase:ContaCorrente     45.00 USD
     Ativos:ContasAReceber:Bob           -45.00 USD

A conta Ativos:ContasAReceber:Bob agora é zero, e seus livros estão perfeitamente balanceados.

Ativos vs. Despesas: Uma Compra de Carro e Depreciação

Uma compra grande como um carro não é uma simples despesa; é a aquisição de um ativo que perde valor ao longo do tempo (depreciação).

1. Registre a compra como um ativo:

   2023-01-15 * "Concessionária Toyota" "Compra de um carro novo"
     Ativos:Carro:ToyotaCamry         30000.00 USD
     Ativos:Banco:EUA:Chase:ContaCorrente -30000.00 USD

2. Registre a depreciação anual: Suponha que você estime que o carro perde $3.000 em valor a cada ano. No final do ano, você registra isso como uma despesa.

   2023-12-31 * "Depreciação" "Depreciação anual do valor do carro"
     Despesas:Depreciação:Carro      3000.00 USD
     Ativos:Carro:ToyotaCamry        -3000.00 USD

Após esta entrada, sua conta Ativos:Carro:ToyotaCamry reflete corretamente o novo valor do carro ($27.000), e você contabilizou adequadamente o custo de uso como uma despesa para aquele ano.

Parte 6: Mergulho Profundo - Modelando Ativos Complexos do Mundo Real

Estudo de Caso 1: Contabilização de Imóveis

Uma casa é frequentemente seu maior ativo e passivo. Veja como modelá-la.

1. Crie Contas e uma Mercadoria Personalizada:

   2022-01-01 commodity CASA_123PRINCIPAL
     name: "Propriedade em 123 Main St"
   2022-01-01 open Ativos:Propriedade:Casa:123Principal        CASA_123PRINCIPAL
   2022-01-01 open Passivos:Hipoteca:EmpréstimoHabitacional       USD
   2022-01-01 open Despesas:Casa:Juros
   2022-01-01 open Despesas:Casa:ImpostoPredial

2. Registre a Compra: Digamos que você compre uma casa de $500 mil com uma entrada de$100 mil e um empréstimo de $400 mil.

   2022-03-15 * "Empresa de Liquidação" "Compra de 123 Main St"
     Ativos:Propriedade:Casa:123Principal          1 CASA_123PRINCIPAL {500000.00 USD}
     Ativos:Banco:Entrada          -100000.00 USD
     Passivos:Hipoteca:EmpréstimoHabitacional    -400000.00 USD

3. Registre os Pagamentos Mensais da Hipoteca: Seu pagamento mensal consiste em principal (reduz o passivo) e juros (uma despesa).

   2022-04-01 * "Banco da Hipoteca" "Pagamento Mensal da Hipoteca"
     Passivos:Hipoteca:EmpréstimoHabitacional      800.00 USD   ; Principal
     Despesas:Casa:Juros            1200.00 USD   ; Juros
     Ativos:Banco:EUA:Chase:ContaCorrente    -2000.00 USD

4. Rastreando a Valorização (Ganhos Não Realizados): O valor de mercado de uma casa muda. Para rastrear isso sem afetar seu patrimônio líquido oficial (já que o ganho não é realizado até você vender), você pode usar uma diretiva de preço com uma moeda "virtual".

   ; O preço de compra é a base de custo real
   2022-03-15 price CASA_123PRINCIPAL   500000.00 USD
   
   ; Uma estimativa de mercado atualizada é um ganho não realizado
   2024-01-01 price CASA_123PRINCIPAL   550000.00 USD.NAO_REALIZADO

Isso permite que você veja o valor estimado nos gráficos do Fava sem inflar indevidamente seu balanço patrimonial.

Estudo de Caso 2: Rastreando Unidades de Ações Restritas (RSUs)

RSUs são uma forma comum de compensação de capital. A contabilização delas envolve o rastreamento da concessão inicial, eventos de vesting e retenção de impostos.

1. Configuração Inicial: Crie mercadorias para ações com vesting (HOOL) e sem vesting (HOOL.NAO_VEST) , juntamente com as contas necessárias.

   2021-01-01 commodity HOOL
   2021-01-01 commodity HOOL.NAO_VEST
   2021-01-01 open Ativos:Corretora:Etrade:HOOL           HOOL
   2021-01-01 open Ativos:Concessão:NaoVestidas                 HOOL.NAO_VEST
   2021-01-01 open Receitas:Salario:Hooli:RSU
   2021-01-01 open Despesas:Impostos:Federal

2. Registre a Concessão Inicial: Esta transação mostra a concessão total movendo-se para uma conta de ativos não vestida.

   2021-02-01 * "Hooli" "Concessão RSU Inicial"
     Ativos:Concessão:NaoVestidas        1000 HOOL.NAO_VEST
     Receitas:Concessão:Prêmios         -1000 HOOL.NAO_VEST

3. Registre um Evento de Vesting: Esta é a transação chave. Quando as ações são concedidas, você reconhece a receita, paga impostos (geralmente vendendo algumas ações) e recebe as ações líquidas. Suponha que 100 ações sejam concedidas a $150/ação.

   2022-02-01 * "Hooli" "Evento de Vesting RSU"
     ; Reconheça a receita total de 100 * $150 = $15.000
     Receitas:Salario:Hooli:RSU                   -15000.00 USD
   
     ; Mostre os impostos pagos desta receita
     Despesas:Impostos:Federal                      4000.00 USD
     Despesas:Impostos:Estadual                        1000.00 USD
   
     ; Você recebe as ações líquidas (suponha 60 ações) em sua base de custo
     Ativos:Corretora:Etrade:HOOL                  60 HOOL {150.00 USD}
   
     ; As outras 40 ações foram vendidas para cobrir $6000 em impostos.
     ; Esta transação balanceia a receita, os impostos e as ações recebidas.
     ; Devemos também mostrar a redução nas ações não vestidas.
     Ativos:Concessão:NaoVestidas                       -100 HOOL.NAO_VEST
     Despesas:Concessão:Vestidas                        100 HOOL.NAO_VEST

Esta única transação balanceada modela corretamente todo o evento: a concessão não vestida é reduzida, a receita é reconhecida, os impostos são pagos e as ações vestidas líquidas aparecem em sua conta de corretora com a base de custo correta para cálculos futuros de ganhos de capital.

Parte 7: Gerenciamento de Projetos para seu Livro-Razão

À medida que seu livro-razão cresce, a organização se torna fundamental.

Usando o Controle de Versão (Git) para Proteger seus Dados

Como seu livro-razão é um arquivo de texto, ele é perfeito para controle de versão com Git. Isso lhe dá um histórico completo de todas as alterações, protegendo-o contra exclusões ou erros acidentais. Aviso: Seus dados financeiros são altamente confidenciais. Use um repositório privado em serviços como GitHub/GitLab ou hospede o seu próprio.

Organizando com Tags (#) e Links (^)

O Beancount oferece duas maneiras de agrupar transações além das contas:

• Tags (#): Use para eventos ou projetos. Você pode filtrar todas as transações relacionadas a uma viagem específica, por exemplo. 2024-07-20 * "Hotel" "Viena" #viagem-europa-2024
• Links (^): Use para conectar transações financeiramente relacionadas que ocorrem em momentos diferentes, como um saque em dinheiro e a taxa bancária associada.

Uma Estratégia Escalável para Estruturar seus Arquivos (include)

Um único arquivo massivo é difícil de gerenciar. Use a diretiva include para dividir seu livro-razão em vários arquivos. main.bean:

; Arquivo principal do livro-razão

; Opções globais
option "title" "Meu Livro-Razão Pessoal"
option "operating_currency" "USD"

; Inclua declarações de conta e outros arquivos
include "accounts.bean"
include "years/2023.bean"
include "years/2024.bean"
include "events/trip-europe-2024.bean"

Uma estratégia organizacional robusta, em ordem de precedência:

1. Por Evento: Crie um arquivo separado para um evento principal e autocontido (por exemplo, trip-europe-2024.bean).
2. Por Categoria/Sacado: Para transações altamente regulares e recorrentes, como contas de serviços públicos ou salário, agrupe-as em seu próprio arquivo (por exemplo, recurring-rent.bean).
3. Por Conta: Para transações estreitamente acopladas a uma conta específica (juros, taxas, pagamentos de cartão de crédito), considere um arquivo específico da conta.
4. Por Data: Para todas as outras transações gerais, uma divisão simples por ano (2024.bean) ou mês (2024/07.bean) é eficaz.

Parte 8: Conclusão

O Beancount oferece uma curva de aprendizado acentuada, mas recompensa o esforço com poder, flexibilidade e controle incomparáveis sobre seus dados financeiros. Ao abraçar os princípios da contabilidade de partidas dobradas e as ferramentas práticas que o Beancount fornece, você pode passar do simples rastreamento de despesas para um sistema completo, preciso e perspicaz de gestão financeira pessoal. Seu livro-razão se torna um ativo permanente, privado e inestimável para entender seu passado e planejar seu futuro.

Começando com Beancount.io

Beancount.io é uma plataforma moderna de gestão financeira baseada em nuvem que transforma seus registros de transações baseados em texto em demonstrações financeiras abrangentes, incluindo demonstrações de resultados, balanços patrimoniais e balancetes de verificação. Ao combinar a confiabilidade de arquivos de texto simples com ferramentas de visualização poderosas, o Beancount.io ajuda você a manter o controle preciso sobre sua vida financeira, obtendo informações valiosas sobre o desempenho de seus investimentos.

Comece sua jornada financeira com Beancount.io - Gratuito durante nosso período promocional!