# O Ciclo Contábil, Estilo Beancount

Os demonstrativos financeiros não aparecem por mágica. Eles são o produto final de um processo estruturado e repetível conhecido como **ciclo contábil**. Embora os princípios sejam universais, as ferramentas que você usa podem mudar drasticamente a experiência. Este guia conduz você pelo ciclo contábil com foco no **Beancount**, a poderosa ferramenta de contabilidade em texto simples.

Veremos como a abordagem text‑first do Beancount elimina etapas tediosas, o que você deve automatizar e quais relatórios oferecem a visão mais clara da sua saúde financeira. 🧑‍💻

---

## TL;DR: O Fluxo de Trabalho no Beancount

- **Captura & Diário:** Registre cada transação como uma postagem limpa de partida dobrada no seu arquivo de texto `.beancount`.
- **Validar & Conciliar:** Use as asserções `balance` para confirmar que seu razão corresponde aos extratos bancários e execute `bean-check` para detectar erros.
- **Revisar:** Gere um trial balance não ajustado para uma verificação rápida de sanidade.
- **Ajustar:** Publique lançamentos para accruals, deferrals, depreciação e outros itens de fim de período.
- **Re‑revisar:** Verifique o trial balance ajustado para garantir que tudo esteja correto.
- **Publicar & Fechar:** Gere sua Demonstração de Resultados, Balanço Patrimonial e Demonstração de Fluxo de Caixa. O fechamento dos livros é opcional no Beancount, pois os relatórios são sensíveis a datas.

Este fluxo pode ser visualizado assim:

```mermaid
graph TD
  A[Raw data - bank exports, receipts, invoices] --> B[Beancount Journal .beancount file]
  B --> C[Validation & Reconciliation<br/><code>balance</code> assertions · <code>bean-check</code>]
  C --> D[Unadjusted Trial Balance<br/><code>bean-query</code> · Fava]
  D --> E[Adjusting Entries<br/>accruals · deferrals · tax]
  E --> F[Adjusted Trial Balance]
  F --> G[Financial Statements<br/>P&amp;L · Balance Sheet · Cash Flow]
  G --> H[Closing - Retained Earnings]
  H -- new period --> B
```

---

## Etapa 1: Capturar e Registrar Transações

Esta é a etapa fundamental. Todo evento financeiro — uma venda, uma compra, uma taxa bancária — deve ser registrado. No Beancount, você faz isso criando transações em um simples arquivo de texto, tipicamente chamado `main.beancount` ou organizado em múltiplos arquivos por ano.

Cada transação deve seguir as regras da contabilidade de partida dobrada, ou seja, a soma de todas as postagens deve ser zero. O Beancount impõe isso para você.

```beancount
2025-08-10 * "Walmart" "Purchase of office supplies"
  Expenses:Office:Supplies      45.67 USD
  Assets:Bank:Checking         -45.67 USD
```

- **Dica Profissional:** Use tags como `#project-phoenix` ou `#client-acme` para adicionar dimensões aos seus dados. Isso torna a consulta e os relatórios incrivelmente flexíveis mais tarde.

### Higiene de Reconciliação ✅

O recurso mais poderoso para garantir precisão é a **asserção de balance**. No final de um período de extrato (por exemplo, fim do mês), você declara qual _deve_ ser o saldo de uma conta.

```beancount
2025-08-31 balance Assets:Bank:Checking  12345.67 USD
```

Se a soma de todas as transações que afetam `Assets:Bank:Checking` até essa data não for igual a `12345.67 USD`, o Beancount emitirá um erro. Esta simples diretiva transforma seu razão em um documento auto‑auditado.

Para quem está retroalimentando dados históricos, a diretiva `pad` pode criar automaticamente uma transação de balanceamento para fazer seus saldos de abertura coincidirem com sua primeira asserção.

---

## Etapa 2: “Postar no Razão” (Um Brinde !)

Em sistemas contábeis tradicionais, você primeiro escreve lançamentos em um “diário” e depois um passo separado de “postagem” copia esses valores para o “razão geral”.

Com o Beancount, **seu arquivo `.beancount` é simultaneamente o diário e o razão**. Quando você escreve e salva uma transação, já a postou. Não há etapa separada. Essa diretividade é uma vantagem central da contabilidade em texto simples — o que você vê é o que obtém.

---

## Etapa 3: Preparar um Trial Balance Não Ajustado

Antes de começar a fazer ajustes, você precisa de uma verificação rápida “tudo soma?”. Um **trial balance** é um relatório simples que lista cada conta e seu saldo total. O total geral de saldos de débito deve ser igual ao total geral de saldos de crédito.

Você pode gerar isso com uma consulta simples:

```bash
bean-query main.beancount \
  "SELECT account, sum(position) GROUP BY 1 ORDER BY 1"
```

Ou, para uma abordagem mais visual, abra seu razão no **Fava** (a interface web do Beancount) e navegue até o relatório “Trial Balance”. Procure por algo incomum — uma conta de ativo com saldo credor, ou uma conta de despesa com valor estranho.

---

## Etapa 4: Lançar Ajustes

Lançamentos de ajuste são cruciais para relatórios precisos sob o **regime de competência** da contabilidade. Eles garantem que receitas sejam reconhecidas quando ganhas e despesas quando incorridas, independentemente de quando o caixa se move.

Ajustes comuns incluem:

- **Accruals:** Registro de receita que você já ganhou mas ainda não faturou, ou despesa que já incorrida mas ainda não paga.
- **Deferrals:** Tratamento de pré‑pagamentos. Se um cliente paga antecipadamente por um ano de serviço, você registra como passivo (`Liabilities:UnearnedRevenue`) e reconhece 1/12 dele como receita a cada mês.
- **Itens Não Monetários:** Registro de depreciação de ativos.
- **Correções:** Conserto de erros ou contabilização de itens perdidos em feeds bancários, como um pequeno pagamento de juros.

#### **Exemplo: Accrual de Receita**

Você finalizou um projeto em 31 de agosto, mas só enviará a fatura em setembro. Para reconhecer a receita no período correto (agosto), faça um lançamento de ajuste:

```beancount
2025-08-31 * "Accrue revenue for client project #1042"
  Assets:AccountsReceivable      3000.00 USD
  Income:Consulting             -3000.00 USD
```

#### **Exemplo: Registro de Depreciação**

Sua empresa tem um cronograma de depreciação para seus ativos. No fim do período, registre a despesa:

```beancount
2025-12-31 * "Annual depreciation on computer equipment"
  Expenses:Depreciation                  4800.00 USD
  Assets:Fixed:AccumulatedDepreciation  -4800.00 USD
```

---

## Etapa 5: Executar um Trial Balance Ajustado & Validar

Depois que seus lançamentos de ajuste estiverem inseridos, execute o relatório de trial balance novamente. Este é o seu **Adjusted Trial Balance**. Ele fornece o conjunto final de números que será usado para criar os demonstrativos financeiros.

Este também é o momento perfeito para rodar a verificação de sanidade embutida do Beancount:

```bash
bean-check main.beancount
```

Este comando verifica toda a sintaxe, regras de balanceamento e asserções. Se ele terminar sem saída, seus livros estão mecanicamente corretos.

---

## Etapa 6: Publicar Demonstrativos Financeiros 📊

Esta é a recompensa. Usando os números do seu adjusted trial balance, você pode gerar os relatórios financeiros principais. O Fava é a maneira mais fácil de fazer isso, pois fornece relatórios interativos e detalhados prontos para uso.

- **Demonstração de Resultados (Profit & Loss):** Mostra suas receitas e despesas ao longo de um período, resultando em seu lucro ou prejuízo líquido.
- **Balanço Patrimonial:** Um instantâneo do que você possui (Ativos) e do que deve (Passivos), além do seu patrimônio líquido (Equity), em uma data específica.
- **Demonstração de Fluxo de Caixa:** Reconcilia seu caixa inicial com o final mostrando de onde o dinheiro veio e para onde foi.

Para relatórios personalizados, você pode usar a Beancount Query Language (BQL). Aqui está uma consulta para uma demonstração de resultados mensal:

```sql
-- P&L for August 2025
SELECT account, sum(position)
WHERE account   '^(Income|Expenses)'
  AND date >= 2025-08-01 AND date <= 2025-08-31
GROUP BY account ORDER BY account;
```

---

## Etapa 7: Fechamento dos Livros (Opcional)

Na contabilidade tradicional, o processo de “fechamento” envolve criar lançamentos que zeram todas as contas temporárias (Receitas e Despesas) e transferem o lucro líquido para uma conta de equity chamada **Retained Earnings**. Isso reinicia formalmente as contas temporárias para o próximo ano.

**No Beancount, esse passo geralmente é desnecessário.** Os relatórios do Fava são sensíveis a datas; se você solicitar um P&L de 2025, ele usará apenas dados de 2025. Os saldos não “transbordam”. A maioria dos usuários simplesmente deixa os saldos como estão.

Entretanto, se você precisar fazer um fechamento formal por questões de conformidade ou relatório a acionistas, pode fazê‑lo com uma simples transação de fim de ano que move os saldos totais de receitas e despesas para `Equity:Retained-Earnings`.

---

## Checklist Prático de Fechamento Mensal

Aqui está um checklist repetível para fechar seus livros a cada mês usando o Beancount.

```mermaid
flowchart TD
  cap[Capture Transactions] --> rec[Reconcile Accounts]
  rec --> review[Unadjusted Review]
  review --> adj[Post Adjustments]
  adj --> atb[Adjusted Review & Validate]
  atb --> pub[Publish Reports]
  pub --> wrap[Wrap-up & Archive]
  wrap --> cap
```

- [ ] **Captura:** Importe todas as transações de bancos e cartões de crédito. Insira manualmente despesas em dinheiro ou itens fora do fluxo.
- [ ] **Reconciliação:** Adicione asserções `balance` para todas as contas bancárias, cartões de crédito e empréstimos, combinando-as com seus extratos.
- [ ] **Revisão:** Analise o trial balance não ajustado no Fava. Investigue saldos estranhos ou inesperados. Verifique faturas não pagas (`Assets:AccountsReceivable`) ou contas a pagar (`Liabilities:AccountsPayable`).
- [ ] **Ajuste:** Lance entradas para receitas/despesas acumuladas, receitas diferidas e correções necessárias.
- [ ] **Validação:** Rode `bean-check`. Revise o trial balance ajustado final.
- [ ] **Publicação:** Gere o P&L e o Balanço Patrimonial. Envie-os aos interessados ou salve-os para seus registros.
- [ ] **Encerramento:** Opcionalmente, faça um lançamento de fechamento se seu negócio exigir. Arquive uma cópia dos arquivos `.beancount` do período.

---

## Por Que o Beancount Brilha no Ciclo Contábil

- **Transparência e Auditabilidade:** Seu razão é um arquivo de texto. Você pode usar `git` para versionar seu histórico financeiro, revisar mudanças com `diff` e colaborar com seu contador em um formato claro e inequívoco.
- **Controle Total:** Você define seu plano de contas. Não fica preso à estrutura de um fornecedor de software. Seus dados são seus, para sempre, em um formato aberto.
- **Poder Inigualável:** A combinação de consultas estilo SQL (BQL) e uma interface web rica (Fava) oferece poder sem precedentes para fatiar, analisar e entender seus dados financeiros.

### Trechos Prontos para Copiar e Começar

**Plano de Contas Simples:**

```beancount
option "title" "My Personal Ledger"
option "operating_currency" "USD"

;; --- Accounts ---
1970-01-01 open Assets:Bank:Checking
1970-01-01 open Assets:AccountsReceivable
1970-01-01 open Liabilities:CreditCard
1970-01-01 open Liabilities:UnearnedRevenue
1970-01-01 open Equity:Owner:Capital
1970-01-01 open Equity:Retained-Earnings
1970-01-01 open Income:Consulting
1970-01-01 open Expenses:Office:Supplies
1970-01-01 open Expenses:Software
1970-01-01 open Expenses:Depreciation
```

**Consulta BQL Útil:**

```sql
-- Find all customers with an outstanding balance
SELECT payee, sum(position)
WHERE account = 'Assets:AccountsReceivable'
GROUP BY payee
HAVING sum(position) > 0
ORDER BY sum(position) DESC;
```

Ao mapear o atemporal ciclo contábil para as ferramentas modernas baseadas em texto do Beancount, você ganha um sistema robusto, transparente e feito para durar. Boas contabilidades!
