Pular para conteúdo

R-Collector API

A R-Collector API sustenta todo o backend do programa no Pará. Construída em ASP.NET Core 6 usando Clean Architecture, ela centraliza cadastros de postos, licenças de estações, fluxo de coletas e integrações externas.

Capas Arquiteturais

  • Presentation: Controllers REST + endpoints SOAP (SoapCore) para compatibilidade com sistemas legados.
  • Application: casos de uso, validações FluentValidation, handlers MediatR e publicação de Domain Events.
  • Infrastructure: SQL Server (EF Core + Dapper para consultas críticas), Azure Blob Storage, Redis para cache e fila interna.
  • Cross-cutting: Application Insights, autenticação via Keycloak (OpenID Connect), políticas de auditoria.

Contextos Principais

Contexto Entidades-chave Descrição
Cadastro Posto, Estacao, Operador, Licenca Configurações do posto, horários, dispositivos e permissões.
Coletas Coleta, Biometria, Documento, Evento Armazena estado de cada RENACH, justificativas, imagens e laudos.
Workflow Fila, Tarefa, Agendamento Controla retentativas, auditorias e integração com CNH Sync.
Auditoria Operacao, Match, Log Registra toda ação relevante com carimbo de data/hora, IP e usuário.

Endpoints Essenciais

Endpoint Função
POST /auth/login Obtém token de operador/serviço. Normalmente intermediado pelo Keycloak.
GET /postos/{id}/configuracao Distribui parâmetros para o Software Desktop e serviços locais.
POST /coletas Cria ou atualiza uma coleta com metadados iniciais.
POST /upload/start / finish Controla ciclo de transmissão dos pacotes.
POST /biometria/match Solicita validação ao Biometric Engine e registra laudos.
POST /expurgo/auditar Recebe comprovantes de deleção local.
GET /relatorios/status Fornece visão resumida para supervisores do Detran-PA.

Segurança

  • Keycloak concede tokens com escopos (read_coleta, write_coleta, match_face etc.).
  • Rate limiting por posto/estação evita abuso em cenários de erro.
  • Assinatura de payload: uploads exigem hash e assinatura enviados junto ao JSON.
  • Criptografia: campos sensíveis (CPF, RENACH) são cifrados em banco usando Always Encrypted.

Observabilidade

  • ColetaCreated, UploadCompleted, MatchRequested, SyncDispatched são eventos enviados ao Event Grid / Service Bus para integrações reativas.
  • Métricas chave: ColetasPorPosto, TempoMedioValidacao, FalhasPorServico.
  • Dashboard expõe status das filas, taxa de erro por endpoint e backlog por posto.

Ciclo de Vida de uma Coleta

  1. Criação (POST /coletas) com status EmCaptura.
  2. Upload altera para EmAnalise; API referencia arquivos no Blob.
  3. Validação biométrica define AguardandoSync ou Reprovada com motivo.
  4. Sincronização com CNH Sync muda para Finalizada e dispara expurgo.
  5. Eventos posteriores: reaproveitamento, cancelamento ou solicitações do órgão.

Ferramentas de Suporte

  • Swagger disponível em /docs (restrito por IP) para testes de integração.
  • Pacotes Postman versionados; incluem exemplos de payloads com máscaras.
  • Jobs de manutenção: limpam coletas órfãs, recalculam indicadores e atualizam caches.

Esta API é a espinha dorsal do RCollector no Pará; todas as demais páginas detalham componentes que dependem dela.