Integração bancária via API: como sair do CNAB sem susto

Toda manhã, alguém do financeiro entra no internet banking, baixa o arquivo de retorno do dia anterior, importa no sistema e torce para não aparecer erro de layout. À tarde, o mesmo ritual ao contrário: gerar a remessa de boletos, subir no portal do banco e esperar a confirmação de registro.

O arquivo CNAB resolveu durante décadas a conversa entre empresa e banco, e ainda funciona. Mas ele trabalha em lote, com atraso e com intervenção humana no meio: se quem cuida dele sai de férias, a baixa atrasa e o cliente que já pagou recebe cobrança. A integração bancária via API troca o arquivo por chamadas diretas entre o seu sistema e o banco: o boleto é registrado na hora, o Pix avisa quando foi pago e o extrato pode ser consultado sem ninguém baixar nada.

A dúvida de quem decide é prática: vale migrar, o que muda no sistema e como fazer isso sem deixar de cobrar nenhum cliente no meio do caminho. Este texto responde às três.

A resposta curta: CNAB ou API?

Para a maioria das empresas que emite boletos, recebe Pix e paga fornecedores com alguma frequência, a integração bancária via API é o destino, e o CNAB passa a ser plano de contingência ou caminho para bancos que ainda não oferecem a API necessária. A migração não precisa ser de uma vez: dá para mover um produto bancário por vez (primeiro Pix, depois boleto, depois pagamentos) e um banco por vez. Para o Pix, veja também Pix direto no banco ou gateway.

O CNAB continua fazendo sentido quando o volume é pequeno, o banco não oferece a API do produto que você usa ou o sistema atual não tem como chamar serviços externos. Nesses casos, automatizar a troca de arquivos já tira boa parte do trabalho manual.

Como a maioria das empresas ainda fala com o banco

O retrato comum numa empresa média brasileira tem três camadas:

• Cobrança por boleto via CNAB. O ERP gera a remessa, alguém sobe no portal do banco, e o retorno volta no dia seguinte com registros, liquidações e rejeições.
• Pix por QR Code estático ou chave na nota. O cliente paga, mas o sistema não sabe de qual título é aquele dinheiro. Alguém confere o extrato e dá baixa à mão.
• Pagamentos a fornecedores pelo internet banking. O financeiro digita ou importa um arquivo de pagamento, e o aprovador libera no aplicativo do banco.

Cada camada tem um momento em que uma pessoa copia informação de um lugar para outro. É ali que surgem baixa atrasada, pagamento duplicado e título "em aberto" que já foi pago. A conferência entre extrato e contas a receber, que é o fim desse fluxo, está detalhada no texto sobre conciliação bancária automática.

CNAB: remessa, retorno e seus limites

CNAB é o padrão de arquivos de intercâmbio definido pela FEBRABAN. Existem dois layouts principais: o CNAB 240, mais completo e mais aderente ao padrão, e o CNAB 400, mais antigo, em que cada banco tem sua própria versão. Os dois funcionam em pares:

• Remessa: a empresa envia instruções ao banco, como registrar boleto, alterar vencimento, conceder abatimento, pedir baixa ou pagar um fornecedor.
• Retorno: o banco devolve o resultado, com títulos registrados, rejeitados, liquidados, tarifas e ocorrências.

Os limites aparecem no dia a dia:

1. Atraso estrutural. O retorno chega em ciclos, normalmente uma ou duas vezes por dia. Um cliente que pagou de manhã pode receber um lembrete de cobrança à tarde.
2. Variação por banco. Mesmo no CNAB 240, cada banco tem campos opcionais, códigos de ocorrência e particularidades próprias. Trocar de banco ou incluir um segundo significa reescrever partes do gerador e do leitor.
3. Erro tardio. Um CPF inválido ou um campo fora de posição só aparece quando o retorno indica rejeição, e a essa altura o cliente já esperava o boleto.
4. Transporte manual. Se a troca não é automatizada (por VAN ou transferência segura de arquivos), alguém precisa baixar e subir arquivos todos os dias.

Nada disso torna o CNAB errado. Torna o CNAB lento para uma operação que quer saber em minutos o que foi pago.

APIs bancárias: boleto, Pix, pagamentos e extrato

A integração via API substitui o arquivo por chamadas ao banco, feitas pelo próprio sistema. Os produtos mais comuns são quatro, e cada um tem um grau diferente de padronização.

Pix

O Pix tem a API mais padronizada do mercado, definida pelo Banco Central e implementada pelos bancos e instituições de pagamento. Com ela, o sistema:

• cria uma cobrança imediata ou com vencimento (com juros, multa e desconto), já com o identificador do título;
• recebe uma notificação (webhook) quando o pagamento entra;
• consulta cobranças e Pix recebidos e trata devoluções.

O ganho principal é a baixa automática: cada QR Code nasce ligado a um título, e o pagamento volta com esse identificador. Não há mais extrato para garimpar. Para quem cobra mensalidade, o Pix Automático leva isso adiante com autorização recorrente, assunto do texto sobre cobrança recorrente com Pix Automático.

Boleto

As APIs de boleto não seguem um padrão único: cada banco tem a sua. Em geral, permitem registrar o boleto na hora e receber de volta a linha digitável e o código de barras, alterar vencimento e valores de abatimento, baixar e consultar a situação. Muitos bancos já devolvem o boleto com QR Code Pix junto, o que deixa o cliente escolher como pagar.

Pagamentos

Pagamento de boletos de fornecedores, tributos com código de barras, transferências e Pix de saída. Aqui a API precisa respeitar a alçada de aprovação da empresa: o sistema prepara o lote, o aprovador libera (no próprio sistema ou no aplicativo do banco, conforme o modelo do banco) e o resultado volta pela API. Esse é o produto em que mais vale ir devagar, porque o erro tira dinheiro da conta.

Extrato e saldo

Consultar lançamentos e saldo por API fecha o ciclo: o sistema confere o que entrou e o que saiu sem depender do arquivo de extrato. A disponibilidade varia por banco e por tipo de conta, e em alguns casos o caminho é o Open Finance, com consentimento da própria empresa.

Vários bancos ao mesmo tempo sem duplicar código

Empresas médias raramente têm um banco só. Há o banco principal da cobrança, o que dá a melhor taxa de antecipação e o que veio junto com um financiamento. Se cada integração for escrita direto dentro do ERP ou do sistema de vendas, a regra de negócio fica espalhada e trocar de banco vira projeto.

O desenho que usamos separa duas camadas:

• Camada de domínio: o sistema conhece "título a receber", "cobrança", "pagamento", "baixa". Ele não sabe qual banco está do outro lado.
• Adaptadores por banco: um módulo para cada banco traduz essas operações para a API ou para o CNAB daquele banco, e traduz as respostas de volta.

Com isso, incluir um banco novo é escrever um adaptador, sem mexer em contas a receber. E o mesmo título pode ser emitido pelo banco A em um mês e pelo banco B no seguinte, por regra de roteamento (carteira, tipo de cliente, custo da tarifa negociada) definida pelo financeiro. Essa separação é uma decisão de arquitetura de software, e é ela que evita que o sistema fique preso ao primeiro banco que foi integrado.

Certificados, credenciais e segurança

A API bancária mexe diretamente com dinheiro, e os bancos exigem camadas de proteção que o arquivo CNAB não tinha:

• Certificado digital para autenticar a conexão (no Pix, a conexão usa TLS mútuo, em que empresa e banco se identificam um ao outro).
• Credenciais da aplicação (identificador e segredo) para obter tokens de acesso, que expiram e precisam ser renovados pelo sistema.
• Escopos que limitam o que cada credencial pode fazer: emitir cobrança é uma coisa, pagar fornecedor é outra.

Na prática, isso exige alguns cuidados:

1. Guardar certificado e segredo num cofre de segredos, nunca no código, em e-mail ou em pasta compartilhada.
2. Controlar o vencimento do certificado. Certificado vencido derruba a conexão com o banco e, com ela, a emissão de cobranças. Um alerta com semanas de antecedência e um responsável pela renovação evitam a surpresa.
3. Separar credenciais por produto e ambiente. A credencial de homologação não deve existir em produção, e a de pagamento não deve estar disponível para o módulo de cobrança.
4. Validar a origem dos webhooks. Notificação de pagamento só é aceita se vier do banco, pelo canal autenticado. Sem isso, qualquer um pode "avisar" que um título foi pago.
5. Registrar quem fez o quê, com trilha de auditoria para emissões, alterações, baixas e pagamentos.

Os erros mais frequentes nesse tipo de integração, como segredo exposto em log ou endpoint sem autenticação, estão no texto sobre segurança de APIs e os erros mais comuns. E como cobrança carrega nome, CPF e endereço de clientes, a LGPD vale para logs, filas e backups da integração como vale para o resto do sistema.

Plano de transição sem parar a cobrança

Migrar de CNAB para API é trocar o motor com o carro andando. O roteiro que seguimos:

1. Inventário. Liste bancos, carteiras, produtos (boleto, Pix, pagamentos, extrato) e volumes. Confira com o gerente de cada banco quais APIs estão disponíveis para a sua conta e quais exigem contrato ou habilitação.
2. Escolha do primeiro produto. O Pix com vencimento ou imediato costuma ser o melhor começo: padronizado, com ganho visível na baixa automática e sem afetar os boletos em circulação.
3. Homologação. Os bancos que oferecem API costumam disponibilizar um ambiente de testes (sandbox). Rode ali os casos difíceis: pagamento parcial, pagamento duplicado, devolução, boleto vencido pago com juros, título alterado depois de emitido.
4. Convivência. Durante a transição, títulos antigos continuam no CNAB até serem liquidados ou baixados; títulos novos nascem pela API. O sistema precisa saber por qual canal cada título foi emitido, para não pedir baixa no canal errado.
5. Corte por carteira. Migre uma carteira ou um banco de cada vez, com data marcada e alguém do financeiro acompanhando os primeiros dias.
6. CNAB como reserva. Mantenha a geração de remessa funcionando por um período. Se a API do banco ficar fora do ar por horas, a cobrança segue pelo arquivo.
7. Desligamento. Só desative a rotina de arquivos quando a conciliação bater de forma consistente e não houver mais títulos abertos emitidos por ela.

O prazo depende do número de bancos e produtos e da situação do sistema atual. Também pesa o tempo de habilitação de cada banco: liberar credenciais, contrato e acesso à produção depende do banco, não só da equipe de desenvolvimento. Por isso o cronograma só fica firme depois do diagnóstico.

Checklist antes de ligar em produção

• Certificados instalados, com data de vencimento monitorada?
• Webhooks validados e com resposta rápida, deixando o processamento pesado para depois?
• Idempotência: a mesma notificação de pagamento recebida duas vezes baixa o título só uma vez?
• Consulta periódica de segurança para pegar pagamentos cujo aviso não chegou?
• Fila de exceções com dono no financeiro?
• Roteiro de contingência pelo CNAB testado?

Monitoramento: quando o banco não responde

APIs bancárias ficam indisponíveis, respondem devagar em dia de pico (início de mês, véspera de feriado) e às vezes devolvem erro genérico. A integração precisa assumir isso desde o início:

• Retentativa com espera crescente para falhas temporárias, sem disparar a mesma chamada em sequência e piorar a situação.
• Fila entre o sistema e o banco: se a emissão não sai agora, o pedido de registro fica guardado e sai assim que o banco voltar, sem perder nem duplicar.
• Webhook não é garantia. Notificações podem atrasar ou não chegar. Uma rotina de consulta periódica confere cobranças em aberto e pega o que ficou para trás.
• Painel de saúde com taxa de erro por banco, tempo de resposta, fila pendente e títulos sem confirmação de registro.
• Alertas que chegam a uma pessoa, não só a um log: certificado perto de vencer, fila crescendo, banco sem responder há mais de alguns minutos.

Perguntas frequentes

Qual a diferença entre CNAB 240 e CNAB 400?

O CNAB 240 é o layout mais completo e mais aderente ao padrão da FEBRABAN, com registros de 240 posições. O CNAB 400 é mais antigo, usa registros de 400 posições e cada banco mantém a sua própria versão dele. Os dois funcionam com arquivos de remessa e retorno, e ambos exigem atenção às particularidades de cada banco.

Todos os bancos oferecem API de boleto?

Não da mesma forma. As APIs de boleto não seguem um padrão único: cada banco tem a sua, com recursos, exigências de contrato e prazos de habilitação próprios. Já a API Pix é padronizada pelo Banco Central. Por isso o primeiro passo é confirmar com o gerente de cada banco quais APIs estão disponíveis para a conta da empresa.

Precisa de certificado digital para usar API bancária?

Na maioria dos casos, sim. As APIs bancárias costumam exigir certificado digital para autenticar a conexão, e no Pix a comunicação usa TLS mútuo, em que empresa e banco se identificam um ao outro. Além do certificado, o sistema usa credenciais da aplicação para obter tokens de acesso, que expiram e precisam ser renovados automaticamente.

Quanto tempo leva para migrar do CNAB para API?

Depende do número de bancos e produtos, do estado do sistema atual e do tempo que cada banco leva para liberar credenciais e acesso à produção. A migração do CNAB para API costuma ser feita por etapas, começando pelo Pix e seguindo para boleto e pagamentos, com o arquivo mantido como reserva. O cronograma firme só sai depois do diagnóstico.

Como a Pervian Tech trabalha integrações bancárias

Na Pervian Tech, começamos pelo diagnóstico: quais bancos e produtos a empresa usa, onde a baixa e a conciliação ainda são manuais, como o sistema atual gera remessa e lê retorno e quais APIs cada banco oferece para a sua conta. A partir daí desenhamos a integração sob medida, com camada de domínio separada dos adaptadores por banco, fila, idempotência, monitoramento e o CNAB mantido como reserva enquanto fizer sentido. Mais sobre esse tipo de projeto está na página de integração de sistemas e nos outros textos da categoria integrações.

O diagnóstico inicial é gratuito, e o cronograma segue fases (diagnóstico, primeiro produto em homologação, produção, demais bancos e produtos). O investimento é sob consulta, porque depende do número de bancos, de produtos e do estado do sistema atual. Se o seu financeiro ainda começa o dia baixando arquivo de retorno, conte como funciona hoje.