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:
- Sanitização com
\D:re.sub(r'\D', '', cnpj)oureplace(/\D/g, '')apaga as letras da raiz/ordem sem disparar exceção, gerando strings curtas ou colisões estranhas. - Tipagem numérica e planilhas: colunas
BIGINTno 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. - 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órios459e424, restos8e6e DV35), 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/cnpjrecebendo{"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 comCache-Control: no-storee ficam comaccess_log offno 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.