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 e o CNAB e por que ele existe

CNAB significa Centro Nacional de Automacao Bancaria, um comite de padronizacao criado pela FEBRABAN (Federacao Brasileira de Bancos) para unificar a forma como os bancos brasileiros e seus clientes corporativos trocam informacoes financeiras por arquivo. Antes do CNAB, cada banco mantinha um layout proprio para cobranca, pagamento a fornecedores e debito automatico, obrigando as empresas a manter uma integracao de ERP diferente para cada instituicao. O CNAB consolidou esses layouts em uma unica especificacao posicional de texto, hoje usada por Banco do Brasil, Caixa, Itau, Bradesco, Santander, BTG Pactual, Banrisul, Sicoob, Sicredi, C6, Inter e dezenas de outros bancos brasileiros.

Um arquivo CNAB e um texto ASCII puro (sem JSON, sem XML, sem delimitadores) no qual cada linha, chamada de registro, tem largura fixa e cada campo ocupa posicoes fixas de caracteres. Campos numericos sao alinhados a direita com zeros a esquerda; campos alfanumericos sao alinhados a esquerda com brancos a direita. Nao ha cabecalho no sentido de CSV nem separador de campo, e por isso um parser que nao conheca o layout nao consegue interpretar um unico byte do arquivo. Em troca, o formato e brutalmente compacto e tem parsing deterministico de altissima 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 voce possa auditar uma remessa antes de envia-la ao banco ou conciliar um retorno que acabou de cair no seu SFTP.

CNAB 240 vs CNAB 400: diferencas e quando usar cada um

Os dois layouts convivem porque nasceram para geracoes diferentes de produtos bancarios. O CNAB 400 e a especificacao mais antiga: cada transacao e uma linha plana de 400 caracteres, sem conceito de lote. E simples, parseavel em um loop unico e ainda e o unico aceito por algumas carteiras legadas de cobranca, especialmente em bancos regionais e contratos antigos de Itau e Bradesco. O CNAB 400 cobre principalmente cobranca (emissao e baixa de boletos), com pouco espaco para servicos adicionais.

O CNAB 240 e o layout hierarquico moderno. Cada linha tem 240 caracteres e os registros sao organizados em lotes, de modo que um unico arquivo pode carregar varios produtos: boletos de cobranca 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 tambem introduziu os segmentos (P, Q, R, S, T, U, Y) dentro do detalhe, o que permite aos bancos adicionar extensoes estruturadas sem quebrar o layout base.

Como escolher

• CNAB 400: contratos antigos de boleto, empresas muito pequenas, bancos que ainda nao migraram uma carteira especifica.
• CNAB 240: qualquer integracao nova, qualquer arquivo com mais de um tipo de produto, qualquer boleto com PIX QR Code, qualquer instrucao de protesto ou negativacao prolongada.
• A FEBRABAN recomenda oficialmente o CNAB 240 para toda integracao 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 posicao 8 (um digito), 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 codigo do banco (3 digitos), numero do convenio, CNPJ da empresa, data e hora de geracao, sequencial do arquivo e versao do layout.
• 1 - Header de Lote: abre o lote, identifica o tipo de servico (cobranca, pagamento de fornecedores, folha) e a forma de lancamento (credito em conta corrente, DOC, TED, PIX, boleto, OP).
• 3 - Detalhe: uma ou mais linhas por transacao, divididas em segmentos (P com a identificacao 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 somatorio de valores para conciliacao.
• 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 e mais rasa: um header na posicao 1, linhas sequenciais de transacao (registro tipo 1 na remessa de cobranca, tipo 1 no retorno com significado diferente) e um trailer com totais. Nao ha 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 trafego CNAB acontece em dois sentidos e o formato e o mesmo, mas o significado dos campos muda:

• Remessa (empresa para banco): instrucoes que voce envia. Registrar um boleto novo, alterar uma data de vencimento, conceder desconto, pedir protesto, cancelar uma instrucao, agendar um pagamento a fornecedor, debitar uma folha. O codigo de movimento remessa (posicoes 16-17 em muitos layouts) diz ao banco o que fazer: 01 entrada de titulos, 02 pedido de baixa, 06 alteracao de vencimento, 09 protestar, e assim por diante.
• Retorno (banco para empresa): a resposta do banco. Cada linha conta o que aconteceu: titulo liquidado, titulo recebido em custodia, instrucao rejeitada (com um codigo de motivo), pagamento confirmado, debito devolvido. O codigo de movimento retorno usa uma tabela de codigos diferente da remessa.

Extensoes de arquivo que voce vai encontrar com frequencia: .REM ou .TXT para remessa, .RET ou .TXT para retorno. Muitos bancos tambem aceitam .CRM e .CRT. A extensao e apenas informativa; o banco valida o layout real.

Aplicacoes

Cobranca bancaria (boleto)

O caso de uso classico. 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 liquidacao. O CNAB sustenta todo o ecossistema de boleto registrado, que processa bilhoes de reais por dia no Brasil.

Pagamento de fornecedores

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

Debito automatico

Concessionarias, escolas e academias enviam instrucoes de debito automatico para cobrar clientes nas contas correntes deles em base recorrente. O CNAB transporta o cadastro da autorizacao, o lote mensal de debitos e o retorno de rejeicao quando nao ha saldo.

Folha de pagamento

Salarios continuam sendo liberados via CNAB 240 na maioria das empresas brasileiras de medio e grande porte. O sistema de RH gera o arquivo, o banco credita a conta de cada funcionario na data combinada e devolve um retorno por credito.

Como interpretar os campos

Ler um CNAB na mao exige um mapa de layout, mas alguns padroes se repetem em quase todo registro:

• Tipo de registro: posicao 8 no CNAB 240, identifica header, lote, detalhe ou trailer.
• Codigo do banco: posicoes 1-3, o codigo FEBRABAN (001 BB, 104 Caixa, 237 Bradesco, 341 Itau, 033 Santander).
• Codigo de movimento: 2 digitos que dizem o que fazer (remessa) ou o que aconteceu (retorno).
• Valor: 15 digitos numericos, com zeros a esquerda, os 2 ultimos sao os centavos. Um boleto de R$ 1.234,56 aparece como 000000000123456.
• Data: 8 digitos em DDMMAAAA. Um vencimento em 15/08/2026 fica 15082026.
• Nosso numero: identificador atribuido pelo banco a cada titulo, de 11 a 20 digitos dependendo do banco e da carteira.

Migracao 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 tambem suportam PIX como forma de liberacao, com a chave PIX do favorecido (CPF, CNPJ, email, telefone ou EVP aleatoria) substituindo os campos de agencia e conta.

A direcao de medio prazo e API-first: os bancos cada vez mais expoem APIs REST com OAuth e webhooks em tempo real, e a especificacao Open Finance Brasil padroniza essas APIs entre instituicoes. Para fluxos de baixo volume em tempo real, as APIs vencem em latencia e observabilidade. O CNAB segue dominante para batches diarios de alto volume porque o parsing e rapido, os arquivos sao faceis de retransmitir e auditar, e ERPs inteiros estao conectados ao modelo de lote.

O SPB (Sistema de Pagamentos Brasileiro) esta sendo modernizado em paralelo, mas os formatos de mensagem (ISO 20022 sobre os trilhos do SPB) ficam abaixo do CNAB, sem substitui-lo na comunicacao cliente-banco. Espere que o CNAB continue evoluindo em layouts versionados (atualmente CNAB 240 v10.11 de 2023) por pelo menos o resto da decada.

FAQ

Por que o arquivo abre como uma unica linha em alguns editores?

Arquivos CNAB usam CRLF (quebra de linha Windows) por padrao. Se voce abrir em um editor que so reconhece LF, os registros se juntam em uma linha enorme. Salve com quebras corretas ou use uma ferramenta que entenda CNAB.

Posso editar um CNAB em planilha?

Fortemente desaconselhado. Planilhas removem zeros a esquerda das colunas numericas, convertem numeros longos para notacao cientifica e quebram o alinhamento fixo. Sempre edite CNAB em editor de texto de largura fixa ou regenere a partir do sistema de origem.

O CNAB e igual em todos os bancos?

O esqueleto e. Posicoes especificas de campos proprietarios (codigos de ocorrencia, identificadores de carteira, areas de uso livre) variam, e por isso cada banco publica seu proprio manual em cima da base FEBRABAN.

Como o CNAB se compara ao OFX?

O OFX (Open Financial Exchange) e um formato baseado em XML/SGML usado principalmente para download de extratos bancarios em softwares de financas pessoais. O CNAB e texto posicional usado para lotes de instrucao entre empresas e bancos. Resolvem problemas diferentes e nao se sobrepoem na pratica.

Este leitor envia meu arquivo a um servidor?

Nao. O parsing acontece inteiramente no seu navegador, em JavaScript local. O arquivo nunca sai da sua maquina, o que importa porque o conteudo CNAB inclui CNPJs, numeros de conta e valores.