Pular para conteúdo

CNHSync (Serviços & APIs)

O domínio CNHSync reúne duas frentes complementares: (1) os Windows Services que rodam 24/7 sincronizando coletas com os sistemas nacionais (Detran/SERPRO) e (2) os endpoints expostos pela R-Collector API para orquestrar lotes, reprocessamentos e auditorias. Juntos eles fecham o “last mile” do RCollector Pará.

Papel no Ecossistema

  • Transformar coletas aprovadas em envios conformes com as regras da Portaria 968/2022.
  • Garantir retentativas e visibilidade de cada tentativa (quem enviou, quando, código de retorno).
  • Processar cancelamentos e reaproveitamentos sem bloquear o fluxo principal.
  • Alimentar dashboards e relatórios oficiais consumidos pelo Detran-PA.

Componentes Principais

Camada Componentes Responsabilidade
Serviços Windows (.NET Framework 4.8) RCollectorCNHSync, RCollectorCNHDelete, utilitários RCollectorCNHSync.SERPRO.* Executam timers (6s para sync, 15s para monitoramentos, 3h para SERPRO), baixam arquivos do Blob, chamam CNH Sync/SERPRO e persistem transações.
APIs na R-Collector API POST /sync/batch, POST /sync/reprocessar/{id}, GET /sync/pendencias, webhooks internos Permitem ao backend criar lotes manuais, priorizar urgências, consultar pendências e publicar eventos para o portal web.
Repositórios/Domain RCollectorCNHSync.Domain, RCollectorCNHSync.Repository Entidades (Coleta, Transaction, CancelamentoColeta) e comandos SQL (Dapper).
Proxies RCollectorCNHSync.Proxy Clientes HTTP para Keycloak, CNH Sync API, Azure Blob Storage e SERPRO.

Fluxo Operacional Completo

  1. Detecção – SyncService consulta o banco local (ColetaRepository.GetAllNotTransactedAsync) e cria fila interna priorizando coletas novas, cancelamentos e reaproveitamentos.
  2. Preparação – baixa imagens/fingerprints do Azure Blob, recupera credenciais (workstationconfig) e gera payload assinável.
  3. Envio – SyncColetaProxy.TransactionImages chama o endpoint oficial do CNH Sync com multipart (dados + arquivos). Autenticação ocorre via Client Credentials no Keycloak (AuthenticationProxy).
  4. Registro – TransactionRepository persiste o protocolo, códigos como ASSINATURA_INVALIDA ou CNH_EM_EMISSAO e número de tentativas.
  5. Atualização de Status – coletas bem-sucedidas viram CONCLUIDO; falhas recebem FALHA, CRITICO ou REVISAO. A API central consome esses eventos para dashboards.
  6. Retentativas & Alertas – política padrão de 5 tentativas (5m → 15m → 30m → 1h → 3h). Após o limite, o item vira crítico e dispara alerta (Teams/Webhooks/Portal).
  7. Expurgo – com recibo confirmado, os serviços notificam a API para liberar o Serviço de Expurgo local.

Cancelamentos e Reaproveitamentos

  • RCollectorCNHDelete roda paralelo ao serviço principal, buscando solicitações de cancelamento, chamando o endpoint específico na CNH Sync API e atualizando status locais.
  • Utilitários RCollectorCNHSync.SERPRO e RCollectorCNHSync.SERPRO.Reaproveitamento consultam SERPRO a cada 3h para preencher dedos ausentes ou reaproveitar digitais aceitas, reduzindo idas ao posto.
  • A API expõe ações administrativas para o portal web aprovar ou reprovar solicitações (Reaproveitamento, Envio prioritário).

APIs Disponíveis

Endpoint Uso
POST /sync/batch Força criação de lote manual ou prioriza um posto específico.
POST /sync/reprocessar/{transactionId} Recoloca uma transação falha na fila de envio.
GET /sync/pendencias Lista itens aguardando protocolo/recibo, permitindo filtros por posto, RENACH ou status.
Webhooks internos (SyncCreated, SyncFailed, SyncCompleted) Atualizam dashboards (RCollector Web) e alimentam alertas no suporte.

Configuração e Operação

  • App.config/variáveis definem URLs (CNHSyncAPI, AuthProviderURL), credenciais (ClientID, ClientSecret), conexão SQL e acesso ao Azure Blob.
  • Serviços suportam execução como console para troubleshooting (RCollectorCNHSync.exe -console).
  • Logs vão para Event Viewer (Application) e para Application Insights (métricas SyncBatchesCreated, SyncFailures, ReceiptsPending).
  • Estados principais: PENDENTE, CONCLUIDO, FALHA, CRITICO, REVISAO. Códigos críticos monitorados incluem ASSINATURA_INVALIDA, CNH_EM_EMISSAO, CPF_CANDIDATO_CONDUTOR_INVALIDO, DIGITAL_INVALIDA, RETRATO_INVALIDO.

Troubleshooting Rápido

  • Tentativas não avançam → validar conectividade com Keycloak e CNH Sync, certificados TLS e hora do servidor (tokens expiram se houver drift >2 min).
  • Falhas recorrentes para um posto → revisar workstationconfig.bin, credenciais Azure e permissões do container; verificar se os arquivos ainda existem.
  • Cancelamentos travados → confirmar se RCollectorCNHDelete está rodando e se o endpoint remoto aceita cancelamento para o status atual.
  • Reaproveitamento não retorna dados → conferir conectividade VPN/SERPRO e agendamento (job roda a cada 3h).

Manter os serviços e APIs do CNHSync operando juntos assegura que todo pacote enviado do Pará chegue oficialmente ao Senatran e que qualquer exceção seja tratada rapidamente pelo time de suporte.