CNABLens

Uma lente para arquivos CNAB. Abra um arquivo de remessa ou retorno de cobrança bancária (CNAB400 ou CNAB240) e veja cada lançamento com o nome correto de cada campo, a posição no layout, o valor e a descrição oficial. Aplicativo para Windows e Linux, roda 100% no seu computador, sem instalação.

1. Para que serve
2. Recursos
3. Download e instalação
4. Como usar
5. Layouts suportados
6. Arquivos de exemplo
7. Guia rápido de CNAB
8. Para desenvolvedores
9. Versões e releases
10. Segurança e privacidade
11. Limitações conhecidas
12. Contribuindo
13. Licença, avisos e fontes

Arquivos CNAB são texto de largura fixa: cada linha tem 400 (ou 240) caracteres e o significado de cada trecho depende da posição e do banco. Abrir um deles no Bloco de Notas mostra só uma parede de números. Este programa faz a leitura por você:

• Conferir um retorno: quais boletos foram liquidados, com que valor, em que data, com qual ocorrência (ex.: "06 - Liquidação Normal").
• Conferir uma remessa antes de enviar ao banco: valores, vencimentos, pagador, instruções.
• Depurar integração: descobrir em qual posição está um campo e o que ele deveria conter, sem abrir o manual do banco.
• Estudar o layout: cada campo traz a descrição transcrita do manual oficial.

• CNAB400 e CNAB240, remessa e retorno, com detecção automática do formato.
• Layouts por banco: FEBRABAN (padrão), Sicredi, Sicoob e Santander (400) e Sicoob e Santander (240), incluindo os registros de QR Code/PIX do Santander. O layout do banco é escolhido sozinho pelo código no Header, e dá para trocar na hora sem reabrir o arquivo.
• Navegação por pasta: escolha uma pasta, filtre por extensão e veja o tipo de cada arquivo (REM/RET) na lista.
• Todos os campos de cada registro: nome, posição (início-fim), valor e descrição. Valores em centavos viram R$ 1.234,56 e datas viram 25/10/2026, sempre mostrando também o valor bruto.
• Títulos CNAB240 por segmento: um lançamento reúne seus segmentos (P+Q+R na remessa, T+U no retorno), cada um em uma faixa própria. Header/Trailer de arquivo e de lote em um clique.
• Copiar qualquer valor: os textos do painel de campos são selecionáveis. Arraste para selecionar, Ctrl+C para copiar. Duplo clique seleciona a célula inteira. Sem botão extra.
• Tabelas de códigos: ocorrências de retorno, comandos de remessa, bancos e espécies de título aparecem traduzidos.
• Leitura tolerante: datas em DDMMAA, AAAAMMDD ou DDMMAAAA; só formata quando a data é válida, nunca inventa uma. Campos reservados aparecem esmaecidos.
• Somente leitura: o programa nunca altera nem grava nenhum arquivo.

Não precisa instalar nada (nem Python).

Os executáveis ficam na página de Releases. A marcada Latest é a versão de produção, e cada versão traz os dois sistemas:

1. Baixe o .exe da versão mais recente.

2. (Recomendado) confira o hash no PowerShell e compare com o SHA256SUMS.txt da mesma release:

   Get-FileHash .\CNABLens-v0.2.0-windows-x64.exe -Algorithm SHA256

3. Dê dois cliques no .exe.

1. Baixe o CNABLens-vX.Y.Z-linux-x64 e o SHA256SUMS-linux.txt da mesma release.

2. Confira o hash, dê permissão de execução e abra (ou dê dois cliques no arquivo):

   sha256sum -c SHA256SUMS-linux.txt
   chmod +x CNABLens-v0.2.0-linux-x64
   ./CNABLens-v0.2.0-linux-x64

Não precisa instalar Python nem Tk: vai tudo dentro do executável. Detalhes, distros suportadas e como compilar no Linux estão em packaging/linux/README.md.

Verificação avançada: os .exe compilados pelo CI têm atestado de procedência (prova de que foram gerados por este repositório, naquele commit): gh attestation verify CNABLens-vX.Y.Z-windows-x64.exe --repo BrunodosSantosVaz/cnab-lens.

Aviso do Windows / antivírus. O executável não é assinado digitalmente, então o SmartScreen pode mostrar "O Windows protegeu seu computador". Clique em Mais informações → Executar assim mesmo. Alguns antivírus também costumam marcar como suspeitos executáveis gerados com PyInstaller (falso positivo comum). Por isso o código-fonte é aberto: você pode auditá-lo e compilar o seu próprio .exe (veja Para desenvolvedores).

1. Abra o programa e clique em Selecionar pasta... (ou Ctrl+O), escolhendo a pasta com os arquivos CNAB. Se houver mais de um tipo de arquivo, o programa pergunta qual extensão listar; dá para trocar depois em Mostrar.
2. Clique em um arquivo da lista à esquerda. O topo mostra o resumo: tipo (Remessa/Retorno), formato (CNAB400/CNAB240), banco, empresa, data de geração e número de lançamentos.
3. A grade de lançamentos lista cada título com ocorrência, nº do documento, vencimento, valor, nosso número e pagador (ou valor pago, no retorno).
4. Clique em um lançamento: o painel de baixo mostra todos os campos dele.
5. Ver Header do arquivo e Ver Trailer do arquivo mostram os registros de abertura e fechamento; ← Voltar aos Lançamentos retorna ao último título visto.
6. Se o layout escolhido automaticamente não for o que você quer, troque em Layout de campos. O layout precisa ter o mesmo tamanho de linha do arquivo (400 ou 240): se você escolher um de tamanho diferente, o programa avisa e mantém o layout atual.

O painel é somente leitura: não dá para digitar nem colar nele.

O seletor Layout de campos oferece:

Notas por layout:

• FEBRABAN: usado por muitos bancos com pequenas variações. Se o seu banco divergir, o valor bruto continua correto e só o rótulo do campo pode diferir.
• Sicredi: layout próprio (Tipo de Cobrança, Boleto Híbrido/Pix, Nosso Número AA/BXXXXX-D separado em partes, Beneficiário Final etc.). A data do Header é AAAAMMDD.
• Sicoob 400: o Detalhe tipo 1 é o único registro de título; o Trailer é diferente na remessa e no retorno; o retorno não traz o nome do pagador (só o CPF/CNPJ).
• Sicoob 240: Header/Trailer de arquivo e de lote, segmentos P, Q, R, S (remessa) e T, U (retorno), com Nosso Número de 20 posições. É o layout usado para arquivos CNAB240 de bancos sem layout próprio: a estrutura de lote/segmento (padrão FEBRABAN) é a mesma, mas campos específicos do banco podem divergir.
• Santander 400: além do Detalhe (tipo 1), descreve o registro 8 (tipo de pagamento e dados de QR Code/PIX, opcional) e as mensagens 2 e 4 a 7 na remessa, e o registro 2 (QR Code/PIX) no retorno. Esses registros aparecem agrupados sob o boleto a que pertencem. O Header aceita o banco 033 ou o código legado 353.
• Santander 240: Header/Trailer de arquivo e de lote, segmentos P, Q, R, S (remessa) e T, U (retorno), com Nosso Número de 13 posições. O segmento Y (QR Code/PIX e tipo de pagamento na remessa; QR Code/PIX e cheque no retorno) é identificado pelo sub-código das posições 18-19 (Y-03, Y-53, Y-04), e o segmento S tem dois formatos, escolhidos pela posição 18.

A pasta exemplos/ traz um par remessa/retorno 100% fictício para cada layout (empresa, CPF/CNPJ, pagadores e valores inventados), ideal para conhecer o programa:

Abra o programa, selecione a pasta exemplos/ e clique nos arquivos. Para regenerá-los: python scripts/gerar_exemplos.py.

• Remessa: arquivo que a empresa envia ao banco com os títulos a cobrar (ou instruções sobre eles: baixa, alteração de vencimento, protesto...).
• Retorno: arquivo que o banco devolve contando o que aconteceu (título registrado, liquidado, baixado, rejeitado...).
• CNAB400: linhas de 400 caracteres. Header (tipo 0) abre o arquivo, cada Detalhe (tipo 1) é um título, o Trailer (tipo 9) fecha.
• CNAB240: linhas de 240 caracteres, com o tipo do registro na posição 8: Header de Arquivo (0), Header de Lote (1), Detalhe (3), Trailer de Lote (5) e Trailer de Arquivo (9). O detalhe se divide em segmentos (letra na posição 14): na remessa de cobrança, P (dados do título), Q (pagador), R (multa/desconto) e S (mensagens); no retorno, T (título) e U (valores e datas).
• Valores vêm sem vírgula (0000015990 = R$ 159,90) e datas sem separador.

cnab-lens/
├── src/cnablens/                 Código-fonte (pacote Python; só biblioteca padrão)
│   ├── __main__.py               Ponto de entrada (python -m cnablens)
│   ├── version.py                Versão do programa
│   ├── formatacao.py             Valores em R$, datas e o valor como aparece na tela
│   ├── leitura/                  Leitura dos arquivos (não depende da interface)
│   │   ├── __init__.py           CnabFile: lê o arquivo e aplica o layout
│   │   ├── leitor400.py          Regras do CNAB 400 (Header, Detalhe, registros opcionais)
│   │   ├── leitor240.py          Regras do CNAB 240 (lotes e segmentos)
│   │   ├── registro.py           CnabRecord (uma linha) e CnabGroup (um lançamento)
│   │   └── pasta.py              Arquivos de uma pasta e o tipo (REM/RET) de cada um
│   ├── layouts/                  Layouts dos bancos
│   │   ├── __init__.py           Registro dos layouts (seletor e escolha automática pelo banco)
│   │   ├── base.py               Layout400, Layout240, PorTipo... e a validação das posições
│   │   ├── bancos.py             Nomes dos bancos
│   │   └── febraban400.py, sicredi400.py, sicoob400.py, santander400.py, sicoob240.py, santander240.py
│   └── interface/                Tela (Tkinter): janela, painel de campos, lista de arquivos e estilo
├── tests/                        Testes automatizados (unittest)
├── packaging/                    Compiladores (as versões oficiais saem do CI)
│   ├── windows/build_exe.py      Compila o .exe do Windows
│   └── linux/
│       ├── build_linux.py        Compila o executável Linux (mesmas opções do build_exe.py)
│       ├── compilar.sh           Compila no container manylinux_2_28, para rodar em qualquer distro
│       └── README.md             Baixar, rodar e compilar no Linux
├── scripts/
│   ├── gerar_exemplos.py         Gera os arquivos fictícios de exemplos/
│   └── processo/                 Configuração do GitHub (labels, painéis, automações)
├── exemplos/                     Arquivos CNAB fictícios de exemplo
├── docs/                         Processo de desenvolvimento e imagens do README
├── .github/                      Workflows (CI, build, release), modelos de issue/PR, automações
├── pyproject.toml                Metadados do projeto, versão (lida de src/cnablens/version.py) e Ruff
├── requirements-build.txt        Dependência de build (PyInstaller)
├── AGENTS.md, CLAUDE.md          Instruções para IAs que trabalham no projeto
├── CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md
└── LICENSE

Requer Python 3.10 ou superior com Tkinter (o instalador oficial do Python para Windows já inclui; no Linux, instale o pacote tk/python3-tk da sua distro). Nenhuma biblioteca externa é necessária para rodar.

git clone https://github.com/BrunodosSantosVaz/cnab-lens.git
cd cnab-lens
python src\cnablens\__main__.py

Ou instale o projeto para desenvolver (pip install -e .) e rode python -m cnablens.

python -m unittest discover -s tests -v
uvx ruff check .          # estilo e qualidade (regras em pyproject.toml); ou: pip install ruff && ruff check .

A suíte cobre as tabelas de layout, a leitura dos arquivos de exemplo (400 e 240), a formatação de valores e datas e a interface (cópia de valores, alinhamento, troca de layout). Ela roda a cada pull request no GitHub Actions (Windows), junto com o Ruff (job lint) e a compilação do executável Linux. Um teste de equivalência compara a leitura de todos os exemplos, em todos os layouts, com um retrato guardado em tests/dados/: uma mudança que altere o que o programa mostra aparece ali.

Windows:

pip install -r requirements-build.txt
python packaging\windows\build_exe.py

O script compila com PyInstaller (fora do repositório, sem deixar build/ ou .spec), embute os metadados de versão no .exe e grava o resultado, com o SHA256SUMS.txt, em build-local/ (ignorada pelo Git). A versão vem de src/cnablens/version.py.

Linux (precisa de Docker; veja packaging/linux/README.md):

bash packaging/linux/compilar.sh           # versão atual
bash packaging/linux/compilar.sh v0.2.0    # a partir de uma tag

Compila dentro de um container antigo (glibc 2.28), para o executável rodar em qualquer distro, e grava CNABLens-vX.Y.Z-linux-x64 e o SHA256SUMS.txt em build-local/.

Os executáveis oficiais (candidatas e produção, Windows e Linux) são gerados pelo CI e publicados nas Releases, não à mão.

1. Leitura (cnablens.leitura): o CnabFile lê as linhas uma vez, detecta o tamanho (400 ou 240) e entrega o trabalho ao leitor do formato (Leitor400 ou Leitor240, padrão Strategy). O leitor classifica cada registro (posição 1 no CNAB 400; posição 8 e segmento na posição 14 no CNAB 240) e lê pelo Header o tipo (remessa/retorno), o banco, a empresa e a data.
2. Layout (cnablens.layouts): diz quais campos, nomes e posições aplicar a cada tipo de registro. Trocar o layout só reaplica os nomes, sem reler o disco. No CNAB 240, os segmentos de um título viram um lançamento (CnabGroup); no CNAB 400, o Detalhe leva junto os registros opcionais que o layout descreve.
3. Formatação (cnablens.formatacao): valores em R$ e datas, sempre com o valor bruto ao lado.
4. Interface (cnablens.interface): mostra a grade de lançamentos e o painel de campos. Ela só apresenta; a leitura e a formatação funcionam sem Tkinter.

1. Crie o módulo de dados em src/cnablens/layouts/ (ex.: itau400.py) no estilo de sicredi400.py: listas de tuplas (nome do campo, início, fim, descrição) que cobrem as posições 1–400 (ou 1–240) sem lacunas, mais as tabelas de ocorrência. Só dados: nada de lógica.
2. Registre o layout em src/cnablens/layouts/__init__.py: um Layout400 (ou Layout240) em LAYOUTS, usando PorTipo(remessa, retorno) para as listas, a chave em LAYOUT_ORDER e, para a escolha automática pelo código do banco, em AUTO_LAYOUT_BY_BANK. O seletor da tela se atualiza sozinho, e a leitura não muda.
3. Confira as posições com python -m cnablens.layouts (a partir de src/); os testes fazem o mesmo.
4. Use estes nomes de campo para o resumo da grade funcionar: Nosso Número (ou Nosso Número [Parte]), Número do Documento, Data de Vencimento, Valor Nominal, Código da Ocorrência / Identificação da Ocorrência / Código de Movimento, Nome do Sacado ou Nome do Pagador e Valor Pago. Campos com "Data" no nome são formatados como data; os com "Valor", "Juros", "Mora", "Desconto", "Abatimento", "IOF", "Tarifa" ou "Despesa" como moeda, exceto se o nome também trouxer "Código", "Tipo", "Taxa", "Percentual" etc.
5. Gere um arquivo fictício para o layout (veja scripts/gerar_exemplos.py), confira na tela e regere o retrato de equivalência (python tests/test_equivalencia.py --gerar), porque o layout novo muda o que o programa mostra.

O projeto usa versionamento semântico (MAIOR.MENOR.PATCH) e cada versão é registrada no CHANGELOG. Antes da 1.0, MENOR sobe com funcionalidade nova e PATCH com correção.

A versão diz o ambiente, e todos os executáveis (Windows e Linux) ficam no mesmo lugar, a página de Releases:

Toda homologação tem versão: antes de testar, o CI cria a candidata vX.Y.Z-rc.N com o .exe e o executável Linux. Aprovada, os mesmos binários são promovidos a produção (vX.Y.Z) pela ação Publicar em produção, com a aprovação do mantenedor. Enquanto não há candidata aberta, a homologação é a própria versão em produção. As pre-releases são para quem quer ajudar a testar: para uso normal, baixe a versão Latest. Mudanças que não alteram o programa (documentação, testes, automação) levam a label sem-executavel: não geram versão nem candidata e chegam à main pelo botão Publicar sem executável. Os executáveis ficam só nas Releases: o repositório guarda o código, e cada versão pode ser recompilada a partir da sua tag. O ciclo completo (planejamento, testes, build no CI, aprovação e publicação) está em docs/processo.md.

• Tudo local. O programa não usa rede, não envia nada para lugar nenhum, não tem telemetria e não grava nem altera arquivos. Ele só lê o arquivo que você seleciona.
• Dados pessoais. Arquivos CNAB reais contêm nomes, CPF/CNPJ, endereços e valores de terceiros (dados protegidos pela LGPD). Nunca anexe arquivos reais em issues, pull requests ou fóruns. Para relatar um problema, substitua os dados por fictícios ou envie só as posições e os valores envolvidos, sem identificação de pessoas.
• Executável não assinado. Confira o SHA-256 (veja Download) ou compile a partir do código-fonte. O .exe também tem atestado de procedência; o executável Linux, por enquanto, só o SHA-256.
• Encontrou uma vulnerabilidade? Não publique detalhes em uma issue aberta: veja a política de segurança e use o relato privado do GitHub.

• Os layouts Sicoob (400 e 240) foram transcritos das planilhas oficiais do Sicoob e os layouts Santander (400 e 240), dos manuais oficiais do Santander; todos foram testados com arquivos sintéticos, mas ainda não foram conferidos com arquivos reais. O layout FEBRABAN também não foi testado com arquivos reais. Só o Sicredi foi validado com arquivos reais.
• Santander: os manuais têm pequenas inconsistências (por exemplo, o banco aparece como 33 no Header de Arquivo do CNAB240, e alguns campos declaram tamanho diferente das posições). O programa segue as posições; confira com um arquivo real do banco. Os manuais não trazem histórico de revisões e o site do Santander não permite download automático, então uma versão nova precisa ser conferida à mão.
• Sicoob 400, retorno: o CPF/CNPJ do pagador (posições 343–356) tem baixa confiança: a planilha oficial escreve 343–357, o que contradiz o tamanho de 14 posições declarado.
• Sicoob 240: a planilha oficial mais recente encontrada é de 2019 (publicada em 2021). As tabelas de motivos de ocorrência e rejeição vêm de fonte secundária (a planilha só cita alguns códigos e remete à tabela FEBRABAN), e o campo "Motivo da Ocorrência" do Segmento T aparece com o valor bruto. Os segmentos Y e W não são descritos pelo manual e aparecem como "Conteúdo do Registro (não mapeado neste layout)".
• CNAB400 cobre só o Detalhe obrigatório (tipo 1), exceto no layout Santander, que também descreve os registros opcionais 8 e 2, 4 a 7. Nos demais layouts, registros opcionais (mensagem, rateio, beneficiário final etc.) não são interpretados.
• Sicredi: a "Tabela de Motivos" do retorno não é decodificada (valor bruto).
• Campos de uso exclusivo do banco podem variar entre instituições: o valor bruto continua correto, mas o nome do campo pode não corresponder ao do seu banco. Nesse caso, compare com o manual do banco e abra uma issue.
• O programa lê um arquivo por vez e não valida regras de negócio (dígito verificador, soma do trailer etc.): ele interpreta, não audita.
• Linux: o executável é só para x86_64 e distros com glibc 2.28 ou mais nova. A interface usa X11 (em Wayland, pelo XWayland, que vem ligado por padrão no GNOME e no KDE). As fontes podem ficar um pouco diferentes das do Windows (a fonte Segoe UI não existe no Linux e o sistema usa outra parecida).

O CNABLens é open source (licença MIT) e aceita contribuição de qualquer pessoa: uma pergunta, um problema encontrado ou uma alteração no código. Contribuições são bem-vindas, principalmente:

• Conferir um layout com arquivo real (informe apenas o banco, o formato e as posições que não bateram, sem dados pessoais).
• Novos bancos e layouts (veja Adicionando um novo layout).
• Correções de rótulos e descrições, e melhorias na interface.

Nunca anexe arquivo CNAB real (nomes, CPF/CNPJ e valores de terceiros): use dados fictícios ou informe só as posições e os valores envolvidos.

1. Tenha uma issue. Comente em uma existente (as com good first issue são um bom começo) ou abra uma. Vale para toda alteração, até uma correção pequena de texto: o número da issue faz parte do nome da branch e do pull request.
2. Faça um fork e crie a branch a partir da develop (não da main), com o número da issue: feature/<n>-<slug> (ex.: feature/12-exportar-csv) ou bugfix/<n>-<slug> para correção de bug.
3. Programe com testes. Um assunto por pull request. Para bug, escreva primeiro o teste que falha. Rode python -m unittest discover -s tests -v antes de enviar.
4. Abra o pull request para a develop, preenchendo o modelo e escrevendo Refs #<n> na descrição (não Closes: a issue fecha sozinha quando a versão é publicada).
5. Espere o CI. Os checks check (compilação e testes) e regras (nome da branch, destino e referência à issue) precisam passar. Se falhar, corrija com novos commits na mesma branch.

O mantenedor revisa e responde. Você não mescla, aprova nem mexe em versão ou CHANGELOG.md: quando o PR é aprovado, a esteira o inclui na próxima release, gera uma versão de teste (rc) e, depois de testada, a publica. Seus commits mantêm a sua autoria no histórico, e a issue é fechada sozinha na publicação. Não há prazo garantido de resposta (projeto mantido em tempo parcial).

Regras que valem sempre: inclua testes; use dados fictícios; só biblioteca padrão do Python; textos em português do Brasil; cite a fonte oficial de qualquer posição nova ou alterada. O passo a passo detalhado está em CONTRIBUTING.md, o processo completo em docs/processo.md e a conduta esperada no Código de Conduta.

Distribuído sob a Licença MIT.

Aviso. Este é um projeto independente e não tem vínculo com nenhum banco, cooperativa ou com a FEBRABAN. Os nomes Sicoob, Sicredi, Itaú, Banco do Brasil e demais são marcas de seus respectivos titulares e aparecem apenas para identificar os layouts. O software é fornecido "como está", sem garantia. Confirme sempre valores e situação de títulos com o seu banco antes de tomar decisões financeiras.

As posições e descrições dos campos vêm da documentação técnica pública dos bancos (as descrições são resumos em português dos manuais):

Conferências cruzadas (sem cópia de código): projetos open source brcobranca, laravel-boleto e cnab-layouts; as tabelas de motivos do CNAB240 do Sicoob seguem a tabela FEBRABAN conforme o projeto ACBr. Os links acima foram acessados em ago/set de 2026 e podem mudar: o banco pode publicar versões mais novas.

O .exe empacota o interpretador Python (licença PSF), o Tcl/Tk (licença BSD) e é gerado com o PyInstaller (GPLv2 com exceção que permite distribuir o executável gerado sob a licença do seu próprio programa).