2

Fiz um depurador de CNPJ alfanumérico, Chave de Acesso (44 dígitos) e auditor de CSV em FastAPI + HTMX

Quem já começou a revisar sistemas legados para o CNPJ alfanumérico sabe que atualizar a função do dígito verificador é a parte mais fácil do trabalho. O que costuma quebrar em silêncio está ao redor dela:

  1. Sanitização com \D: re.sub(r'\D', '', cnpj) ou replace(/\D/g, '') apaga as letras da raiz/ordem sem disparar exceção, gerando strings curtas ou colisões estranhas.
  2. Tipagem numérica e planilhas: colunas BIGINT no banco e leituras padrão de CSV no Pandas/Excel que engolem zeros à esquerda ou falham na inferência de tipo quando a primeira linha alfanumérica aparece no meio do arquivo.
  3. Chave de Acesso de 44 posições (NF-e / CT-e): o CNPJ ocupa da posição 7 à 20 da chave. Mesmo quem já atualizou o cadastro de clientes às vezes esquece que o DV da posição 44 também muda quando entra caractere alfanumérico (conforme a Nota Técnica 2025.001).

Para testar esses cenários sem depender de planilhas soltas ou geradores genéricos que só devolvem true/false, coloquei no ar uma ferramenta focada em QA e depuração:

Link: https://rdg-code.duckdns.org/

O que tem lá

  • Depurador passo a passo do DV (módulo 11): mostra caractere por caractere o valor ASCII, a conversão (ASCII - 48), o peso (2 a 9 da direita para a esquerda), o produto, o somatório e o resto. O cálculo foi conferido contra o exemplo oficial publicado pelo SERPRO (12.ABC.345/01DE-35, com somatórios 459 e 424, restos 8 e 6 e DV 35), com flag opcional para testar cenários com restrição de letras (I, O, U, Q, F).
  • Validador de Chave de Acesso (44 posições): quebra a chave nos campos fiscais e valida o DV da posição 44 com suporte a CNPJ alfanumérico.
  • Auditor de CSV/TXT: recebe um arquivo de até 2 MB e aponta linhas inválidas, problemas de formatação e sinais clássicos de truncamento (como perda de zeros à esquerda).
  • API simples para teste rápido: POST /api/v1/validate/cnpj recebendo {"cnpj": "12.ABC.345/01DE-35"} e devolvendo o passo a passo completo em JSON.
  • 4 guias curtos de referência: foco em Python puro, Pydantic/FastAPI, geração de massa de dados no Pytest e pontos de atenção na migração com Pandas e SQL.

Arquitetura e privacidade

A stack é propositalmente enxuta: FastAPI, Jinja2 e HTMX servido localmente (sem dependência de CDN externa), rodando atrás de Nginx e Gunicorn.

Como ninguém deveria subir base real de clientes em ferramenta de terceiros sem saber o que acontece com o arquivo, tomei três cuidados básicos:

  • Não há banco de dados nem escrita em disco para os uploads; o CSV é auditado em memória e descartado ao fim da requisição.
  • As rotas de validação (/run/* e /api/*) respondem com Cache-Control: no-store e ficam com access_log off no Nginx.
  • Mesmo assim, a recomendação óbvia para QA continua valendo: use massa de dados sintética ou anonimizada.

O projeto está em um domínio temporário (duckdns.org) justamente para validar se esse formato de depurador e auditor ajuda no dia a dia de quem está tocando essa migração.

Se puderem testar com casos de borda ou apontar o que está dando mais dor de cabeça na stack de vocês (ERPs legados, integração fiscal, bibliotecas antigas de validação), o feedback nos comentários ajuda bastante a decidir os próximos passos.

Carregando publicação patrocinada...
1

Mais um lugar que quebra em silêncio e nem chega ao backend: o formulário. Campo com type="number", inputmode="numeric" ou máscara no formato 99.999.999/9999-99 simplesmente não deixa digitar a letra, e no celular o teclado numérico nem mostra letras. A pessoa com CNPJ novo trava antes da sua validação rodar.

Dois outros que vejo pouco comentados: normalizar para maiúsculas antes do DV (o cálculo usa o código ASCII, então a e A dão valores diferentes: 49 contra 17) e revisar ordenação e índices no banco, porque ordem de texto não é a ordem numérica que alguns relatórios assumiam.

Talvez valha o auditor de CSV também apontar linhas com letra minúscula na raiz ou na ordem.