Use IA para sugerir contas e explicar transações, depois verifique os lançamentos contra seus documentos originais antes de salvá-los. Este guia percorre um extrato fictício por categorização, revisão, validação e uma consulta que você pode verificar.
Escolha um fluxo de trabalho hospedado ou local abaixo. O exemplo prático usa um arquivo de amostra local para que você possa reproduzir cada etapa antes de conectar a IA aos seus próprios livros.
Escolha seu fluxo de trabalho
| Sua configuração | Comece aqui | Como as alterações chegam ao seu razão |
|---|---|---|
| Você usa o Beancount.io | Use Importação Inteligente para arquivos de extrato, ou Assistente de IA para perguntas e edições propostas. | Revise as linhas antes de enviar a importação. Para edições do Assistente, revise o diff proposto e escolha Aprovar ou Negar. |
| Você usa um cliente de IA externo | Siga o guia de configuração do Beancount MCP para conectar seu cliente a um razão hospedado. | Uma execução de teste (dry run) pré-visualiza uma operação de edição. Uma chamada de escrita separada a confirma. Os avisos de aprovação dependem das configurações do seu cliente. |
| Você mantém arquivos locais | Use o conversor de CSV para Beancount ou um importador e, em seguida, peça a uma ferramenta de IA que sugira categorias. | Você revisa os lançamentos propostos, valida o arquivo e salva as alterações aceitas. |
O Assistente hospedado e o MCP são integrações do Beancount.io. Instalar o motor de contabilidade Beancount de código aberto não adiciona esses serviços a um razão local.
Antes de começar
Tenha seu extrato, a conta a que ele pertence e uma lista de contas de destino permitidas. Mantenha o extrato original disponível para comparar com o resultado.
Para o passo a passo local, instale o Beancount usando o guia de introdução. Você também precisará do Beanquery para executar a consulta final a partir do terminal. O exemplo assume USD durante todo o processo e nenhuma transação existente no arquivo de amostra.
Para dados reais, decida quais informações sua ferramenta de IA pode receber. Remova identificadores desnecessários antes de compartilhar um extrato. Um razão local ainda pode enviar dados para um modelo em nuvem por meio de um editor ou cliente MCP. Verifique as políticas de dados do cliente e do provedor do modelo; manter um arquivo no seu computador não garante, por si só, que seu conteúdo permaneça local.
1. Comece com as transações de origem
Nossa conta corrente fictícia começa agosto com 1.000,00 USD. Seu extrato contém três saques e fecha em 805,10 USD após essas retiradas:
date,payee,description,amount
2026-08-03,Office Depot,Printer paper,-45.00
2026-08-04,Cloud Hosting Inc,Monthly hosting,-120.00
2026-08-05,Amazon,Online purchase,-29.90Valores negativos aqui significam dinheiro saindo da conta corrente. Confirme a convenção de sinais do seu banco antes de importar; outros exportadores e importadores podem usar uma convenção diferente.
No conversor de CSV, mapeie estas quatro colunas e defina a conta de origem como Assets:Bank:Checking com moeda USD. Deixe Inverter todos os sinais desligado para esta amostra. Verifique se os lançamentos de origem são negativos. Uma conta de destino provisória é apenas um espaço reservado até você revisar as categorias.
Se você começar com uma imagem de recibo ou PDF, compare as datas, valores, moeda e contagem de transações extraídas com o documento original antes de categorizar qualquer coisa. Mantenha os valores de origem intactos enquanto decide as contas.
2. Peça categorias com limites explícitos
Use um prompt que nomeie as contas permitidas e deixe espaço para incerteza:
Sugira uma conta de destino para cada linha deste extrato de amostra. A conta de origem é Assets:Bank:Checking. Use apenas Expenses:Office:Supplies ou Expenses:Business:Hosting. Retorne a data, o beneficiário, o valor, a conta sugerida e um motivo curto originais. Se a descrição for insuficiente, retorne NEEDS_REVIEW e explique qual informação está faltando. Não invente contas, altere valores ou escreva no razão.
Forneça as três linhas do CSV com o prompt. Um resultado útil seria assim; a redação do modelo e as sugestões podem variar:
| Data | Beneficiário | Valor (USD) | Conta sugerida | Motivo da revisão |
|---|---|---|---|---|
| 2026-08-03 | Office Depot | -45.00 | Expenses:Office:Supplies | A descrição identifica papel para impressora. |
| 2026-08-04 | Cloud Hosting Inc | -120.00 | Expenses:Business:Hosting | A descrição identifica hospedagem. |
| 2026-08-05 | Amazon | -29.90 | NEEDS_REVIEW | O nome do comerciante não identifica o que foi comprado. |
O prompt expressa sua intenção. Ele não impõe permissões sobre uma ferramenta que pode escrever em arquivos. Configure os controles de aprovação do seu cliente antes de dar a ele acesso a um razão real.
3. Resolva a incerteza e revise os lançamentos
Verifique o recibo da compra na Amazon. Para este exemplo, ele identifica um cabo USB-C para o escritório, e o revisor atribui Expenses:Office:Supplies. Sem essa evidência, deixe a linha pendente em vez de aceitar uma categoria adivinhada.
Crie um novo arquivo chamado review.beancount com o seguinte exemplo completo. Ele inclui as declarações de contas e o saldo inicial que o CSV não contém. Se você usou o conversor, compare as transações dele com estes lançamentos revisados; não adicione ambas as cópias ao mesmo razão.
option "title" "AI bookkeeping review example"
option "operating_currency" "USD"
2026-08-01 open Assets:Bank:Checking USD
2026-08-01 open Equity:Opening-Balances USD
2026-08-01 open Expenses:Office:Supplies USD
2026-08-01 open Expenses:Business:Hosting USD
2026-08-01 * "Opening balance"
Assets:Bank:Checking 1000.00 USD
Equity:Opening-Balances -1000.00 USD
2026-08-03 * "Office Depot" "Printer paper"
Assets:Bank:Checking -45.00 USD
Expenses:Office:Supplies 45.00 USD
2026-08-04 * "Cloud Hosting Inc" "Monthly hosting"
Assets:Bank:Checking -120.00 USD
Expenses:Business:Hosting 120.00 USD
2026-08-05 * "Amazon" "Online purchase; receipt: office USB-C cable"
Assets:Bank:Checking -29.90 USD
Expenses:Office:Supplies 29.90 USD
2026-08-06 balance Assets:Bank:Checking 805.10 USDA transação de saldo inicial pertence a este razão de prática vazio. Em um razão existente, use seu saldo e declarações de contas estabelecidos em vez de adicionar outro saldo inicial.
Antes de aceitar uma alteração proposta, compare cada transação com sua linha de origem. Confirme os sinais, moeda, contas e o recibo de suporte. Um nome de comerciante familiar, por si só, não estabelece a finalidade de uma compra.
4. Valide e reconcilie
Execute o validador do Beancount na amostra local:
bea --file review.beancount checkO exemplo completo deve passar sem erros. Sua verificação de saldo confere o valor em conta corrente no início de 6 de agosto, após as três retiradas anteriores.
Confirme o resultado contra o extrato:
- As três transações do extrato aparecem uma vez cada, além do saldo inicial.
- Os saques totalizam 194,90 USD.
- A conta corrente contém 805,10 USD: o saldo inicial de 1.000,00 USD menos esses saques.
- Os suprimentos de escritório totalizam 74,90 USD e a hospedagem totaliza 120,00 USD.
Se você deixar a transação da Amazon pendente, a conta corrente permanece em 835,00 USD e a verificação falha por 29,90 USD. Investigue essa diferença; não adicione um ajuste não explicado apenas para fazer a verificação passar.
O bea check captura erros de sintaxe, contas, equilíbrio e verificação de saldo. Ele não pode estabelecer que um recibo é genuíno, que você selecionou a categoria de despesa correta ou que cada linha do extrato está presente. Uma transação lançada na conta de despesa errada ainda pode equilibrar perfeitamente.
Quando algo não corresponde
| Sintoma | Próxima verificação |
|---|---|
| O saldo difere do extrato | Compare o saldo inicial, a contagem de transações, os sinais, as datas e os valores com a origem. |
| Dois lançamentos parecem iguais | Compare os identificadores de transação de origem e os recibos. O mesmo comerciante e valor podem representar duas compras legítimas. |
| O modelo inventa uma conta | Escolha uma conta existente ou crie deliberadamente uma nova após revisar seu plano de contas. |
| A extração omite uma linha ou altera uma casa decimal | Corrija os dados extraídos contra o documento original antes de categorizá-los. |
| O validador passa, mas um relatório parece errado | Inspecione as escolhas de contas, o período do relatório e os lançamentos individuais. |
Peça à IA para explicar discrepâncias e apontar as linhas afetadas. Confirme a evidência antes de excluir uma duplicata suspeita ou alterar um valor.
5. Salve o resultado revisado e consulte-o
Ao repetir este fluxo de trabalho com seu próprio extrato, mescle apenas suas transações revisadas em seu razão real e, em seguida, valide o arquivo combinado. Mantenha os lançamentos fictícios no arquivo de amostra. Se você usa Git, inspecione o diff e faça o commit pelo seu fluxo de trabalho usual. Mantenha o extrato de origem disponível para reconciliação posterior. O guia de fluxos de trabalho com script cobre automação local repetível.
Você pode verificar os totais da amostra com a Linguagem de Consulta do Beancount. Com o Beanquery instalado, execute:
bea --file review.beancount query "SELECT account, sum(position) WHERE account ~ '^Expenses:' AND date >= 2026-08-01 AND date < 2026-09-01 GROUP BY account"Os dois totais de despesas devem ser 74,90 USD para suprimentos de escritório e 120,00 USD para hospedagem. Inspecione o intervalo de datas e o filtro de conta da consulta, bem como sua saída.
Com um cliente de IA conectado a um razão contendo a amostra, você pode perguntar:
Consulte o razão de amostra para despesas de agosto de 2026 agrupadas por conta. Mostre a consulta e seus resultados. Não altere nenhum arquivo.
Compare a resposta com os mesmos totais. Uma resposta fluente é útil apenas quando seus números podem ser rastreados até o razão.
Aplique o processo de revisão no Beancount.io
Para arquivos de extrato, abra Importar → Importação Inteligente na barra lateral do seu razão. Revise as linhas extraídas, escolha Conta de Origem e Moeda, e use Preenchimento com IA para sugestões de conta de destino. Corrija as categorias antes de enviar Importar, cujo botão inclui a contagem de transações. Verifique o diário e os saldos resultantes em um razão de amostra antes de processar um extrato real. Confirme que os saques reduzem a conta de origem; o CSV acima está preparado para o conversor local, e os importadores podem interpretar os sinais de forma diferente.
Para o Assistente hospedado, abra Perguntar ao Beancount.io dentro do seu razão. Comece com uma pergunta sobre os lançamentos existentes. Quando ele propor uma edição de arquivo, revise o diff antes de aprová-lo. Importações aceitas e edições do Assistente são registradas no Git para que você possa inspecionar ou reverter as alterações.
Para MCP, siga as instruções de configuração específicas do cliente vinculadas acima e autorize o razão pretendido. Peça editLedgerFiles com dry_run: true antes de permitir uma edição. Inspecione o conteúdo proposto e o resumo da operação e, em seguida, permita uma chamada de escrita separada somente após a revisão. A pré-visualização de execução de teste não estabelece a correção contábil nem garante que seu cliente pedirá permissão antes de uma escrita posterior.
Mantenha o processo de revisão enquanto automatiza
Comece com um lote pequeno e registre quais sugestões você altera. Transforme mapeamentos repetidos e confirmados em regras de importação explícitas ou forneça exemplos revisados como contexto. Não presuma que um modelo aprende permanentemente com uma correção em uma conversa.
Mantenha as verificações de extração, revisão de categorias e reconciliação de extratos separadas. Cada uma captura um tipo diferente de erro. Para importações recorrentes, verifique também se importar a mesma origem duas vezes não duplica transações silenciosamente.
A pesquisa apoia essa distinção entre sintaxe válida e contabilidade correta. O estudo de janeiro de 2025 de Figueroa Rosero e colegas avaliou pequenos modelos de peso aberto em cenários de índices financeiros e geração de transações usando prompts estruturados. Seus resultados descrevem esses modelos e tarefas, em vez de uma taxa de precisão para os assistentes de hoje ou seu fluxo de trabalho de importação. Avalie seu próprio fluxo de trabalho usando transações de origem verificadas e as correções que elas exigem.
Ferramentas para um fluxo de trabalho local repetível
Escolha uma ferramenta para a parte do processo que você precisa repetir:
- Beangulp fornece uma estrutura de importador. Ele substitui a estrutura mais antiga
beancount.ingestno Beancount 3. - smart_importer é um pacote instalado separadamente que adiciona sugestões de aprendizado de máquina aos importadores. Não é um recurso de LLM integrado.
- Beanborg documenta categorização baseada em regras, sugestões de aprendizado de máquina e previsões opcionais do ChatGPT. Verifique sua configuração atual e compatibilidade antes de adotá-lo.
Para um contexto mais amplo, consulte o guia de automação de escrituração e o guia de fluxo de trabalho contábil mensal.
Explore um exemplo maior
O razão público abaixo é separado do exercício de três transações. Use-o para explorar como contas, transações e relatórios se encaixam antes de conectar a IA aos seus próprios livros.