Tutorial do Beancount: instalação e primeiro livro-razão

Pronto para assumir o controle das suas finanças? Este guia fará você começar com o Beancount em minutos. Você aprenderá a criar seu primeiro livro-razão, configurar contas essenciais e registrar suas primeiras transações.

Explore o livro-razão ao vivo →

Configuração Inicial​

Criando Seu Primeiro Livro-razão​

; Basic structure for a new ledger
2024-01-01 open Assets:Checking
2024-01-01 open Equity:Opening-Balances
 
2024-01-02 * "Initial Deposit"
  Assets:Checking           100.00 USD
  Equity:Opening-Balances

Configuração Essencial​

option "title" "Personal Finance Ledger"
option "operating_currency" "USD"

Organização de Arquivos​

Estrutura Recomendada​

; 1. Configuration Options
option "title" "Personal Ledger"
option "operating_currency" "USD"
 
; 2. Account Declarations
2024-01-01 open Assets:Checking    USD
2024-01-01 open Assets:Savings     USD
2024-01-01 open Expenses:Food      USD
2024-01-01 open Equity:Opening-Balances
 
; 3. Initial Balances
; Pad fills the gap up to Equity:Opening-Balances, so it must be dated
; before the assertion. Balance assertions are checked at the start of
; their day, so assert the next morning.
2024-01-01 pad Assets:Checking Equity:Opening-Balances
2024-01-02 balance Assets:Checking 1000.00 USD
 
; 4. Transactions
2024-01-15 * "Grocery Store" "Weekly groceries"
  Expenses:Food            50.00 USD
  Assets:Checking

Organização de Seções​

1. Contas Eternas

   2024-01-01 open Liabilities:Payables    USD
   2024-01-01 open Assets:Receivables      USD

2. Contas Bancárias

   2024-01-01 open Assets:Bank:Checking     USD
   2024-01-01 open Assets:Bank:Savings      USD
   2024-01-01 open Income:Bank:Interest     USD

3. Contas de Investimento

   2024-01-01 open Assets:Investment:Cash    USD
   2024-01-01 open Assets:Investment:Stocks  VTSAX
   2024-01-01 open Income:Investment:Dividend USD

Validação e Relatórios​

Validação Básica​

# Check for errors (exits 0 when clean)
bea --file ledger.beancount check
 
# Browse balances, reports, and charts in the web interface
fava ledger.beancount

bea check é o validador: ele sai com código 0 quando o livro-razão está limpo, e lista todos os erros e sai com código diferente de zero caso contrário. Instale-o com o início rápido da CLI. Fava é a interface web — execute-o e abra o endereço http://localhost:5000 impresso para o balanço patrimonial, a demonstração de resultados e os diários de contas.

Relatórios Comuns​

O Beancount 3 produz relatórios através da interface web do Fava, do comando único bea report, ou de consultas ad-hoc com bea query, que executa a Linguagem de Consulta do Beancount. O Beancount 3 removeu seus comandos antigos de relatórios e da web; bea report e o Fava os substituem.

# Balance sheet, in one command
bea --file ledger.beancount report balance-sheet
 
# Income statement, in one command
bea --file ledger.beancount report income-statement
 
# Balance-sheet numbers: balances by asset, liability, and equity account
bea --file ledger.beancount query "SELECT account, sum(position) AS balance WHERE account ~ '^(Assets|Liabilities|Equity)' GROUP BY account ORDER BY account"
 
# Income-statement numbers: totals by income and expense account
bea --file ledger.beancount query "SELECT account, sum(position) AS total WHERE account ~ '^(Income|Expenses)' GROUP BY account ORDER BY account"
 
# One account's journal, with a running balance
bea --file ledger.beancount query "SELECT date, narration, position, balance WHERE account = 'Assets:Checking'"

Gerenciando Saldos Iniciais​

Exemplo de Preenchimento​

2024-01-01 open Assets:Checking    USD
2024-01-01 open Equity:Opening-Balances
 
; Pad account to match a known balance
2024-01-01 pad Assets:Checking Equity:Opening-Balances
 
; Assert the known balance the next day: assertions are evaluated at the
; start of their date, and the pad transaction must fall before it
2024-01-02 balance Assets:Checking 1525.00 USD

Uma asserção de balance verifica a conta no início de sua data, portanto deve ser datada após o pad (ou qualquer transação) que deve incluir. Datar o pad e o balance no mesmo dia deixa o pad não utilizado e a asserção insuficiente — o Beancount relata Unused Pad entry e Balance failed. A conta Equity:Opening-Balances deve ser aberta antes de ser preenchida contra ela.

Encerramento de Conta​

2024-01-01 open Assets:OldBank:Checking   USD
2024-06-30 close Assets:OldBank:Checking  ; Account closed

Deduplicação de Transações​

Tratamento de Transferências​

; Credit card payment - combined view
2024-01-15 * "Credit Card Payment"
  Assets:Checking            -500.00 USD
  Liabilities:CreditCard     500.00 USD
 
; Flag for pending match
2024-01-15 * "Pending CC Payment"
  ! Assets:Checking         -500.00 USD
  Liabilities:CreditCard    500.00 USD

Asserções de Saldo​

; Regular balance checks prevent duplicates
2024-01-31 balance Assets:Checking    2150.25 USD
2024-01-31 balance Liabilities:CreditCard  -350.00 USD

Melhores Práticas​

1. Organização de Arquivos

   • Mantenha um arquivo principal inicialmente
   • Use cabeçalhos de seção claros
   • Agrupe contas relacionadas

2. Nomes de Contas

   • Use convenções de nomenclatura consistentes
   • Inclua prefixos de país/instituição
   • Mantenha uma hierarquia lógica

3. Verificação de Saldos

   • Asserções de saldo regulares
   • Preencha contas adequadamente
   • Rastreie encerramentos de contas

4. Tratamento de Moedas

   • Declare moedas operacionais
   • Use códigos de mercadoria consistentes
   • Especifique restrições de moeda

Próximos Passos​

Agora que você tem um livro-razão básico configurado:

1. Registre Transações Regulares: Comece com suas despesas e receitas diárias
2. Configure Importações de Contas Bancárias: Use importações CSV ou conexões bancárias para automatizar a entrada de dados. Cole uma exportação de extrato no conversor CSV para Beancount para obter lançamentos balanceados em seu navegador, ou use OFX & QIF para Beancount para downloads .ofx, .qfx e .qif.
3. Copie um Layout Comprovado: Baixe um arquivo inicial executável das seções doméstica, orçamento por envelopes ou freelancer dos exemplos de livros-razão funcionais, depois adapte os padrões de propriedade e investimento da mesma galeria
4. Aprenda Sintaxe Avançada: Explore a referência de sintaxe para cenários mais complexos
5. Gere Seus Primeiros Relatórios: Use os recursos da interface para criar relatórios financeiros e analisar seus gastos
6. Trabalhe pelo Terminal: Instale a linha de comando bea com o início rápido da CLI, depois feche um mês completo de ponta a ponta em Seu primeiro mês com bea

Referência Rápida​

Tipos Comuns de Contas:

• Assets:Bank:Checking - Sua conta corrente
• Expenses:Food:Groceries - Gastos com supermercado
• Income:Salary:Company - Renda de emprego
• Liabilities:CreditCard:Visa - Dívida de cartão de crédito

Comandos Essenciais:

• bea --file ledger.beancount check - Valide seu livro-razão (sai com código diferente de zero em erros)
• bea --file ledger.beancount report balance-sheet - Imprima um balanço patrimonial
• bea --file ledger.beancount query "SELECT ..." - Consulte saldos e transações
• fava ledger.beancount - Lance a interface web para relatórios e gráficos

Estas diretrizes estabelecem uma base sólida para gerenciar finanças pessoais com o Beancount. Pronto para adicionar sua primeira transação? Confira nosso guia de transações pela interface.