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

> Integração bancária via API ou arquivo CNAB? Compare remessa e retorno com as APIs de boleto, Pix e pagamentos e veja como migrar sem parar a cobrança.

Fonte: https://pervian.tech/blog/integracao-bancaria-cnab-e-api · Pervian Tech · publicado em 2026-10-01

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](https://pervian.tech/blog/pix-direto-no-banco-ou-gateway).

| Critério | Arquivo CNAB (remessa e retorno) | API bancária |
|---|---|---|
| Momento do registro do boleto | Quando a remessa é processada | Na hora da chamada |
| Aviso de pagamento | No retorno do dia seguinte, em geral | Em minutos, por notificação ou consulta |
| Intervenção humana | Comum: baixar, subir, importar | Nenhuma no fluxo normal |
| Erro | Descoberto quando o retorno chega | Devolvido na resposta da chamada |
| Padronização entre bancos | Layout base comum, com variações por banco | Pix padronizado; boleto e pagamentos variam por banco |
| Esforço técnico | Menor no início, alto na manutenção manual | Maior no início, menor na operação |
| Segurança | Arquivo em pasta ou portal | Certificado, credenciais e canal criptografado |

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](https://pervian.tech/blog/automatizar-contas-a-pagar) 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](https://pervian.tech/blog/conciliacao-bancaria-automatica).

## 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](https://pervian.tech/blog/webhook-o-que-e))** 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](https://pervian.tech/blog/cobranca-recorrente-com-pix-automatico).

### 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](https://pervian.tech/blog/workflow-de-aprovacao-por-alcada)** 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](https://pervian.tech/servicos/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](https://pervian.tech/blog/senhas-e-chaves-de-api-no-codigo)**, 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](https://pervian.tech/blog/seguranca-de-apis-erros-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](https://pervian.tech/solucoes/integracao-de-sistemas) e nos outros textos da categoria [integrações](https://pervian.tech/blog/categoria/integracoes).

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](https://pervian.tech/#contato).