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.
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?
Escopo, prazo e preço travados antes de começar, com 90 dias de garantia.
Quero automatizar minha conciliação