Leitor de Arquivo CNAB

O que é o CNAB?

O CNAB é o padrão brasileiro de arquivos usado na troca de informações bancárias, como cobrança, pagamentos e retorno. Vale lembrar que cada banco acaba adotando pequenas variações próprias.

Cada linha do arquivo é um registro de tamanho fixo (240 ou 400 caracteres). O tipo do registro vem no primeiro caractere: 0=header, 1=header lote, 3=detalhe (com sub-segmentos A/B/C/...), 5=trailer lote, 9=trailer.

Aqui você consegue ver a contagem por tipo e o conteúdo das primeiras linhas, o suficiente para uma inspeção visual. Numa integração de verdade, o caminho é recorrer às libs específicas do banco.

O que é o CNAB e por que ele existe

CNAB significa Centro Nacional de Automação Bancária, um comitê de padronização criado pela FEBRABAN (Federação Brasileira de Bancos) para unificar a forma como os bancos brasileiros e seus clientes corporativos trocam informações financeiras por arquivo. Antes do CNAB, cada banco mantinha um layout próprio para cobrança, pagamento a fornecedores e débito automático, obrigando as empresas a manter uma integração de ERP diferente para cada instituição. O CNAB consolidou esses layouts em uma única especificação posicional de texto, hoje usada por Banco do Brasil, Caixa, Itaú, Bradesco, Santander, BTG Pactual, Banrisul, Sicoob, Sicredi, C6, Inter e dezenas de outros bancos brasileiros.

Um arquivo CNAB é um texto ASCII puro (sem JSON, sem XML, sem delimitadores) no qual cada linha, chamada de registro, tem largura fixa e cada campo ocupa posições fixas de caracteres. Campos numéricos são alinhados à direita com zeros à esquerda; campos alfanuméricos são alinhados à esquerda com brancos à direita. Não há cabeçalho no sentido de CSV nem separador de campo, e por isso um parser que não conheça o layout não consegue interpretar um único byte do arquivo. Em troca, o formato é brutalmente compacto e tem parsing determinístico de altíssima velocidade, propriedades que os bancos valorizavam nos anos 1980 quando o CNAB foi concebido para mainframes e modems discados, e que ainda beneficiam o processamento em lote de alto volume.

Este leitor detecta se o arquivo segue o layout de 240 ou 400 caracteres, separa em registros, identifica os tipos e mostra os campos-chave para que você possa auditar uma remessa antes de enviá-la ao banco ou conciliar um retorno que acabou de cair no seu SFTP.

CNAB 240 vs CNAB 400: diferenças e quando usar cada um

Os dois layouts convivem porque nasceram para gerações diferentes de produtos bancários. O CNAB 400 é a especificação mais antiga: cada transação é uma linha plana de 400 caracteres, sem conceito de lote. É simples, parseável em um loop único e ainda é o único aceito por algumas carteiras legadas de cobrança, especialmente em bancos regionais e contratos antigos de Itaú e Bradesco. O CNAB 400 cobre principalmente cobrança (emissão e baixa de boletos), com pouco espaço para serviços adicionais.

O CNAB 240 é o layout hierárquico moderno. Cada linha tem 240 caracteres e os registros são organizados em lotes, de modo que um único arquivo pode carregar vários produtos: boletos de cobrança no lote 1, pagamentos a fornecedores no lote 2, folha de pagamento no lote 3, tributos (DARF, GPS, FGTS) no lote 4, tudo dentro de um mesmo header e trailer de arquivo. O CNAB 240 também introduziu os segmentos (P, Q, R, S, T, U, Y) dentro do detalhe, o que permite aos bancos adicionar extensões estruturadas sem quebrar o layout base.

Como escolher

• CNAB 400: contratos antigos de boleto, empresas muito pequenas, bancos que ainda não migraram uma carteira específica.
• CNAB 240: qualquer integração nova, qualquer arquivo com mais de um tipo de produto, qualquer boleto com PIX QR Code, qualquer instrução de protesto ou negativação prolongada.
• A FEBRABAN recomenda oficialmente o CNAB 240 para toda integração nova; o CNAB 400 permanece por compatibilidade retroativa.

Estrutura: header de arquivo, header de lote, detalhe, trailer de lote, trailer de arquivo

O CNAB 240 organiza o arquivo como um envelope aninhado. Todo registro tem seu tipo identificado na posição 8 (um dígito), e o parser usa esse byte para direcionar o restante da linha ao mapa de campos correto:

• 0 - Header de Arquivo: uma linha no topo, com código do banco (3 dígitos), número do convênio, CNPJ da empresa, data e hora de geração, sequencial do arquivo e versão do layout.
• 1 - Header de Lote: abre o lote, identifica o tipo de serviço (cobrança, pagamento de fornecedores, folha) e a forma de lançamento (crédito em conta corrente, DOC, TED, PIX, boleto, OP).
• 3 - Detalhe: uma ou mais linhas por transação, divididas em segmentos (P com a identificação do boleto, Q com o sacado, R com desconto e juros, S com o sacador avalista, T e U no retorno).
• 5 - Trailer de Lote: fecha o lote, com quantidade de registros e somatório de valores para conciliação.
• 9 - Trailer de Arquivo: uma linha no fim, com a quantidade total de registros em todos os lotes e uma quantidade final de integridade.

No CNAB 400 a hierarquia é mais rasa: um header na posição 1, linhas sequenciais de transação (registro tipo 1 na remessa de cobrança, tipo 1 no retorno com significado diferente) e um trailer com totais. Não há lotes nem segmentos.

0  Header de Arquivo
1  Header de Lote 1
3 P Detalhe boleto 001
3 Q Detalhe sacado 001
3 P Detalhe boleto 002
3 Q Detalhe sacado 002
5  Trailer de Lote 1
9  Trailer de Arquivo

Remessa vs retorno

O tráfego CNAB acontece em dois sentidos e o formato é o mesmo, mas o significado dos campos muda:

• Remessa (empresa para banco): instruções que você envia. Registrar um boleto novo, alterar uma data de vencimento, conceder desconto, pedir protesto, cancelar uma instrução, agendar um pagamento a fornecedor, debitar uma folha. O código de movimento remessa (posições 16-17 em muitos layouts) diz ao banco o que fazer: 01 entrada de títulos, 02 pedido de baixa, 06 alteração de vencimento, 09 protestar, e assim por diante.
• Retorno (banco para empresa): a resposta do banco. Cada linha conta o que aconteceu: título liquidado, título recebido em custódia, instrução rejeitada (com um código de motivo), pagamento confirmado, débito devolvido. O código de movimento retorno usa uma tabela de códigos diferente da remessa.

Extensões de arquivo que você vai encontrar com frequência: .REM ou .TXT para remessa, .RET ou .TXT para retorno. Muitos bancos também aceitam .CRM e .CRT. A extensão é apenas informativa; o banco valida o layout real.

Aplicações

Cobrança bancária (boleto)

O caso de uso clássico. A empresa envia uma remessa registrando boletos, o banco imprime ou entrega digitalmente, os pagadores quitam por qualquer canal e o banco devolve um retorno confirmando a liquidação. O CNAB sustenta todo o ecossistema de boleto registrado, que processa bilhões de reais por dia no Brasil.

Pagamento de fornecedores

Um único arquivo CNAB 240 pode liberar centenas de pagamentos a fornecedores via DOC, TED, transferência interna ou PIX, com cada segmento carregando banco, agência, conta e CNPJ do favorecido. O retorno confirma quais pagamentos foram efetivados e quais foram rejeitados.

Débito automático

Concessionárias, escolas e academias enviam instruções de débito automático para cobrar clientes nas contas correntes deles em base recorrente. O CNAB transporta o cadastro da autorização, o lote mensal de débitos e o retorno de rejeição quando não há saldo.

Folha de pagamento

Salários continuam sendo liberados via CNAB 240 na maioria das empresas brasileiras de médio e grande porte. O sistema de RH gera o arquivo, o banco credita a conta de cada funcionário na data combinada e devolve um retorno por crédito.

Como interpretar os campos

Ler um CNAB na mão exige um mapa de layout, mas alguns padrões se repetem em quase todo registro:

• Tipo de registro: posição 8 no CNAB 240, identifica header, lote, detalhe ou trailer.
• Código do banco: posições 1-3, o código FEBRABAN (001 BB, 104 Caixa, 237 Bradesco, 341 Itaú, 033 Santander).
• Código de movimento: 2 dígitos que dizem o que fazer (remessa) ou o que aconteceu (retorno).
• Valor: 15 dígitos numéricos, com zeros à esquerda, os 2 últimos são os centavos. Um boleto de R$ 1.234,56 aparece como 000000000123456.
• Data: 8 dígitos em DDMMAAAA. Um vencimento em 15/08/2026 fica 15082026.
• Nosso número: identificador atribuído pelo banco a cada título, de 11 a 20 dígitos dependendo do banco e da carteira.

Migração para CNAB 240 com PIX, e o futuro com SPB modernizado

A FEBRABAN adicionou suporte a PIX no CNAB 240 a partir de 2020. Um boleto pode carregar o payload de PIX QR Code dentro de segmentos dedicados de detalhe, de modo que o mesmo papel ou PDF possa ser pago via PIX ou pelos canais tradicionais de boleto. Os lotes de pagamento a fornecedores também suportam PIX como forma de liberação, com a chave PIX do favorecido (CPF, CNPJ, email, telefone ou EVP aleatória) substituindo os campos de agência e conta.

A direção de médio prazo é API-first: os bancos cada vez mais expõem APIs REST com OAuth e webhooks em tempo real, e a especificação Open Finance Brasil padroniza essas APIs entre instituições. Para fluxos de baixo volume em tempo real, as APIs vencem em latência e observabilidade. O CNAB segue dominante para batches diários de alto volume porque o parsing é rápido, os arquivos são fáceis de retransmitir e auditar, e ERPs inteiros estão conectados ao modelo de lote.

O SPB (Sistema de Pagamentos Brasileiro) está sendo modernizado em paralelo, mas os formatos de mensagem (ISO 20022 sobre os trilhos do SPB) ficam abaixo do CNAB, sem substituí-lo na comunicação cliente-banco. Espere que o CNAB continue evoluindo em layouts versionados (atualmente CNAB 240 v10.11 de 2023) por pelo menos o resto da década.