Importar exportações bancárias com a CLI

Use bea import para visualizar uma exportação bancária, revisar duplicatas e anexar entradas validadas ao seu livro-razão local.

Você precisa de um livro-razão existente e de um importador Python para o formato exato de exportação do seu banco. Se você está começando uma nova escrituração, siga o início rápido da CLI. Mantenha a exportação bancária original para poder compará-la com a visualização.

1. Escolha um importador​

Um importador lê o arquivo do banco e fornece as contas das transações. O Bea não adivinha o formato nem categoriza compras com um modelo de IA.

Sua configuração importers.py exporta CONFIG = [importer, ...]. Os importadores usam a interface atual do Beangulp: identify(filepath), account(filepath) e extract(filepath, existing). Lançamentos de conta de origem precisam de valores explícitos para correspondência de duplicatas.

Para um primeiro teste prático, salve a configuração de CSV categorizada de exemplo como importers.py ao lado do seu livro-razão raiz. Ela usa apenas Beancount e a biblioteca padrão do Python, portanto funciona com a instalação Homebrew.

Salve esta amostra como bank.csv no mesmo diretório:

Date,Payee,Narration,Amount,Currency,Category,BankID
2026-08-02,Cafe,Coffee,-5.25,USD,Expenses:Dining,bank-001
2026-08-03,Employer,Salary,1000,USD,Income:Salary,bank-002

A amostra usa um valor assinado de conta corrente: gastos são negativos e um depósito é positivo. Category fornece a outra conta. Ambas as categorias estão no modelo USD criado por bea init.

Use um importador escrito para o seu banco ao importar seu CSV nativo, OFX ou QIF. A configuração de amostra espera exatamente as colunas acima. Execute apenas configurações Python nas quais você confia.

2. Visualize as entradas​

Execute isto a partir do diretório que contém main.bean:

bea import bank.csv --config importers.py

Nada é gravado no livro-razão ainda. Revise as datas, beneficiários, valores de origem assinados, contas de destino, correspondências de duplicatas e o diff de arquivo proposto na visualização.

Para a amostra, a visualização deve conter uma despesa de alimentação de 5,25 USD e um depósito de salário de 1.000 USD. Corrija uma categoria incorreta no importador ou nos dados de origem e visualize novamente. Abra quaisquer contas ausentes antes de aplicar a importação.

Se vários importadores reconhecerem o arquivo, selecione um pelo nome:

bea import bank.csv --config importers.py --importer categorized-checking

Um nome desconhecido lista os nomes configurados. Um importador conhecido que não reconhece o arquivo relata isso separadamente.

3. Aplique as entradas revisadas​

bea import bank.csv --apply
bea check
bea list transaction --limit 10

A CLI lembra o caminho da configuração para este livro-razão raiz. Execuções futuras escolhem o --config explícito, depois o caminho lembrado e então importers.py ao lado do raiz. A saída nomeia o caminho e de onde ele veio.

--apply recalcula a visualização contra os arquivos atuais. Ele valida o livro-razão candidato completo antes de gravar. Uma falha de validação deixa o livro-razão original inalterado e sai com código 1. Uma alteração concorrente no livro-razão sai com código 4; inspecione a alteração e execute uma nova visualização antes de tentar novamente.

4. Resolva possíveis duplicatas​

Repetir a mesma importação de amostra pula suas entradas existentes. Uma exportação sobreposta também pode conter linhas que precisam de uma decisão:

Um ID bancário diferente não descarta uma duplicata. Os bancos podem alterar IDs em downloads posteriores. Duas compras reais também podem compartilhar data, beneficiário e valor.

Após revisar cada correspondência possível, escolha uma destas alternativas:

bea import bank.csv --apply --duplicates skip

bea import bank.csv --apply --duplicates include

A decisão se aplica a todas as correspondências possíveis nessa invocação. Duplicatas exatas permanecem puladas. Conflitos de ID ainda bloqueiam a gravação.

O padrão --duplicates review recusa aplicar correspondências não resolvidas. Ele sai com código 4 e nomeia as linhas de visualização afetadas. --no-input e --yes não ignoram essa revisão. Uma decisão intencional de pular todas as linhas sai com código 0 sem adições ao livro-razão.

Mantenha importações repetíveis​

Por padrão, a correspondência de duplicatas verifica metadados bank_id, fitid, transaction_id e imported_id dentro da conta de origem do importador. Use opções repetidas --id-key KEY para substituir esse conjunto.

A CLI também escreve metadados bea_import_id para identificar a linha na exportação original. Retenha-os ao editar entradas importadas. Correspondências possíveis são verificadas contra transações existentes e linhas aceitas no mesmo lote.

Beneficiários, narrações e metadados de string substituem quebras de linha por espaços antes da visualização e gravação. Aspas e barras invertidas mantêm seu conteúdo. O texto do comerciante importado permanece, portanto, legível em uma única linha do livro-razão.

Importar adiciona entradas; não atualiza ou exclui uma transação existente. Faça correções deliberadamente em seu livro-razão e execute bea check depois. A entrada JSON em massa com bea add transactions não tem detecção de duplicatas.

Gravar em um arquivo incluído​

Mantenha --file apontado para o raiz e selecione o destino com --into:

bea --file ~/my-books/main.bean import bank.csv --into 2026.bean
bea --file ~/my-books/main.bean import bank.csv --into 2026.bean --apply

2026.bean já deve existir e ser incluído pelo raiz. Seu caminho é relativo ao diretório raiz. O caminho da exportação permanece relativo ao seu diretório de trabalho. A visualização identifica o arquivo que será alterado.

Usar importações em um script​

bea --json --no-input import bank.csv --apply --duplicates skip

Escolha skip somente quando essa for sua política pretendida para correspondências possíveis. O JSON retorna a visualização e a contagem de gravações dentro de data. Aplicações recusadas colocam a visualização em error.result no stderr, com written: 0. Sempre verifique o status de saída. Consulte a referência JSON e códigos de saída antes de agendar importações não assistidas.

Solucionar problemas de um importador​

Se a configuração importa pacotes de terceiros, esses pacotes devem estar no ambiente Python que executa bea. Por exemplo:

uv run --with beancount-io --with beangulp \
  bea --file ~/my-books/main.bean import bank.ofx --config importers.py

Adicione --with YOUR_IMPORTER_PACKAGE para um importador bancário instalado separadamente. Isso usa um ambiente separado do Homebrew.

Para uma exceção de importador, coloque --debug antes do comando para mostrar seu traceback:

bea --debug import bank.csv --config importers.py

A saída do importador é capturada em importer_output para não corromper o JSON. No modo de depuração JSON, o traceback está em error.traceback.

Para uma conversão única sem um importador Python, tente o conversor de CSV ou o conversor de OFX e QIF. Revise as entradas geradas antes de adicioná-las aos seus livros.