Desenvolvimento de Robô para Consulta de Pontos e Infrações em Cnh com Automação Web

O cliente busca um desenvolvedor experiente em automação web para criar um sistema robusto de reconsulta de CNH, pontos, infrações e processos administrativos em portais oficiais de trânsito.

O objetivo não é desenvolver apenas um script de cliques, mas uma solução confiável, modular, rastreável e preparada para processamento contínuo e em lote.

A entrada será uma base Excel contendo id interno, nome, cpf e número da cnh. O sistema deverá validar e normalizar os dados, controlar registros processados, evitar duplicidades, preservar o arquivo original e permitir retomada sem reiniciar todo o lote.

A arquitetura deverá permitir uso inicial em um determinado portal estadual e futura expansão para outros estados sem reconstrução do sistema.

Estrutura desejada:

Excel → Fila → Máquina de Estados → Adapter do Estado → Navegação → Parser → Validação → Regras → Evidências → JSON/Excel/PDF

Futuramente:

Motor Central → Adapter rj / sp / mg / demais estados

o sistema deverá consultar e estruturar, conforme disponibilidade do portal:

situação atual da cnh;
pontuação;
infrações pontuáveis e mandatórias;
suspensão;
cassação;
bloqueios;
processos administrativos;
status e fases dos processos.

Para infrações relevantes, principalmente dos últimos 12 meses, deverá identificar e abrir individualmente cada auto necessário, extraindo:

número do auto;
data e hora;
órgão;
placa;
proprietário;
responsável pelos pontos;
situação/status;
fase administrativa;
código e descrição;
local;
enquadramento;
natureza;
pontos;
vencimento;
valor e desconto;
processo relacionado.

Não será suficiente identificar apenas a quantidade de infrações. Cada auto deverá estar relacionado aos seus dados detalhados e à respectiva evidência.

As saídas deverão incluir:

JSON estruturado por consulta;
planilha Excel consolidada;
PDF de evidências;
logs;
histórico de erros e tentativas;
status de cada registro processado.

Robustez é requisito central. O sistema deverá possuir fila de processamento, checkpoints, máquina de estados e capacidade de retomada. Uma interrupção não poderá exigir reprocessamento completo.

Devem existir tratamentos específicos para:

http 502/504;
timeout;
indisponibilidade temporária;
sessão perdida;
falha do navegador;
cnh não cadastrada;
alteração de html/dom;
falha de parser;
carregamento parcial;
evidência incompleta.

Os eventos não poderão ser tratados genericamente. Uma CNH não cadastrada deve ser registrada como resposta válida e permitir avanço imediato. Já erros 502/504 deverão possuir política controlada de retry, sem loops infinitos ou bloqueio do lote.

Quando alguma validação do portal exigir intervenção, o sistema deverá preservar navegador, sessão, cookies e estado atual, permitindo continuidade posterior sem perda do processamento.

Performance também é importante. A solução deverá evitar sleeps fixos, recarregamentos excessivos, múltiplas inicializações do navegador e geração repetitiva de arquivos. Espera-se uso de esperas condicionais, leitura eficiente do DOM, reaproveitamento de sessão e processamento apenas do necessário.

O sistema deverá registrar métricas de execução, permitindo acompanhar tempo por cliente e identificar gargalos.

O desenvolvimento deverá utilizar Claude Code como ferramenta de apoio ao desenvolvimento, manutenção e tratamento estruturado de erros, em conjunto com Git, documentação técnica e testes automatizados.

Cada erro relevante corrigido deverá gerar:

identificação do problema;
causa raiz;
correção aplicada;
teste de regressão;
registro em documentação, como LEARNINGS.md.

As regras de negócio deverão permanecer separadas da lógica de navegação sempre que possível, evitando regras importantes hardcoded no sistema.

Também deverá ser simples adicionar novos estados, alterar seletores, atualizar parsers ou incluir novas regras sem comprometer o motor principal.

Entregáveis esperados:

código-fonte completo;
repositório Git;
documentação de instalação e execução;
configuração de ambiente;
arquitetura modular;
fila, checkpoints e retomada;
tratamento de erros;
logs;
testes automatizados e de regressão;
geração de Excel, json e pdf;
homologação com amostra real;
documentação para manutenção e inclusão de novos estados.

O profissional deverá informar experiência prática com Node.js/JavaScript ou TypeScript, Selenium ou Playwright, automação web, scraping estruturado, Excel, json, pdf, git, testes automatizados e claude code.

Será diferencial ter experiência com automação de portais públicos, processamento em lote, sistemas sujeitos a mudanças frequentes de DOM e mecanismos de retry/checkpoint.

O objetivo final é receber uma solução que possa operar continuamente, ser monitorada, corrigida e evoluir com segurança — e não apenas um script que funcione em uma demonstração inicial.