Glossário de Beancount e contabilidade em texto simples

A contabilidade em texto puro toma emprestado o vocabulário da escrituração por partidas dobradas e acrescenta algumas palavras próprias do Beancount. Este glossário define os termos que você encontrará ao ler esta documentação ou o seu próprio arquivo de razão, cada um com um pequeno exemplo quando isso ajuda. Cada verbete tem seu próprio link, para que você possa apontar um colega direto para uma definição.

Conta​

Uma conta é um compartimento nomeado que rastreia um fluxo de valor, escrito como uma hierarquia separada por dois-pontos sob um dos cinco tipos raiz: Assets, Liabilities, Equity, Income ou Expenses. A hierarquia é toda a estrutura organizacional dos seus livros — Assets:US:BofA:Checking e Expenses:Food:Restaurant se ordenam e se agregam automaticamente. Toda conta precisa ser declarada antes de ser usada. Consulte Sintaxe da Linguagem Beancount para as regras de nomenclatura.

Regime de competência​

A contabilidade por regime de competência registra a receita quando ela é auferida e as despesas quando são incorridas, independentemente de quando o dinheiro efetivamente circula. A contabilidade por regime de caixa faz o oposto: reconhece ambos apenas quando o dinheiro muda de mãos. O regime de competência dá uma visão mais fiel do desempenho de um período, e é por isso que uma fatura que você enviou em março pertence a março, mesmo que o cliente pague em maio.

Amortização​

A amortização distribui um único pagamento grande pelos períodos que ele efetivamente cobre, de modo que cada mês carrega sua parcela justa do custo. Um prêmio de seguro anual pago em janeiro é uma despesa dos doze meses, não apenas de janeiro. No Beancount você escreve os lançamentos divididos à mão ou os gera com um plugin — consulte Amortizar.

Verificação de saldo​

Uma asserção de saldo é uma diretiva balance que declara qual deve ser o saldo de uma conta no início de uma data determinada, transformando seu extrato bancário em uma verificação automática dos seus livros. Se o saldo calculado diferir além da tolerância da asserção, o Beancount falha ruidosamente, mostrando os valores esperado e real. Essa tolerância é uma unidade da última casa decimal que você escreveu — 4.27 RGAGX aceita qualquer coisa de 4,26 a 4,28 — e um ~ antes da moeda define a sua própria. Espalhar uma asserção por conta por extrato é a maneira mais barata de manter um razão confiável.

2026-01-01 balance Assets:US:BofA:Checking   4,321.00 USD

Beancount​

Beancount é um sistema de contabilidade por partidas dobradas de código aberto cujo razão é um arquivo de texto puro que você edita em qualquer editor de texto e valida com uma ferramenta de linha de comando. Ele oferece uma sintaxe estrita e analisável, uma linguagem de consulta e uma interface web, sem banco de dados nem formato de arquivo proprietário. Como o razão é texto, ele vive tranquilamente no Git junto com o seu código. Comece pela Introdução ao Beancount.

Linguagem de Consulta Beancount​

Beancount Query Language, geralmente abreviada como BQL, é a linguagem semelhante a SQL que você usa para fazer perguntas ao seu razão. Ela opera sobre as diretivas analisadas, não sobre um banco de dados, então SELECT account, sum(position) WHERE year = 2026 responde imediatamente a partir do mesmo arquivo que você edita. Leia o guia da linguagem de consulta para a gramática completa.

Método de alocação​

Um método de booking é a regra que o Beancount aplica quando uma redução precisa escolher quais lotes existentes baixar. O Beancount 3.2.3 aceita sete nomes: STRICT (o padrão, em que você mesmo identifica o lote), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO e AVERAGE. Defina um por conta na sua diretiva open, ou para o arquivo inteiro com option "booking_method". Seis dos sete estão implementados: AVERAGE é analisado, mas gera AVERAGE method is not supported no momento em que precisa registrar uma redução. O método que você escolhe altera seus ganhos de capital realizados, então escolha o que sua jurisdição fiscal espera e mantenha-o estável. Gestão de Inventário executa todos os sete sobre os mesmos lotes e publica o razão que falha sob AVERAGE.

Plano de contas​

Um plano de contas é a lista completa de contas que seu razão usa, junto com a estrutura que as organiza. No Beancount não há um arquivo de plano de contas separado — o conjunto de diretivas open é o seu plano de contas. Projetá-lo bem desde cedo economiza muita renomeação depois; consulte Configurações Específicas por Setor para pontos de partida.

Diretiva Close​

Uma diretiva close marca a data após a qual uma conta não pode mais ser usada, o que é como você aposenta uma conta bancária ou um empréstimo quitado sem apagar seu histórico. As transações passadas continuam válidas e reportáveis; apenas novos lançamentos são rejeitados. Fechar contas não utilizadas mantém os relatórios legíveis à medida que um razão envelhece.

2026-03-31 close Assets:US:OldBank:Checking

Mercadoria​

Uma commodity é qualquer unidade de valor que seu razão rastreia — uma moeda como USD, um ticker de ação como AAPL, um criptoativo como BTC ou algo que você inventa, como VACATION-DAYS. O Beancount nunca converte entre commodities pelas suas costas, então um valor é sempre um número emparelhado com a commodity em que é denominado. Uma diretiva commodity opcional permite anexar metadados como um nome ou uma classe de ativo.

Base de custo​

A base de custo é o que você efetivamente pagou por uma posição, registrado na moeda com que pagou e carregado junto com a posição enquanto você a possuir. O Beancount a escreve entre chaves — 10 AAPL {150.00 USD} significa dez ações adquiridas a 150 dólares cada. Dobre as chaves e o número passa a ser o total em vez do preço unitário, então 10 AAPL {{1,500.00 USD}} registra o mesmo lote. Como a base viaja com a posição, os ganhos de capital saem da aritmética quando você vende. Consulte Gestão de Inventário.

Diretiva​

Uma diretiva é uma instrução em um arquivo Beancount, geralmente datada, e as diretivas são do que um razão é feito. Doze tipos carregam uma data: open, close, balance, price, note, document, pad, event, commodity, custom, query e a própria transação. Algumas não carregam nenhuma e agem sobre o arquivo em vez de sobre um dia — option, include, plugin e o par pushtag/poptag. O Beancount ordena as datadas por data antes de processar, então você pode mantê-las na ordem que fizer mais sentido ler; uma sem data entra em vigor onde está escrita.

Contabilidade de partidas dobradas​

A escrituração por partidas dobradas é a prática de registrar cada evento econômico como pelo menos dois lançamentos correspondentes, de modo que seus pesos sempre somem zero. O dinheiro nunca é criado nem destruído — ele apenas se move entre contas, e é por isso que a técnica captura erros que uma lista de coluna única jamais capturaria. Um peso é o próprio valor de um lançamento, ou seu custo ou preço convertido de volta para uma única moeda, então duas pernas em commodities diferentes ainda se cancelam. O Beancount aplica a regra com rigor: uma transação cujos lançamentos não balanceiam é um erro, não um aviso.

2026-03-02 * "Bank" "Buy euros"
  Assets:US:BofA:EUR       100.00 EUR @ 1.08 USD
  Assets:US:BofA:Checking -108.00 USD

Orçamento por envelopes​

O orçamento por envelopes reserva dinheiro para uma finalidade antes de você gastá-lo, de modo que cada categoria tem seu próprio limite em vez de competir por um único saldo comum. O nome vem dos envelopes de papel que as pessoas enchiam de dinheiro no dia do pagamento. Em um razão de texto puro você modela envelopes com contas dedicadas ou diretivas de orçamento — consulte Orçamentos.

Fava​

Fava é a interface web do Beancount: gráficos, balanços patrimoniais, demonstrações de resultado, um editor de consultas e um formulário de entrada, servidos a partir do seu arquivo de razão. É majoritariamente de leitura e roda localmente, então muda como você vê seus livros sem mudar como você os registra. O beancount.io hospeda uma versão gerenciada junto com suas próprias ferramentas; o guia Recursos da Interface cobre o que você pode fazer lá.

Inventário​

Um inventário é a coleção de posições que uma conta detém atualmente, cada uma com sua própria commodity e, quando relevante, sua própria base de custo e data de aquisição. Uma conta de corretora que comprou a mesma ação três vezes detém três lotes separados em um inventário, não um número combinado. Manter os lotes distintos é o que torna possível cálculos precisos de ganhos.

Diário​

O diário é a lista cronológica de tudo o que aconteceu nos seus livros — o fluxo bruto de transações, em ordem de data, antes de qualquer agrupamento ou resumo. É a visão que você percorre quando quer responder "o que eu realmente fiz em março?". A página de diário do Fava costuma ser o lugar mais rápido para identificar um lançamento mal categorizado.

Ledger​

Um razão é o conjunto completo de registros contábeis de uma entidade, o que no Beancount significa seu arquivo de texto puro (mais tudo o que ele inclui). A palavra serve tanto como o nome de todo o livro de contas quanto como o nome do próprio arquivo. Como é texto, um razão pode ser comparado, revisado, ramificado e mesclado como código-fonte.

Lote​

Um lote é uma aquisição específica de uma commodity, identificada por sua base de custo e data de aquisição. Comprar o mesmo ETF em janeiro e de novo em junho cria dois lotes, e vender depois significa escolher qual lote você está vendendo. Os lotes são a razão pela qual o Beancount pode calcular ganhos realizados com exatidão em vez de aproximá-los.

2026-06-15 * "Broker" "Buy VTI"
  Assets:US:Broker:VTI     5 VTI {260.00 USD, 2026-06-15}
  Assets:US:Broker:Cash            -1,300.00 USD

Narração​

A narração é a descrição em texto livre do que uma transação representava, escrita como a segunda string entre aspas na linha da transação. Ela é para humanos: "Aluguel mensal", "Mercado e casa". O Beancount não a analisa, mas é o que você vai ler quando o lançamento não fizer mais sentido daqui a seis meses.

Diretiva Open​

Uma diretiva open declara uma conta, a data em que ela começa a ser utilizável e, opcionalmente, as commodities que ela pode conter e o método de booking que usa. O Beancount exige que toda conta seja aberta antes de seu primeiro lançamento, o que impede que um erro de digitação crie silenciosamente uma conta totalmente nova. Restringir as commodities permitidas transforma outra classe inteira de erros em erros explícitos.

2026-01-01 open Assets:US:Broker:VTI   VTI   "FIFO"

Pad​

Uma diretiva pad diz ao Beancount para inserir qualquer valor necessário para fazer a próxima asserção de saldo de uma conta ter sucesso, lançando a diferença em uma segunda conta. Ela existe para exatamente uma função: abrir um razão no meio do caminho sem reconstruir anos de histórico. Fazer pad além dessa configuração inicial geralmente significa que um erro real está sendo maquiado.

Beneficiário​

O favorecido é com quem você transacionou, escrito como a primeira string entre aspas na linha da transação. Manter os favorecidos consistentes — sempre "Whole Foods", nunca às vezes "WholeFoods" — é o que faz os relatórios baseados em favorecido e os importadores automatizados funcionarem. O Beancount trata o favorecido como opcional; uma transação pode carregar apenas uma narração.

Plain-text accounting​

A contabilidade em texto puro é a prática de manter seus livros em um arquivo de texto legível por humanos sob controle de versão, processado por ferramentas de linha de comando de código aberto. Ela troca uma interface de apontar e clicar por durabilidade, auditabilidade e automação: seus dados sobrevivem a qualquer fornecedor, toda mudança é um diff revisável e qualquer script pode lê-lo. Beancount, Ledger e hledger são as três implementações mais conhecidas.

Plugin​

Um plugin é um módulo Python que o Beancount carrega ao processar seu arquivo, permitindo adicionar, transformar ou validar diretivas antes que os relatórios sejam construídos. Plugins são como previsões, cronogramas de amortização e verificações personalizadas são implementados sem alterar a linguagem central. Você habilita um com uma linha plugin independente no topo do seu razão, nunca com uma option — option "plugin" "…" é rejeitado com Option 'plugin' may not be set. O guia Plugin de Previsão percorre um exemplo real.

Lançamento​

Um lançamento é uma perna de uma transação: uma conta, um valor e, opcionalmente, um custo ou preço. O que precisa somar zero em uma transação não são os valores brutos, mas seus pesos: um valor simples pesa a si mesmo, 10 FUND @ 38.46 USD pesa 384.60 USD e 10 FUND {384.61 USD} pesa 3,846.10 USD, porque chaves simples contêm o custo de uma unidade. No máximo um lançamento pode deixar seu valor em branco, caso em que o Beancount calcula a cifra de balanceamento para você. Consulte Precisão e Tolerâncias para as regras completas de peso.

Diretiva Price​

Uma diretiva price registra a taxa de câmbio entre duas commodities em uma data, que é como o Beancount converte uma posição para seu valor de mercado nos relatórios. Uma diretiva price é puro dado de referência: ela não move dinheiro e não pertence a nenhuma transação. Não a confunda com o preço @ escrito dentro de um lançamento, que é aritmética — ele dá a 10 FUND @ 38.46 USD um peso de 384.60 USD e, portanto, decide se a transação balanceia. Sem diretivas de preço, uma carteira ainda balanceia pelo custo, mas não pode ser avaliada a mercado.

2026-06-30 price VTI   271.40 USD

Preços ao Vivo fornece diretivas de preço gerenciadas para ativos suportados em razões hospedados. Seu próprio preço prevalece para a mesma data e par, incluindo o par recíproco. Um preço gerenciado em uma data posterior ainda pode se aplicar a uma avaliação posterior.

Conciliação​

A conciliação é o ato de provar que seus livros concordam com um registro externo, como um extrato bancário ou de corretora. Na contabilidade em texto puro ela é em grande parte mecânica: adicione uma asserção de saldo para cada data de extrato e deixe a ferramenta dizer se os números batem. Um razão que concilia limpo todo mês é aquele do qual você pode declarar impostos sem medo.

Tags e links​

Tags e links são os dois rótulos que você anexa às transações para agrupá-las fora da hierarquia de contas: uma tag com # marca um tema como #trip-japan, e um link com ^ amarra lançamentos relacionados como ^invoice-2026-014 entre si. As tags respondem "mostre-me tudo nesta categoria"; os links respondem "mostre-me os lançamentos que pertencem a este evento". Ambos são filtráveis no Fava e consultáveis em BQL — consulte Filtragem e Busca.

Transação​

Uma transação é um evento econômico datado junto com os lançamentos que o registram, e é a diretiva que você escreverá com mais frequência. Ela carrega um sinalizador (* para confirmada, ! para precisa de revisão), um favorecido opcional, uma narração e dois ou mais lançamentos cujos pesos somam zero. Todo o resto em um arquivo Beancount existe para declarar, verificar ou anotar transações.

2026-02-14 * "Blue Bottle" "Coffee with Dana"
  Expenses:Food:Coffee      9.50 USD
  Assets:US:BofA:Checking  -9.50 USD

Ainda travado em uma palavra? A Central de Ajuda indexa todos os guias deste site, e a Cola Rápida coloca a sintaxe de cada diretiva lado a lado.