# Importar um CSV bancário para o Beancount com o bea

Um CSV bancário comum não precisa de um importador Python. Mapeie suas colunas com `--csv`, nomeie a conta de origem com `--account`, categorize as linhas com `--rules`, depois pré-visualize e aplique as entradas com `bea import`.

Você precisa de um livro-razão existente. Se estiver começando um novo livro, siga o [início rápido da CLI](https://beancount.io/pt/docs/Basics/bea-cli). Mantenha o extrato bancário original para que possa compará-lo com a pré-visualização.

## 1. Mapeie as colunas do CSV

Salve este exemplo como `statement.csv`, depois execute os comandos abaixo no mesmo diretório:

```csv
Date,Payee,Narration,Amount
2026-08-02,Whole Foods,groceries,-20.00
2026-08-03,Shell,gas,-40.00
2026-08-04,Unknown Shop,mystery,-9.99
```

Os valores usam a convenção de sinal do banco: gastos são negativos e depósitos são positivos. A moeda padrão é a moeda operacional do livro-razão, então este arquivo não precisa de uma coluna de moeda. Coloque uma coluna de descrição bancária em `narration` e mantenha `payee` para o comerciante.

Crie o livro-razão e abra a subconta combustível usada abaixo:

```bash
bea --no-input init books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-08-01 --account Expenses:Transport:Fuel -c USD
```

O modelo já abre `Expenses:Groceries` e as outras contas comuns. Ele não abre `Expenses:Transport:Fuel`, então o segundo comando a abre antes da importação. Opções globais como `--file` vão antes do subcomando.

## 2. Pré-visualize as entradas

Salve estas regras de categorização como `rules.toml`, depois pré-visualize:

```bash
cat > rules.toml <<'EOF'
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"

[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"
EOF
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee,narration=Narration --account Assets:Checking --rules rules.toml
```

As regras correspondem primeiro ao beneficiário, depois à narração, ignorando maiúsculas/minúsculas. A primeira regra que corresponder vence. Linhas para as quais não há regra correspondente são lançadas em `Expenses:Uncategorized` com a flag `!` para revisão posterior. O produto [guia de IMPORTAÇÃO](https://github.com/bex-co/beancount-io/blob/main/cli/docs/IMPORTING.md) documenta a referência completa do mapeamento, incluindo o par `debit` e `credit`, a coluna `category` e a leitura de cabeçalho `--csv auto`.

Nada é escrito no livro-razão ainda. A pré-visualização informa `3 ready, 0 exact duplicates, 0 possible duplicates` e sai com código 0. Sua coluna `RULE` informa o padrão vencedor por linha, ou `unmatched` para a linha `Unknown Shop`. Revise as datas, beneficiários, valores de origem com sinal, contas de destino, correspondências duplicadas e a diferença proposta do arquivo. Corrija uma regra ou categoria incorreta, depois pré-visualize novamente. Abra qualquer conta ausente antes de aplicar a importação: uma regra que nomeia uma conta não aberta no livro-razão falha na validação.

## 3. Aplique as entradas revisadas

```bash
bea --file books/main.bean import statement.csv --apply
bea --file books/main.bean check
bea --file books/main.bean list transaction --flag '!'
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"
```

O mapeamento de colunas é lembrado por razão principal, linha de cabeçalho e conta de origem, então `--apply` é executado novamente sem flags e reporta usando o mapeamento de colunas lembrado. Ele recomputa a pré-visualização contra os arquivos atuais, valida o razão candidato completo antes de escrever e escreve 3 lançamentos. `bea check` não reporta erros. A fila `!` lista a única linha sem correspondência: `Unknown Shop` com `mystery` em `-9.99 USD`. Uma verificação aprovada apenas prova que o razão está equilibrado e validado. Não diz nada sobre se essa linha pertence a `Expenses:Uncategorized`, então recategorize-a deliberadamente no seu razão. A verificação termina em `930.01 USD`: o saldo inicial `1,000 USD` menos `69.99 USD` de gastos.

## 4. Importações repetidas não adicionam nada

```bash
bea --file books/main.bean import statement.csv --apply
```

A pré-visualização reporta `0 ready, 3 exact duplicates`, e a execução escreve 0 lançamentos com saída 0. Cada linha escrita carrega metadados `import-id` com um hash de conteúdo, então o arquivo idêntico corresponde a cada linha. Preserve esses metadados ao editar lançamentos importados. Importar adiciona lançamentos; não atualiza nem exclui uma transação existente. Faça correções deliberadamente no seu razão e execute `bea check` após isso. Entrada em massa JSON com `bea add transactions` não possui detecção de duplicados.

## 5. Resolver possíveis duplicatas

Um download posterior pode repetir uma linha com narração ou IDs bancários diferentes. Data, beneficiário normalizado e valor da fonte assinado ainda a marcam como uma possível correspondência:

| Status da pré-visualização | Significado | O que fazer |
| -------------- | ------- | ---------- |
| `new` | Nenhuma evidência de duplicata encontrada | Verifique os valores e categorias |
| `duplicate` | Um ID estável e detalhes da transação coincidem, ou existe uma diretiva não transacional idêntica | Já pulado |
| `possible_duplicate` | A data, beneficiário normalizado e valor/câmbio da fonte assinado coincidem | Compare a pré-visualização com o lançamento existente |
| `conflict` | Um ID estável coincide com detalhes de transação diferentes | Resolva a discrepância do ID ou dos dados, então pré-visualize novamente |

Um ID bancário diferente não exclui uma duplicata. Bancos podem mudar IDs em downloads posteriores. Duas compras reais também podem compartilhar data, beneficiário e valor, logo uma possível correspondência é evidência e não prova. Bea não realiza suposições com modelo de IA e nunca categoriza para você além de suas regras.

O `--duplicates review` padrão recusa aplicar correspondências não resolvidas. Em uma execução de verificação, um segundo arquivo repetindo a linha `2026-08-02 Whole Foods -20.00 USD` sob uma narração diferente foi exibido como 1 possível duplicata, e `--apply` saiu com 4 sem nada escrito. Depois de revisar todas as correspondências possíveis, escolha uma destas alternativas:

```bash
bea --file books/main.bean import statement.csv --apply --duplicates skip
bea --file books/main.bean import statement.csv --apply --duplicates include
```

Escolha `include` para preservar compras repetidas legítimas. A decisão se aplica a todas as correspondências possíveis nessa invocação. Duplicatas exatas continuam sendo ignoradas. Conflitos de ID ainda bloqueiam a gravação. `--no-input` e `--yes` não ignoram essa revisão. Uma decisão intencional de pular todas as linhas resulta em saída 0 sem adições ao livro razão.

## 6. Use um importador Python para outros formatos

Para formatos que o mapeamento de colunas não pode expressar, como OFX ou QIF ou um CSV com layout incomum, `bea import` chama um importador configurado usando a interface atual do Beangulp: `identify(filepath)`, `account(filepath)` e `extract(filepath, existing)`. O importador é responsável pela análise e categorização específica do banco. Ele deve fornecer valores explícitos nos lançamentos da conta-fonte para que a correspondência de duplicatas use os valores reais do banco. Um importador Python continua sendo o caminho avançado para esses formatos. Para um CSV nativo de banco, experimente `--csv` primeiro.

Para uma primeira execução prática, salve a [configuração CSV categorizada de exemplo](https://github.com/bex-co/beancount-io/blob/main/cli/docs/examples/csv_importers.py) como `importers.py` ao lado do seu livro razão raiz. Ele usa apenas Beancount e a biblioteca padrão do Python, então funciona com a instalação Homebrew. Seu exemplo `bank.csv` usa um valor assinado de conta corrente: uma despesa `-5.25 USD` para refeições e um depósito `1,000 USD` de salário. A configuração de exemplo espera exatamente as colunas documentadas. Execute apenas configurações Python em que confie.

```bash
bea --file books/main.bean import bank.csv --config importers.py
bea --file books/main.bean import bank.csv --config importers.py --importer categorized-checking
bea --file books/main.bean import bank.csv --config importers.py --apply
```

Sua configuração `importers.py` exporta `CONFIG = [importer, ...]`. Se vários importadores reconhecerem o arquivo, selecione um pelo nome. Um nome desconhecido lista os nomes configurados. Um importador conhecido que não reconhece o arquivo reporta isso separadamente.

O 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, por fim, `importers.py` ao lado do raiz. A saída indica o caminho e sua origem.

`--apply` recalcula a pré-visualização em relação aos arquivos atuais. Ele valida o razão candidato completo antes de escrever. Uma falha de validação deixa o razão original inalterado e sai com o código 1. Uma alteração simultânea no razão sai com o código 4; inspecione a alteração e execute uma nova pré-visualização antes de tentar novamente.

## Mantenha as importações repetíveis

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

Uma linha com um ID bancário estável é gravada com metadados `import-id` nomeando seu tipo, como um prefixo `bank:` ou `ofx:`. Uma linha sem esse ID é gravada com um hash de conteúdo `csv:sha256:` sobre sua data, valor, descrição e conta, portanto, reimportar o mesmo arquivo pula todas as linhas. Entradas gravadas antes desta convenção ainda podem conter metadados `bea_import_id`, e estes ainda correspondem na reimportação. 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 pré-visualização e gravação. Aspas e barras invertidas mantêm seu conteúdo. O texto do comerciante importado permanece legível em uma única linha no razão.

## Escrever em um arquivo incluído

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

```bash
bea --file books/main.bean import statement.csv --into 2026.bean
bea --file books/main.bean import statement.csv --into 2026.bean --apply
```

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

## Use importações em um script

```bash
bea --file books/main.bean --json --no-input import statement.csv --apply --duplicates skip
```

Escolha `skip` somente se essa for sua política intencional para possíveis correspondências. JSON retorna a pré-visualização e a contagem de gravação dentro de `data`. Aplicações recusadas colocam a pré-visualização em `error.result` no stderr, com `written: 0`. Sempre verifique o status de saída. Veja a [referência de JSON e códigos de saída](https://beancount.io/pt/docs/bea-cli-reference) antes de agendar importações não supervisionadas.

## Solucione problemas de um importador

As configurações do importador rodam na engine gerenciada. Se uma configuração importa Beangulp, instale a biblioteca `libmagic` do sistema e habilite Beangulp lá uma vez:

```bash
bea engine enable beangulp
bea --file books/main.bean import bank.ofx --config importers.py
bea --debug --file books/main.bean import bank.csv --config importers.py
```

`bea engine status` reporta os recursos habilitados. Instalar um importador bancário junto à interface `bea` não o torna disponível dentro da engine. Uma configuração que importa pacotes adicionais precisa dessas dependências na engine; habilitar Beangulp sozinho não as instala. Use o mapeador CSV ou os conversores abaixo quando essas dependências do importador estiverem indisponíveis.

Para uma exceção de importador, coloque `--debug` antes do comando para mostrar seu rastreamento. A saída do importador é capturada em `importer_output` para que não corrompa o JSON. No modo de depuração JSON, o rastreamento é `error.traceback`.

Para uma conversão única sem um importador Python, experimente o [conversor CSV](/tools/csv-to-beancount) ou o [conversor OFX e QIF](/tools/ofx-to-beancount). Revise as entradas geradas antes de adicioná-las aos seus livros.
