Pular para o conteúdo principal

O Guia Completo para Gerenciar Contas no Beancount e Fava

· 13 min para ler
Mike Thrift
Mike Thrift
Marketing Manager

O plano de contas e a espinha dorsal do seu livro-razao no Beancount. Uma hierarquia de contas bem projetada torna cada relatorio mais claro, cada consulta mais rapida e cada periodo fiscal menos doloroso. Neste guia, vamos percorrer tudo o que voce precisa saber sobre criar, consultar, atualizar e encerrar contas no Beancount e Fava -- desde o basico para iniciantes ate padroes avancados.

Os Cinco Tipos de Contas​

O Beancount utiliza o modelo padrao de contabilidade por partidas dobradas com exatamente cinco tipos de contas raiz:

TipoFinalidadeSinal NormalRelatorio
AssetsRecursos que voce possui (dinheiro, investimentos, imoveis)Positivo (debito)Balanco Patrimonial
LiabilitiesDividas que voce deve (cartoes de credito, emprestimos, hipotecas)Negativo (credito)Balanco Patrimonial
EquityPatrimonio do proprietario, lucros retidos, saldos de aberturaNegativo (credito)Balanco Patrimonial
IncomeFontes de receita (salario, juros, dividendos)Negativo (credito)Demonstracao de Resultado
ExpensesCategorias de custo (alimentacao, aluguel, servicos publicos)Positivo (debito)Demonstracao de Resultado

A equacao contabil fundamental sempre se mantem:

Assets + Expenses + Equity + Income + Liabilities = 0

Uma heuristica util: se os valores sao relevantes apenas para um periodo de tempo (ex.: "Quanto gastei com alimentacao este mes?"), use Income ou Expenses. Se representam um saldo contínuo (ex.: "Quanto tenho na minha conta corrente?"), use Assets ou Liabilities.

Convencoes de Nomenclatura de Contas​

Os nomes de contas no Beancount sao identificadores hierarquicos separados por dois-pontos. As regras sao:

  • Devem comecar com um dos cinco tipos raiz: Assets, Liabilities, Equity, Income, Expenses
  • Cada componente comeca com uma letra maiuscula ou numero
  • Os componentes podem conter letras, numeros e hifens (sem espacos ou underscores)
  • Sao necessarios pelo menos dois componentes (ex.: Expenses:Food, nao apenas Expenses)
  • Dois-pontos (:) separam os niveis da hierarquia
; Nomes de contas validos
Assets:US:BofA:Checking
Liabilities:CA:RBC:CreditCard
Equity:Retained-Earnings
Income:US:Acme:Salary
Expenses:Food:Groceries
Assets:Crypto:BTC-Holdings

; Nomes de contas invalidos
assets:checking          ; tipo raiz em minusculas
Assets:my checking       ; espacos nao sao permitidos
Expenses                 ; apenas um componente

O padrao de nomenclatura recomendado para contas do balanco patrimonial e:

Tipo : Pais : Instituicao : Conta : SubConta

Por exemplo: Assets:US:Vanguard:401k:VTSAX ou Liabilities:US:Chase:Sapphire.

Para contas de despesas e receitas, use nomenclatura baseada em categorias:

Expenses:Food:Groceries
Expenses:Housing:Utilities:Electric
Income:US:Employer:Salary

Personalizando os Nomes Raiz​

Voce pode renomear os cinco tipos raiz para localizacao ou preferencia pessoal:

option "name_assets"       "Actifs"
option "name_liabilities"  "Passifs"
option "name_equity"       "Capital"
option "name_income"       "Revenus"
option "name_expenses"     "Depenses"

Criando Contas (Diretiva Open)​

Toda conta deve ser declarada com uma diretiva open antes de voce poder lancar transacoes nela. A sintaxe completa e:

YYYY-MM-DD open Account [MoedaRestricao,...] ["MetodoAlocacao"]

Open Basico​

2014-05-01 open Assets:US:BofA:Checking

Com Restricoes de Moeda​

Restringir moedas evita lancar acidentalmente a moeda errada:

2014-05-01 open Assets:US:BofA:Checking       USD
2014-05-01 open Assets:Cash                    USD,CAD,EUR
2012-03-01 open Assets:US:ETrade:Main:ITOT     ITOT

Com Metodos de Alocacao​

Para contas de investimento, especifique como os lotes sao combinados quando voce vende:

2014-02-11 open Assets:US:ETrade:IVV   IVV   "FIFO"
2014-02-11 open Assets:US:Schwab:AAPL  AAPL  "LIFO"
2014-02-11 open Assets:US:Fidelity     GOOG  "STRICT"

Metodos de alocacao disponiveis:

MetodoComportamento
"STRICT"Padrao. Requer especificacao exata do lote; gera erro em caso de ambiguidade
"FIFO"Primeiro a Entrar, Primeiro a Sair -- reduz os lotes mais antigos primeiro
"LIFO"Ultimo a Entrar, Primeiro a Sair -- reduz os lotes mais recentes primeiro
"AVERAGE"Mescla todos os lotes e recalcula o custo medio
"NONE"Sem correspondencia de lotes; qualquer preco e aceito

Com Metadados​

2013-03-14 open Assets:US:BTrade:HOOLI
  category: "taxable"
  institution: "BTrade Corp"
  account-number: "XX-1234-5678"

Escolhendo Datas de Abertura Estrategicamente​

  • Use sua data de nascimento para contas universais como Expenses:Groceries (isso permite somas vitalicas)
  • Use a data de inicio do emprego para contas de receita relacionadas ao trabalho
  • Use a data real de criacao da conta para contas especificas de instituicoes (contas bancarias, cartoes de credito)

Abertura Automatica com um Plugin​

Se voce deseja pular diretivas open manuais durante a prototipagem:

plugin "beancount.plugins.auto_accounts"

Isso gera automaticamente diretivas open para qualquer conta referenciada em transacoes. No entanto, isso reduz a deteccao de erros de digitacao, portanto nao e recomendado para uso em producao.

Listando e Consultando Contas​

Usando bean-query (BQL)​

# Listar todas as contas com saldos
bean-query ledger.beancount "SELECT account, units(sum(position)) GROUP BY 1"

# Listar apenas contas de despesas
bean-query ledger.beancount "SELECT account WHERE account ~ 'Expenses'"

# Extrato da conta com saldo acumulado
bean-query ledger.beancount \
  "SELECT date, account, position, balance WHERE account ~ 'BofA:Checking'"

# Visao de diario para uma conta especifica
bean-query ledger.beancount "JOURNAL 'Assets:US:BofA:Checking'"

Usando bean-report​

# Balancete (todas as contas com saldos finais)
bean-report ledger.beancount balances

# Balanco patrimonial
bean-report ledger.beancount balsheet

# Demonstracao de resultado
bean-report ledger.beancount income

# Diario para uma conta especifica
bean-report ledger.beancount journal -a Assets:US:BofA:Checking

Usando o Fava​

O Fava oferece uma interface visual rica para explorar contas:

  • Pagina de Balanco Patrimonial: arvore interativa de todos os Assets, Liabilities e Equity
  • Pagina de Demonstracao de Resultado: arvore interativa de todos os Income e Expenses
  • Pagina da conta: clique em qualquer nome de conta para ver suas abas de Diario, Alteracoes e Saldos
  • Barra de filtro: use padroes regex para mostrar apenas contas correspondentes (ex.: Assets:US)

Atualizando Contas (Renomear e Reorganizar)​

O Beancount nao possui uma diretiva de renomeacao nativa, mas existem diversas abordagens.

1. Localizar e Substituir​

A simples busca e substituicao funciona, mas tenha cuidado -- Assets:Bank tambem corresponderia a Assets:Bank:Cash. Use padroes com limites de palavra:

sed -i 's/Assets:US:OldBank:Checking/Assets:US:NewBank:Checking/g' *.beancount

2. O Plugin rename_accounts​

O pacote beancount_reds_plugins fornece um poderoso plugin de renomeacao:

plugin "beancount_reds_plugins.rename_accounts.rename_accounts" "{
  'Expenses:Taxes' : 'Income:Taxes',
  'Assets:House:Capital-Improvements' : 'Expenses:House:Appliances',
}"

Este plugin:

  • Usa correspondencia de substring (Expenses:Taxes:Federal automaticamente se torna Income:Taxes:Federal)
  • Suporta regex com referencias retroativas
  • Gera automaticamente diretivas Open para contas renomeadas
  • Nao modifica seus arquivos fonte -- apenas altera a representacao em memoria
  • Pode ser ativado/desativado comentando a linha do plugin

3. Padrao Fechar e Reabrir​

Para migracoes reais de contas (ex.: trocar de banco):

; Conta antiga
2010-01-01 open Assets:US:OldBank:Checking  USD

; Fechar a antiga, abrir a nova
2024-06-15 close Assets:US:OldBank:Checking
2024-06-15 open Assets:US:NewBank:Checking  USD

; Transferir o saldo restante
2024-06-15 * "Transferencia para novo banco"
  Assets:US:OldBank:Checking    -5000.00 USD
  Assets:US:NewBank:Checking     5000.00 USD

Encerrando Contas​

A diretiva close marca uma conta como nao mais ativa:

2016-11-28 close Liabilities:CreditCard:CapitalOne

O Que o Encerramento Faz​

  • Gera um erro se algum lancamento ocorrer apos a data de encerramento
  • Filtra a conta dos relatorios fora do seu periodo ativo
  • Informa ao Fava para ocultar a conta das visualizacoes em arvore (configuravel)

Quando Encerrar Contas​

  • Quando voce encerra uma conta bancaria ou cartao de credito no mundo real
  • Quando voce troca de empregador
  • Quando voce consolida ou reorganiza seu plano de contas
  • Quando voce vende um imovel ou encerra uma posicao de investimento

Sempre Verifique Saldo Zero Antes de Encerrar​

O Beancount nao verifica automaticamente o saldo zero no encerramento. Adicione uma verificacao manual:

2023-12-31 balance Assets:US:OldBank:Savings  0.00 USD
2023-12-31 close Assets:US:OldBank:Savings

Organizando Seu Plano de Contas​

Comece Simples, Refine com o Tempo​

Voce nao precisa do plano de contas perfeito no primeiro dia. Comece com categorias amplas e divida-as conforme suas necessidades de relatorio crescem. O autor do Beancount relata ter mais de 250 contas de despesas, todas criadas organicamente ao longo do tempo.

Padroes Comuns de Organizacao​

Padrao 1: Por Instituicao (para contas do balanco patrimonial)

Assets:US:BofA:Checking
Assets:US:BofA:Savings
Assets:US:Vanguard:401k:VTSAX
Assets:US:Vanguard:401k:VBTLX
Liabilities:US:Amex:Platinum
Liabilities:US:Chase:Sapphire

Padrao 2: Por Categoria (para contas de receitas e despesas)

Expenses:Food:Groceries
Expenses:Food:Restaurant
Expenses:Food:Coffee
Expenses:Housing:Rent
Expenses:Housing:Insurance
Expenses:Housing:Utilities:Electric
Expenses:Housing:Utilities:Water
Expenses:Transport:Subway
Expenses:Transport:Gas
Expenses:Health:Medical
Expenses:Health:Dental

Padrao 3: Por Geografia (para financas em multiplos paises)

Assets:US:BofA:Checking
Assets:CA:RBC:Checking
Assets:UK:HSBC:Current
Income:US:Acme:Salary
Income:CA:Freelance:Consulting

Padrao 4: Por Imovel ou Projeto (para imoveis ou negocios)

Assets:US:Loft4530:Property
Income:US:Loft4530:Rental
Expenses:Loft4530:Electricity
Expenses:Loft4530:Insurance
Expenses:Loft4530:Maintenance

Padrao 5: Espelhamento de Contas Relacionadas (mesmo componente de instituicao)

Assets:US:ETrade:Cash
Assets:US:ETrade:AAPL
Income:US:ETrade:Dividends
Income:US:ETrade:PnL
Expenses:US:ETrade:Commissions

Qual Deve Ser a Profundidade das Hierarquias?​

  • 2-3 niveis e comum para categorias de despesas (Expenses:Food:Restaurant)
  • 3-4 niveis para itens estruturados do balanco patrimonial (Assets:US:Vanguard:401k:VTSAX)
  • Evite mais de 5 niveis a menos que tenha uma razao forte para relatorios
  • Hierarquias profundas funcionam bem quando o Fava as recolhe nas visualizacoes em arvore

Um Exemplo do Mundo Real​

Aqui esta um plano de contas pratico para financas pessoais:

; -- Ativos --
Assets:US:BofA:Checking         USD
Assets:US:BofA:Savings          USD
Assets:US:Vanguard:401k:VTSAX  VTSAX
Assets:US:Vanguard:Roth:VTSAX  VTSAX
Assets:US:ETrade:Cash           USD
Assets:US:ETrade:AAPL           AAPL
Assets:Cash:Wallet              USD

; -- Passivos --
Liabilities:US:Amex:Platinum    USD
Liabilities:US:Chase:Freedom    USD
Liabilities:US:BofA:Mortgage    USD

; -- Receitas --
Income:US:Employer:Salary
Income:US:Employer:Bonus
Income:US:Employer:Match401k
Income:US:ETrade:Dividends
Income:US:BofA:Interest

; -- Despesas --
Expenses:Food:Groceries
Expenses:Food:Restaurant
Expenses:Food:Coffee
Expenses:Housing:Rent
Expenses:Housing:Insurance
Expenses:Housing:Utilities:Electric
Expenses:Housing:Utilities:Water
Expenses:Transport:Subway
Expenses:Transport:Taxi
Expenses:Transport:Gas
Expenses:Health:Medical
Expenses:Health:Dental
Expenses:Health:Pharmacy
Expenses:Shopping:Clothing
Expenses:Shopping:Electronics
Expenses:Entertainment:Streaming
Expenses:Entertainment:Books
Expenses:Travel:Flights
Expenses:Travel:Hotels
Expenses:Taxes:Federal
Expenses:Taxes:State
Expenses:Taxes:SocialSecurity
Expenses:Taxes:Medicare

; -- Patrimonio --
Equity:Opening-Balances
Equity:Retained-Earnings

Recursos Especificos do Fava​

Indicadores de Atualizacao​

Um dos melhores recursos do Fava para gerenciamento de contas. Adicione este metadado a qualquer conta:

2014-05-01 open Assets:US:BofA:Checking  USD
  fava-uptodate-indication: TRUE

O Fava entao exibe pontos coloridos ao lado da conta:

  • Ponto verde: o ultimo lancamento e uma verificacao de saldo aprovada (conta conciliada)
  • Ponto vermelho: o ultimo lancamento e uma verificacao de saldo reprovada (necessita atencao)
  • Ponto amarelo: existe um ultimo lancamento, mas nao e uma verificacao de saldo (ainda nao conciliado)
  • Ponto cinza: nenhuma atividade dentro do periodo de retrospecao

Configure o limite do ponto cinza:

2016-06-14 custom "fava-option" "uptodate-indicator-grey-lookback-days" "60"

Controles de Visualizacao em Arvore​

Controle como o Fava exibe as contas:

; Mostrar contas encerradas na arvore
2016-06-14 custom "fava-option" "show-closed-accounts" "true"

; Mostrar contas sem transacoes
2016-06-14 custom "fava-option" "show-accounts-with-zero-transactions" "true"

; Mostrar contas com saldo zero
2016-06-14 custom "fava-option" "show-accounts-with-zero-balance" "true"

Padroes de Recolhimento​

Recolha contas profundamente aninhadas por padrao:

; Recolher todas as contas com 3+ niveis de profundidade
2016-06-14 custom "fava-option" "collapse-pattern" ".*:.*:.*"

; Recolher subarvores especificas
2016-06-14 custom "fava-option" "collapse-pattern" "Assets:US:Vanguard:.*"

Incluir Subcontas no Diario da Conta​

Ao visualizar o diario de uma conta no Fava, inclua lancamentos das contas filhas:

2016-06-14 custom "fava-option" "account-journal-include-children" "true"

Inverter Sinais para Melhor Leitura​

Por padrao, receitas e passivos aparecem como numeros negativos (seu sinal natural). Para exibi-los como positivos:

2016-06-14 custom "fava-option" "invert-income-liabilities-equity" "true"

Gerenciamento de Documentos​

O Fava integra o gerenciamento de documentos com sua hierarquia de contas. Defina um diretorio raiz de documentos:

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

Depois organize os arquivos pelo caminho da conta:

/path/to/documents/
  Assets/
    US/
      BofA/
        Checking/
          2024-01-15.january-statement.pdf
          2024-02-15.february-statement.pdf
  Liabilities/
    US/
      Amex/
        Platinum/
          2024-03-15.march-bill.pdf

Arquivos que comecam com YYYY-MM-DD sao automaticamente descobertos pelo Fava e aparecem na visualizacao do diario da conta.

Erros Comuns e Como Evita-los​

1. Erros de Digitacao em Nomes de Contas​

Um unico erro de digitacao como Expenses:Grocries cria uma conta completamente nova e nao intencional.

Solucao: Nao use o plugin auto_accounts em producao. Exija diretivas open explicitas. O Beancount retornara imediatamente um erro para qualquer conta nao declarada:

ERROR: Invalid reference to unknown account 'Expenses:Grocries'

2. Esquecer Restricoes de Moeda​

Sem restricoes de moeda, voce pode acidentalmente lancar EUR em uma conta que deveria ser apenas USD.

Solucao: Sempre especifique moedas nas diretivas open:

2014-01-01 open Assets:US:BofA:Checking  USD

3. Nao Verificar Saldos Regularmente​

Sem verificacoes regulares de saldo, erros podem passar despercebidos por meses.

Solucao: Adicione verificacoes mensais de saldo para toda conta ativa:

2024-01-01 balance Assets:US:BofA:Checking   5,432.10 USD
2024-02-01 balance Assets:US:BofA:Checking   4,890.55 USD
2024-03-01 balance Assets:US:BofA:Checking   6,123.00 USD

4. Convencoes de Nomenclatura Inconsistentes​

Misturar padroes (ex.: Expenses:Food vs Expenses:US:Food) torna consultas e relatorios confusos.

Solucao: Escolha uma convencao e siga-a. Use prefixos de pais para contas do balanco patrimonial e nomenclatura baseada em categorias para receitas e despesas.

5. Encerrar Sem Verificacao de Saldo Zero​

A diretiva close nao verifica o saldo. Voce pode encerrar uma conta que ainda tem dinheiro.

Solucao: Sempre combine o encerramento com uma verificacao de saldo:

2023-12-31 balance Assets:US:OldBank:Savings  0.00 USD
2023-12-31 close Assets:US:OldBank:Savings

Padroes Avancados​

Dicas para Multiplas Moedas​

Declare suas moedas operacionais para colunas dedicadas nos relatorios:

option "operating_currency" "USD"
option "operating_currency" "EUR"

Para contas com multiplas moedas, liste todas as moedas permitidas:

2014-01-01 open Assets:Cash  USD,CAD,EUR

Verificacoes de saldo com multiplas moedas devem ser feitas uma moeda por vez:

2024-01-01 balance Assets:Cash     562.00 USD
2024-01-01 balance Assets:Cash     210.00 CAD
2024-01-01 balance Assets:Cash      60.00 EUR

Pad e Balance para Configuracao Inicial​

Use a diretiva pad para estabelecer saldos de abertura sem calcular manualmente os valores:

2000-05-28 open Assets:US:BofA:Checking  USD
2000-05-28 pad Assets:US:BofA:Checking  Equity:Opening-Balances
2024-07-01 balance Assets:US:BofA:Checking  12,345.67 USD

O Beancount sintetiza automaticamente a transacao de ajuste. Um detalhe importante: as verificacoes de saldo conferem o saldo no inicio da data especificada. Portanto, um pad no dia 2 de janeiro precisa de uma verificacao de saldo no dia 3 de janeiro ou posterior.

Metadados de Conta para Categorizacao​

Use metadados nas diretivas open para relatorios personalizados:

2014-01-01 open Assets:US:BofA:Checking  USD
  category: "liquid"
  tax-status: "taxable"

2014-01-01 open Assets:US:Vanguard:401k  USD
  category: "retirement"
  tax-status: "tax-deferred"

Consulte metadados com BQL:

SELECT account, META("category") WHERE META("tax-status") = "taxable"

Notas para Historico da Conta​

Anexe notas datadas ao diario de qualquer conta:

2024-03-20 note Assets:US:BofA:Checking "Ligou sobre cobranca contestada, ref #12345"
2024-06-01 note Liabilities:US:Chase:Sapphire "Anuidade isentada apos ligar para retencao"

Essas notas aparecem no diario da conta no Fava, fornecendo uma trilha de auditoria.

Contas de Rastreamento e Reservas​

O Beancount nao possui lancamentos virtuais como o Ledger, mas voce pode usar subcontas para reservas:

; Rastrear fundo de emergencia dentro da conta corrente
Assets:US:BofA:Checking:EmergencyFund    USD
Assets:US:BofA:Checking:Operating        USD

; Rastrear reembolsos
Assets:Receivables:Employer:Travel       USD
Assets:Receivables:Friend:SharedDinner   USD

Categorias de Despesas Amigaveis para Impostos​

Estruture contas de despesas para facilitar a preparacao de impostos:

Expenses:Health:Medical:Deductible
Expenses:Charity:Deductible
Expenses:Business:Office
Expenses:Business:Equipment
Expenses:Education:Professional

Guia Rapido de Referencia​

TarefaSintaxe
Abrir uma conta2024-01-01 open Assets:US:BofA:Checking USD
Encerrar uma conta2024-12-31 close Assets:US:OldBank:Savings
Verificar saldo2024-01-01 balance Assets:US:BofA:Checking 5,432.10 USD
Pad ate o saldo2024-01-01 pad Assets:Cash Equity:Opening-Balances
Adicionar nota2024-01-15 note Assets:US:BofA:Checking "Conciliacao mensal concluida"
Anexar documento2024-01-15 document Assets:US:BofA:Checking "/path/to/statement.pdf"
Adicionar metadadosChave-valor indentado na linha apos open
Auto-open (dev)plugin "beancount.plugins.auto_accounts"
Restringir moeda2024-01-01 open Assets:Cash USD,EUR
Definir metodo de alocacao2024-01-01 open Assets:US:ETrade:AAPL AAPL "FIFO"

Resumo​

Gerenciar bem as contas e a base de uma contabilidade eficaz no Beancount. Aqui estao os pontos principais:

  1. Sempre use diretivas open explicitas -- elas detectam erros de digitacao e impoem disciplina
  2. Adicione restricoes de moeda para evitar erros entre moedas
  3. Use uma convencao de nomenclatura consistente -- por instituicao para o balanco patrimonial, por categoria para receitas/despesas
  4. Comece simples e refine -- divida contas conforme suas necessidades de relatorio crescem
  5. Verifique saldos regularmente -- a conciliacao mensal detecta erros cedo
  6. Encerre contas corretamente -- com uma verificacao de saldo zero
  7. Aproveite os recursos do Fava -- indicadores de atualizacao, padroes de recolhimento e integracao de documentos
  8. Use metadados para categorizacao personalizada e relatorios

Boas contas!

References:
Share on TwitterFollow @beancount_io

Comece a usar o Beancount.io

Assuma o controle de suas finanças com nosso sistema de contabilidade de partidas dobradas de código aberto. Comece seu livro-razão hoje.

Começar GratuitamenteVer Preços

Primeiros Passos

Recursos

Comunidade

Jurídico

Beancount.io© 2019 - 2026 Beancount.io
Baixar na App StoreDisponível no Google Play
Construído com transparência • Controle de versão • Alimentado por IA