Glossário

O plain-text accounting empresta vocabulário da contabilidade de partidas dobradas e adiciona algumas palavras específicas do Beancount. Este glossário define os termos que você encontrará ao ler estes documentos ou o seu próprio arquivo de ledger, cada um com um breve exemplo quando ajuda. Cada entrada tem seu próprio link, para que você possa apontar um colega diretamente para uma definição.

Conta​

Uma conta é um agrupamento nomeado que rastreia um fluxo de valor, escrito como uma hierarquia separada por dois-pontos sob um dos cinco tipos de raiz: Assets, Liabilities, Equity, Income ou Expenses. A hierarquia é toda a estrutura organizacional dos seus livros — Assets:US:BofA:Checking e Expenses:Food:Restaurant são classificados e agregados automaticamente. Toda conta deve ser declarada antes de ser usada. Veja 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 é ganha e as despesas quando são incorridas, independentemente de quando o dinheiro efetivamente se move. A contabilidade por regime de caixa faz o oposto: reconhece ambos apenas quando o dinheiro muda de mãos. A competência dá uma imagem mais fiel do desempenho de um período, por isso 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 realmente cobre, para que cada mês carregue sua parcela justa do custo. Um prêmio de seguro anual pago em janeiro é uma despesa de todos os doze meses, não apenas de janeiro. No Beancount, você escreve os lançamentos divididos manualmente ou os gera com um plugin — veja Amortizar.

Verificação de saldo​

Uma verificação de saldo é uma diretiva balance que declara qual deve ser o saldo de uma conta no início de uma determinada data, para que seu extrato bancário se torne uma verificação automática dos seus livros. Se o saldo calculado diferir em mais do que a tolerância da verificação, o Beancount falha ruidosamente com 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 verificação por conta por extrato é a maneira mais barata de manter um ledger confiável.

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

Beancount​

Beancount é um sistema de contabilidade de partidas dobradas de código aberto cujo ledger é um arquivo de texto simples 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 ou formato de arquivo proprietário. Como o ledger é texto, ele vive feliz no Git junto com seu código. Comece com Introdução ao Beancount.

Linguagem de Consulta Beancount​

A Linguagem de Consulta Beancount, geralmente abreviada como BQL, é a linguagem semelhante a SQL que você usa para fazer perguntas ao seu ledger. Ela é executada sobre as diretivas analisadas, em vez de 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 alocação é a regra que o Beancount aplica quando uma redução precisa escolher quais lotes existentes serão usados. O Beancount 3.2.3 aceita sete nomes: STRICT (o padrão, onde você identifica o lote você mesmo), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO e AVERAGE. Defina um por conta na diretiva open, ou para o arquivo inteiro com option "booking_method". Seis dos sete são implementados: AVERAGE é analisado, mas gera AVERAGE method is not supported no momento em que precisa alocar uma redução. O método que você escolher muda 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 ledger que falha sob AVERAGE.

Plano de contas​

Um plano de contas é a lista completa de contas que seu ledger usa, juntamente com a estrutura que as organiza. No Beancount, não há um arquivo de plano separado — o conjunto de diretivas open é o seu plano de contas. Projetá-lo bem desde o início economiza muita renomeação depois; veja 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, que é como você aposenta uma conta bancária ou um empréstimo quitado sem apagar seu histórico. Transações passadas permanecem 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 ledger envelhece.

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

Mercadoria​

Uma mercadoria é qualquer unidade de valor que seu ledger rastreia — uma moeda como USD, um ticker de ação como AAPL, um ativo cripto como BTC, ou algo que você inventa, como VACATION-DAYS. O Beancount nunca converte entre mercadorias por conta própria, então um valor é sempre um número emparelhado com a mercadoria em que é denominado. Uma diretiva commodity opcional permite anexar metadados, como um nome ou uma classe de ativo.

Base de custo​

Base de custo é o que você realmente pagou por uma participação, registrado na moeda com que pagou e carregado junto com a participação enquanto você a possui. O Beancount escreve isso entre chaves — 10 AAPL {150.00 USD} significa dez ações adquiridas a 150 dólares cada. Dobre as chaves e o número se torna 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 emergem da aritmética quando você vende. Veja Gestão de Inventário.

Diretiva​

Uma diretiva é uma instrução em um arquivo Beancount, geralmente datada, e diretivas são do que um ledger é 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 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 for melhor para leitura; uma não datada tem efeito onde é escrita.

Contabilidade de partidas dobradas​

A contabilidade de partidas dobradas é a prática de registrar cada evento econômico como pelo menos duas entradas correspondentes, de modo que seus pesos sempre somem zero. O dinheiro nunca é criado nem destruído — ele apenas se move entre contas, por isso a técnica detecta erros que uma lista de coluna única nunca detectaria. Um peso é o valor próprio de um lançamento, ou seu custo ou preço convertido de volta em uma moeda, então duas pernas em mercadorias diferentes ainda se cancelam. O Beancount aplica a regra estritamente: uma transação cujos lançamentos não fecham é 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 um propósito antes de você gastá-lo, de modo que cada categoria tenha seu próprio limite em vez de competir por um saldo único. O nome vem dos envelopes de papel que as pessoas enchiam com dinheiro no dia do pagamento. Em um ledger de texto simples, você modela envelopes com contas dedicadas ou diretivas de orçamento — veja Orçamentos.

Fava​

Fava é a interface web do Beancount: gráficos, balanços patrimoniais, demonstrativos de resultados, um editor de consultas e um formulário de entrada, servidos a partir do seu arquivo de ledger. É principalmente de leitura e roda localmente, então muda como você vê seus livros sem mudar como os registra. o beancount.io hospeda uma versão gerenciada junto com suas próprias ferramentas; o guia Recursos de 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 mercadoria e, quando relevante, sua própria base de custo e data de aquisição. Uma 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íveis cálculos precisos de ganhos.

Diário​

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

Ledger​

Um ledger é o conjunto completo de registros contábeis de uma entidade, que no Beancount significa seu arquivo de texto simples (mais qualquer coisa que ele inclua). A palavra também serve como o nome de todo o livro de contas e o nome do arquivo em si. Como é texto, um ledger pode ser comparado (diff), revisado, ramificado e mesclado como código-fonte.

Lote​

Um lote é uma aquisição específica de uma mercadoria, identificada por sua base de custo e data de aquisição. Comprar o mesmo ETF em janeiro e novamente 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 exatamente 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 de para que serviu uma transação, escrita como a segunda string entre aspas na linha da transação. É para humanos: "Aluguel mensal", "Mercado e itens domésticos". O Beancount não a analisa, mas é o que você lerá quando a entrada não fizer mais sentido seis meses depois.

Diretiva Open​

Uma diretiva open declara uma conta, a data em que ela começa a ser utilizável e, opcionalmente, as mercadorias que ela pode conter e o método de alocação 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 nova. Restringir as mercadorias permitidas transforma toda outra classe de erros em erros.

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

Pad​

Uma diretiva pad diz ao Beancount para inserir o valor que for necessário para fazer a próxima verificação de saldo em uma conta ser bem-sucedida, lançando a diferença em uma segunda conta. Ela existe para exatamente um trabalho: abrir um ledger no meio da vida sem reconstruir anos de histórico. Usar "pad" além dessa configuração inicial geralmente significa que um erro real está sendo encoberto.

Beneficiário​

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

Plain-text accounting​

Plain-text accounting é 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 código aberto de linha de comando. Ele troca uma interface de apontar e clicar por durabilidade, auditabilidade e automação: seus dados sobrevivem a qualquer fornecedor, cada 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. Os plugins são como previsão, cronogramas de amortização e verificações personalizadas são implementados sem mudar a linguagem central. Você ativa um com uma linha plugin autônoma no topo do seu ledger, 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 o valor de equilíbrio para você. Veja Precisão e Tolerâncias para as regras completas de peso.

Diretiva Price​

Uma diretiva price registra a taxa de câmbio entre duas mercadorias em uma data, que é como o Beancount converte uma participação ao seu valor de mercado nos relatórios. Uma diretiva price é puramente dados de referência: 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ético — ele dá a 10 FUND @ 38.46 USD um peso de 384.60 USD e assim decide se a transação fecha. Sem diretivas de preço, uma carteira ainda fecha ao custo, mas não pode ser avaliada a mercado.

2026-06-30 price VTI   271.40 USD

Conciliação​

Conciliação é o ato de comprovar que seus livros concordam com um registro externo, como um extrato bancário ou de corretora. No plain-text accounting, é em grande parte mecânico: adicione uma verificação de saldo para cada data de extrato e deixe a ferramenta dizer se os números batem. Um ledger que concilia limpo todo mês é um 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 entradas relacionadas como ^invoice-2026-014. Tags respondem "mostre-me tudo nesta categoria"; links respondem "mostre-me as entradas que pertencem a este evento". Ambos são filtráveis no Fava e consultáveis em BQL — veja Filtragem e Busca.

Transação​

Uma transação é um evento econômico datado juntamente com os lançamentos que o registram, e é a diretiva que você escreverá com mais frequência. Ela carrega um sinalizador (* para confirmado, ! para precisa de revisão), um beneficiário 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 preso em uma palavra? O Central de Ajuda indexa todos os guias deste site, e o Cheatsheet coloca a sintaxe de cada diretiva lado a lado.