# Declare Papéis de Fluxo de Caixa no Seu Livro-razão: Uma Linha de Metadados Substitui a Adivinhação

Toda demonstração de fluxo de caixa repousa sobre uma decisão silenciosa tomada uma vez por conta: esta conta faz parte do caixa que você está explicando, ou é uma atividade operacional, de investimento ou de financiamento? Acertar essa decisão e a demonstração diz para onde seu dinheiro realmente foi. Errar e a demonstração é confiantemente enganosa.

Até agora, o relatório de fluxo de caixa do Beancount.io tomava essa decisão por você com heurísticas — o tipo raiz da conta, mais uma suposição baseada no nome sobre quais ativos contam como caixa. Para a maioria dos livros-razão, a suposição estava certa na maioria das vezes, e silenciosamente errada no resto do tempo. Uma conta de corretagem nomeada da maneira errada caía na seção errada. Um fundo do mercado monetário que é caixa em todos os sentidos práticos ficava em Atividades de Investimento porque seu nome não dizia isso.

A partir de hoje, você pode tornar a classificação explícita. Uma linha de metadados padrão do beancount na diretiva `open` da conta:

```beancount
2000-01-01 open Assets:US:Brokerage
  cash-flow-role: "investing"

2000-01-01 open Assets:US:Marcus:Savings
  cash-flow-role: "cash"
```

Uma chave, quatro valores — `cash`, `operating`, `investing`, `financing` — e essa é toda a configuração. Não há página de configurações, nenhum arquivo JSON, nenhum diálogo de opções por relatório. Na próxima vez que o relatório de fluxo de caixa carregar, os fluxos da conta de corretagem aparecem em Atividades de Investimento, a conta poupança se junta ao monte de caixa cuja mudança a demonstração explica, e todas as outras contas continuam funcionando exatamente como antes.

![O relatório de fluxo de caixa do Beancount.io para o livro-razão de exemplo: um gráfico mensal de fluxo de caixa líquido acima de tabelas detalhadas de atividades operacionais e de investimento.](/img/blog/declare-cash-flow-roles-in-your-ledger/cash-flow-report.webp)

## O que cada papel significa

Uma demonstração de fluxo de caixa classifica cada conta em uma de duas funções, e `cash-flow-role` responde a ambas com uma única palavra:

- **`"cash"`** — a conta pertence ao monte de caixa e equivalentes. Contas de caixa nunca aparecem como itens de linha; a demonstração explica a *mudança* no saldo combinado delas, e transferências entre duas contas de caixa se cancelam, da maneira que mover dinheiro da conta corrente para a poupança deveria.
- **`"operating"` / `"investing"` / `"financing"`** — a conta não é caixa, e sua mudança no período aparece como uma linha sob essa seção de atividade.

Por padrão, o relatório trata contas de ativos cujos nomes contêm `Cash`, `Checking`, `Savings` ou `Bank` como equivalentes de caixa. Declarar um papel substitui isso em ambas as direções. `cash-flow-role: "cash"` puxa uma conta que a regra de nome não pega — um fundo do mercado monetário, uma carteira de stablecoin. E `cash-flow-role: "investing"` em `Assets:US:Bank:CD` faz duas coisas com uma linha: exclui o CD do caixa *e* o arquiva em investimentos, mesmo que seu nome tivesse correspondido à regra de caixa.

Usamos deliberadamente uma chave em vez de duas. "Esta conta é caixa?" e "a qual seção de atividade ela pertence?" nunca foram perguntas independentes — uma conta é parte do monte de caixa ou pertence a exatamente uma seção de atividade. Duas chaves teriam permitido estados sem sentido, como uma conta de caixa com um papel de atividade. Uma chave torna os estados ilegais irrepresentáveis, e toda a especificação cabe em um tweet.

![A visão Por Atividade do relatório de fluxo de caixa, empilhando fluxos de caixa operacionais, de investimento e de financiamento por mês.](/img/blog/declare-cash-flow-roles-in-your-ledger/by-activity.webp)

A classificação que você declara é a classificação que toda visão usa. O gráfico Por Atividade empilha os fluxos operacionais, de investimento e de financiamento de cada mês; mova o papel de uma conta, e seus fluxos se movem para a camada certa do gráfico, a seção certa da demonstração e a linha certa da exportação, tudo de uma vez.

## Declarado vence inferido — e o relatório mostra seu trabalho

A classificação agora resolve em uma ordem estrita: seus metadados primeiro, a heurística embutida em segundo. E o relatório é honesto sobre o que fez. A demonstração termina com um painel "Caixa e equivalentes de caixa neste relatório" listando exatamente quais contas tratou como caixa ao construir os números, e então as reconcilia: caixa no início do período, caixa no final do período e a mudança líquida que as seções de atividade explicam.

![O fim da demonstração de fluxo de caixa: a reconciliação da mudança líquida em caixa e equivalentes, e o painel listando as contas tratadas como caixa ao construir o relatório.](/img/blog/declare-cash-flow-roles-in-your-ledger/cash-equivalents.webp)

O relatório também distingue classificações que você declarou das que inferiu, e a distinção vai para as exportações CSV e Markdown: uma demonstração construída inteiramente de papéis declarados não carrega mais a linha de divulgação "classificação é inferida", porque nesse ponto a classificação não é uma inferência — é parte dos seus livros.

Erros de digitação são tratados da maneira que uma ferramenta de texto simples deveria tratá-los. `cash-flow-role: "invsting"` não é silenciosamente aceito e não é silenciosamente ignorado: a conta cai para a heurística padrão, e o painel de status sinaliza — "valor cash-flow-role desconhecido, usando padrão" — para que o erro seja visível onde você olha, não enterrado em um log.

## Se você não mudar nada, nada muda

Contas não anotadas usam os mesmos padrões publicados de antes: Income e Expenses mapeiam para operacional, Assets não-caixa para investimento, Liabilities e Equity para financiamento, e equivalentes de caixa correspondidos por nome formam o monte de caixa. Um livro-razão existente renderiza identicamente antes e depois deste lançamento. A maioria dos usuários anotará um punhado de contas — aquelas onde o padrão está errado — e nunca pensará no resto.

A portabilidade também não é tocada. Metadados em diretivas `open` são sintaxe central do beancount, analisados por toda ferramenta v2/v3 e ignorados por qualquer coisa que não procure por esta chave específica. `bean-check` passa, Fava dá de ombros, e seu livro-razão permanece totalmente utilizável fora do Beancount.io.

## Toda visão do seu caixa concorda com todas as outras

Um resolvedor compartilhado produz o papel final para cada conta, e todo consumidor lê dele:

- O **relatório de fluxo de caixa** constrói suas seções de atividade e seu resultado final — mudança líquida em caixa e equivalentes — a partir dos papéis resolvidos.
- **Exportações CSV, Markdown e impressão** carregam os mesmos números, com a divulgação de classificação inferida apenas onde uma heurística foi realmente usada.
- O **diagrama Sankey da visão geral** lê as mesmas declarações, então uma conta que você marcou como caixa para de aparecer como um nó de fluxo, e seus papéis de atividade declarados são honrados para contas não-Income.
- O **painel de status da conta** para de listar uma conta declarada como um "ativo não classificado".

![O diagrama Sankey da visão geral, desenhando o fluxo de dinheiro de renda através de caixa para categorias de despesas, investimentos e poupança — construído sobre as mesmas classificações de contas que o relatório de fluxo de caixa.](/img/blog/declare-cash-flow-roles-in-your-ledger/overview-sankey.webp)

Não há como a demonstração e o diagrama discordarem sobre o que seu caixa é, porque há apenas uma resposta sobre a qual discordar.

## Por que o livro-razão, e não uma página de configurações

Esta é a parte do lançamento sobre a qual nos sentimos mais fortes. Consideramos uma UI de configurações e a rejeitamos, por três razões:

1. **O livro-razão é a fonte da verdade.** Uma classificação que vive em qualquer outro lugar pode discordar dos livros que descreve. Uma classificação que vive na diretiva `open` viaja com a conta — através de renomeações, através de movimentos de repositório, através de todo cliente que lê o arquivo.
2. **Texto simples é diffável, greppável e revisável.** Se você mantém seu livro-razão em git — e se você usa Beancount.io, você mantém — a regra de classificação agora é algo que você pode `grep`, `diff` e `blame`, e algo que um revisor pode ver em um pull request. Uma página de configurações não é nenhuma dessas coisas.
3. **Funciona offline e em qualquer lugar.** Qualquer editor pode declarar um papel. Qualquer cliente futuro que leia o livro-razão obtém a classificação de graça, com zero configurações por cliente para sincronizar.

Pela mesma razão, classificações são deliberadamente não efetivas por data. Os metadados descrevem a natureza da conta, que raramente muda; quando muda, você edita a diretiva `open`, e seu histórico git registra o que mudou e quando. Esse histórico *é* a trilha de auditoria.

## Experimente no seu livro-razão

O recurso está sendo lançado para todos os livros-razão agora. Declarar um papel requer apenas um editor de texto:

1. Abra o arquivo onde a diretiva `open` da conta vive.
2. Adicione `cash-flow-role: "cash"` (ou `"operating"`, `"investing"`, `"financing"`) como uma linha de metadados indentada sob ela.
3. Recarregue o relatório de fluxo de caixa. Sua declaração vence a heurística imediatamente.

Comece com as contas onde a suposição padrão está errada — o CD que não é realmente caixa, o fundo do mercado monetário que realmente é, a conta de corretagem que você quer limpa sob Atividades de Investimento. Deixe o resto em paz. A especificação completa — valores aceitos, precedência, classificações padrão e como valores inválidos são tratados — vive na [referência de Papéis de Fluxo de Caixa](/docs/cash-flow-roles).

Seus livros já sabiam quais contas são investimentos e quais são gastos diários. Agora a demonstração de fluxo de caixa também sabe.
