Um escritório contábil confere todo mês os CT-e, os conhecimentos de transporte eletrônicos, dos clientes transportadores. Uma das fontes é o portal de uma grande operação logística. Hoje a conferência é à mão: baixar os XMLs, importar no sistema contábil e comparar os relatórios para ver se o total bate.
Esta prova de conceito automatiza a conferência. Ela compara o relatório do portal com os XMLs do mesmo período e responde, documento por documento, OK, DIVERGENTE ou NÃO CONFERIDO. Um conector somente leitura entra no portal, baixa o relatório e o lote de XMLs e já roda a conferência. Ele rodou no portal real.
Construí entre 30 de setembro e 20 de outubro de 2026, em 62 commits. Depois, a prova de conceito virou um piloto ponta a ponta, ainda em andamento: captura em três fontes, importação no sistema contábil e conferência dos três lados.
PC do escritório (Windows): agente local, sem servidor nem fila no meio. Python 3.13 num ambiente próprio, com o Chromium do Playwright, instalado por um script PowerShell com versões fixas e conferência do SHA-256 de cada download; rodar de novo não duplica nada. Painel de um botão (janela local). Tarefa no Agendador de Tarefas do Windows nas datas combinadas, que recupera a data perdida. Rodada de conferência (Python 3.13): leitores plugáveis (Excel binário e HTML, xlsx, CSV, PDF, XMLs em pasta ou zip) para o mesmo modelo de documento, e um comparador que devolve OK, DIVERGENTE ou NÃO CONFERIDO por documento, sempre com o motivo. Conector do portal: Playwright, só leitura. Atualizador com manifesto assinado. Cofre de credenciais: Gerenciador de Credenciais do Windows. Disco local: pasta de XMLs por rodada e cliente, resultado (resumo, CSV, JSON, XLSX), histórico e logs sem segredos; cadastro dos clientes só na máquina, nunca no repositório.
Serviços externos: portal logístico (relatório + lote de XMLs); sistema contábil, rodando em nuvem (piloto); e-mail do resultado via SMTP; hospedagem estática com o manifesto assinado e o pacote zip.
Equipe do escritório → painel de um botão: clique.
Painel de um botão → rodada de conferência: inicia a rodada.
Agendador de Tarefas → rodada de conferência: início agendado nas datas combinadas; recupera a data perdida se o PC estava desligado.
Rodada de conferência → cofre de credenciais: lê as senhas dos portais no Gerenciador de Credenciais do Windows; mensagens de erro citam só o nome do segredo, nunca o valor.
Rodada de conferência → conector do portal: dispara a captura.
Conector do portal → portal logístico: Playwright, só leitura; login, relatório, download do lote de XMLs, retentativa com modal travado, divisão do mês em semanas e quantidade baixada comparada com o contador da tela.
Conector do portal → pasta de XMLs: download dos XMLs numa pasta por rodada e cliente.
Rodada de conferência → pasta de XMLs: os leitores levam relatório e XMLs ao mesmo modelo de documento; o comparador confere documento por documento.
Rodada de conferência → resultado: 3 estados (OK, DIVERGENTE, NÃO CONFERIDO) gravados em resumo, CSV, JSON e XLSX, com código de saída 0, 1 ou 2.
Resultado → e-mail do resultado: SMTP, planilha anexa, sem XML.
Pasta de XMLs → sistema contábil: importação da pasta na mesma rodada (piloto).
Atualizador → hospedagem estática: HTTPS; antes de cada rodada baixa o manifesto assinado e o pacote zip; recusa o pacote se a assinatura ou o SHA-256 não batem.
Atualizador → rodada de conferência: troca só os arquivos do programa; volta à versão anterior se a nova não passar no teste rápido.
Três estados, com NÃO CONFERIDO para tudo o que não deu para verificar.
Alternativa descartada: Só OK ou DIVERGENTE.
Por quê: Para um contador, uma automação que diz OK sem ter conferido é pior que o processo manual. A primeira versão devolvia OK em pelo menos 4 situações erradas, entre elas captura vazia e CT-e com evento de cancelamento.
Conector somente leitura, que se recusa a clicar em botões que alteram o portal.
Alternativa descartada: Automação livre da tela, inclusive salvar o layout do relatório.
Por quê: É regra fixa do projeto: nos portais, só leitura e download.
Comparar a quantidade baixada com o contador da tela do portal e gerar o relatório de novo se não bater.
Alternativa descartada: Confiar no arquivo baixado.
Por quê: Numa execução o relatório veio com mais linhas do que CT-e válidos. Se a contagem segue diferente, o resultado é NÃO CONFERIDO.
CT-e de complemento numa categoria própria, com quantidade e soma.
Alternativa descartada: Misturar os complementos com as outras divergências.
Por quê: O filtro padrão do relatório não lista complementos. No mês inteiro, os CT-e a mais eram todos complementos; separados, a divergência fica explicada.
Rodar como agente local no computador do escritório.
Alternativa descartada: App na nuvem que recebe os arquivos por upload.
Por quê: A pasta de XMLs e o sistema contábil ficam na máquina do escritório, e um mês de XMLs pesa: 15 mil XMLs sintéticos mínimos já dão 5,9 MB zipados.