Como integrar o extrato bancário com o ERP
Existem três formatos para levar o extrato bancário ao ERP: OFX, que todo banco brasileiro exporta e serve para conciliação; CNAB retorno, que traz a baixa de títulos e cobrança; e API de Open Finance, que elimina o download manual. OFX resolve a maioria dos casos, desde que a rotina use o identificador da transação para não duplicar lançamento.
OFX não é XML, e é aí que a maioria trava
A versão do OFX que os bancos brasileiros exportam na prática é a 1.x, que usa uma sintaxe parecida com SGML: várias tags não têm fechamento. Jogar esse arquivo num parser de XML gera erro de documento malformado, e muita gente conclui que o arquivo do banco veio corrompido.
Use uma biblioteca de OFX de verdade, ou normalize o arquivo antes de tratar. A versão 2.x do OFX é XML válido, mas ainda é minoria no que os bancos daqui entregam.
O segundo detalhe é a codificação de caracteres. Boa parte dos arquivos vem em ISO-8859-1 ou cp1252, não em UTF-8. Ler como UTF-8 sem declarar a codificação estraga acento em histórico de lançamento e, dependendo da linguagem, derruba a leitura.
O identificador da transação é o que impede duplicidade
Todo lançamento no OFX carrega um identificador único atribuído pelo banco, o FITID. Ele é a chave para tornar a importação idempotente: antes de gravar, verifique se aquele identificador já existe no ERP e ignore se existir.
Sem isso, reimportar o mesmo arquivo duplica lançamento, e reimportar é o caso comum, não a exceção. As pessoas baixam o extrato de novo quando o período veio incompleto, quando o processo falhou no meio, ou simplesmente quando não lembram se já importaram.
Cuidado com um detalhe: alguns bancos reemitem o identificador quando a transação muda de status, por exemplo de lançamento pendente para efetivado. Vale guardar também data e valor para detectar esse caso em vez de tratar como transação nova.
OFX, CNAB ou API: cada um resolve uma coisa
Confundir os três é a causa mais comum de projeto que entrega a coisa errada. OFX é extrato: o que entrou e saiu da conta. CNAB retorno é cobrança: quais boletos foram pagos, com qual valor e qual tarifa. API de Open Finance é o mesmo extrato, sem o download manual.
Se o objetivo é conciliar o caixa, você quer OFX ou API. Se o objetivo é baixar título a receber automaticamente, você quer CNAB retorno. Muitas empresas precisam dos dois, e são duas rotinas diferentes.
A regra de casamento é onde o projeto vive ou morre
Casar por valor exato e data exata funciona no ambiente de teste e falha na produção. Pagamento cai um dia útil depois, tarifa bancária muda o valor em centavos, e um lote de recebimentos vira um crédito só no extrato.
Uma regra que sobrevive ao mundo real trabalha em camadas: primeiro tenta o casamento exato por identificador ou documento, depois por valor com janela de data, depois por valor aproximado dentro de uma tolerância. O que não casar em nenhuma camada vai para revisão humana.
A meta não é casar 100% de forma automática. É reduzir a fila de revisão manual a um volume que uma pessoa resolve em minutos, com confiança de que o que foi casado automaticamente está certo. Foi esse desenho em camadas que aplicamos no case de automação de conciliação financeira, uma ferramenta desktop offline que concilia extratos em PDF em segundos.
Passo a passo da importação por OFX
- Colete um extrato real de cada banco. Baixe um arquivo de cada banco que a empresa usa e inspecione a versão do OFX e a codificação de caracteres. Bancos diferentes entregam variações diferentes do mesmo formato.
- Leia com biblioteca de OFX, não com parser de XML. Use uma biblioteca que entenda a sintaxe SGML do OFX 1.x, ou normalize o arquivo antes. Declare explicitamente a codificação na leitura para não perder acento.
- Extraia identificador, data, valor e histórico. De cada lançamento, guarde o identificador da transação, a data, o valor com sinal, o tipo e o texto do histórico. Persista o identificador com índice único.
- Torne a importação idempotente. Antes de gravar, verifique se o identificador já existe. Se existir, pule. Isso é o que permite reimportar o mesmo arquivo sem duplicar lançamento no ERP.
- Aplique a regra de casamento em camadas. Tente casar por documento, depois por valor com janela de data, depois por valor com tolerância. Registre por qual camada cada casamento passou, para auditar a qualidade depois.
- Separe a fila de exceções. Tudo que não casou vai para uma tela de revisão com o lançamento do banco de um lado e os candidatos do ERP do outro. A decisão do usuário deve alimentar a regra ao longo do tempo.
- Valide contra um fechamento conhecido. Rode a rotina sobre um mês já fechado manualmente e compare o resultado. Divergência aqui é barata de corrigir. Divergência descoberta no fechamento seguinte não é.
OFX, CNAB e Open Finance lado a lado
Os três levam dado do banco ao ERP, mas resolvem perguntas diferentes. A coluna de limite é a que mais importa na hora de escolher.
| Abordagem | Custo | Prazo | Onde para de servir |
|---|---|---|---|
| OFX baixado manualmente | Baixo: só o desenvolvimento da leitura | 1 a 2 semanas | Alguém precisa baixar o arquivo todo dia. Formato varia entre bancos e o arquivo pode vir incompleto sem avisar. |
| CNAB retorno | Baixo, porém com layout por banco | 1 a 3 semanas | Cobre cobrança, não o extrato completo. Cada banco tem sua variação do layout, então suportar cinco bancos é quase cinco trabalhos. |
| API de Open Finance ou agregador | Assinatura mensal por conta conectada | 1 a 2 semanas | Elimina o download manual, mas cria dependência e custo recorrente. Exige consentimento que precisa ser renovado. |
| Digitação manual no ERP | Zero em software, caro em hora | Imediato | Erro de digitação e atraso de fechamento. Só sustentável em volume muito baixo, e é o cenário que a automação costuma substituir. |
Perguntas frequentes
Referências
Quer isso rodando na sua operação?
O primeiro passo é um Diagnóstico: mapeamos o processo na sua operação e devolvemos escopo, prazo e preço antes de qualquer proposta.
Conhecer o Diagnóstico