Arquitetura de Software e Integrações em soluções do DETRAN

Estilos arquiteturais e decisões em soluções do DETRAN

Em soluções do DETRAN, a arquitetura de software precisa equilibrar integração com múltiplos sistemas (internos e externos), alta disponibilidade, rastreabilidade de transações e evolução contínua sem interromper serviços digitais. As decisões arquiteturais mais comuns envolvem: organização em camadas, adoção (ou não) de microserviços, padrões de integração (APIs e mensageria), governança de contratos, idempotência, tratamento de erros e observabilidade.

Arquitetura em camadas (layered)

Arquitetura em camadas organiza o sistema separando responsabilidades. Em geral, usa-se: camada de apresentação (API/Controllers), camada de aplicação (casos de uso), camada de domínio (regras) e camada de infraestrutura (persistência, integrações, mensageria). O objetivo é reduzir acoplamento e facilitar testes, manutenção e evolução.

• Apresentação (API): validação básica de entrada, autenticação/autorização, roteamento para casos de uso.
• Aplicação: orquestra fluxos (ex.: “solicitar emissão de CRLV-e”), chama domínio e integrações.
• Domínio: regras de negócio (ex.: elegibilidade, validações de estado, cálculos).
• Infraestrutura: acesso a dados, chamadas HTTP a parceiros, publicação/consumo de mensagens, cache.

Decisão prática: em sistemas com muitas integrações, manter a camada de aplicação como “orquestradora” ajuda a centralizar fluxos e padronizar tratamento de erros e logs de auditoria.

Microserviços (conceitos e quando fazem sentido)

Microserviços são um estilo arquitetural em que o sistema é dividido em serviços pequenos, independentes e implantáveis separadamente, cada um com responsabilidade bem definida. O ganho esperado é autonomia de deploy e escalabilidade por serviço; o custo é aumento de complexidade operacional e de integração.

• Quando tende a ajudar: domínios bem separados (ex.: “Notificações”, “Pagamentos”, “Protocolo Digital”), necessidade de escalar partes específicas, equipes diferentes com ciclos de entrega distintos.
• Quando pode atrapalhar: equipe pequena, domínio muito acoplado, baixa maturidade em observabilidade e automação, integrações frágeis sem governança.
• Alternativa comum: monólito modular (mesma aplicação, módulos bem separados), evoluindo para microserviços apenas onde houver necessidade clara.

Decisão prática: em contexto de DETRAN, microserviços costumam surgir primeiro em capacidades transversais (ex.: autenticação, notificações, auditoria, consulta de status) e em integrações com parceiros que exigem escalabilidade e isolamento de falhas.

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

Integrações: APIs REST, mensageria, filas e eventos

APIs REST: contratos, recursos e boas práticas

APIs REST expõem recursos via HTTP, usando métodos (GET, POST, PUT, PATCH, DELETE) e códigos de status. Em integrações do DETRAN, REST é comum para consultas e comandos síncronos (ex.: consultar situação de veículo, iniciar solicitação de serviço).

Boas práticas de contrato:

• Recursos e URIs: modelar por substantivos (ex.: /veiculos/{placa}, /servicos, /solicitacoes/{id}).
• Semântica HTTP: GET não altera estado; POST cria/aciona; PUT substitui; PATCH altera parcialmente.
• Paginação e filtros: ?page=1&size=20, filtros explícitos (ex.: ?status=EM_ANALISE).
• Correlação: aceitar/retornar um X-Correlation-Id para rastrear a transação ponta a ponta.

Exemplo de contrato (trecho):

POST /api/v1/solicitacoes-crlve HTTP/1.1 200 OK (ou 202 Accepted para processamento assíncrono) Content-Type: application/json X-Correlation-Id: 8f2a... { "idempotencyKey": "a1b2c3", "cpf": "***", "placa": "ABC1D23", "canal": "PORTAL" } Resposta: { "solicitacaoId": "b7f1...", "status": "EM_PROCESSAMENTO" }

Versionamento de API

Versionamento é a estratégia para evoluir contratos sem quebrar consumidores. Em integrações governamentais, mudanças precisam ser previsíveis e compatíveis.

• Versionamento por URI: /api/v1, /api/v2. Simples e explícito.
• Compatibilidade retroativa: adicionar campos é geralmente seguro; remover/renomear campos quebra clientes.
• Política de depreciação: definir prazos e comunicar mudanças; manter v1 e v2 em paralelo quando necessário.

Passo a passo prático para evoluir um endpoint:

• 1) Identifique se a mudança é compatível (ex.: adicionar campo) ou incompatível (ex.: alterar significado, remover campo).
• 2) Para mudança incompatível, crie /v2 e mantenha /v1 ativo.
• 3) Publique documentação do contrato e exemplos de request/response.
• 4) Monitore uso por versão (métricas por rota) e planeje desligamento do legado.

Mensageria: filas, tópicos e eventos

Mensageria é integração assíncrona por troca de mensagens. Em vez de esperar a resposta imediata, o produtor publica uma mensagem e o consumidor processa quando possível. Isso reduz acoplamento temporal e melhora resiliência, especialmente quando há dependências externas instáveis.

• Fila (queue): cada mensagem é consumida por um único consumidor (ou grupo). Útil para processamento de tarefas (ex.: geração de documento, envio de notificação).
• Tópico/evento (pub/sub): múltiplos consumidores recebem o mesmo evento. Útil para disseminar mudanças de estado (ex.: “SolicitaçãoAprovada”).
• Comando vs evento: comando pede ação (“ProcessarSolicitacao”); evento informa que algo ocorreu (“SolicitacaoCriada”).

Padrões de integração comuns:

• Event-driven: serviços reagem a eventos de domínio.
• Outbox: grava a mudança de estado e o evento na mesma transação local; um publicador assíncrono envia ao broker, reduzindo risco de inconsistência.
• Retry com backoff: reprocessar mensagens com intervalos crescentes.
• DLQ (Dead Letter Queue): mensagens que falham repetidamente vão para uma fila de quarentena para análise.

Exemplo de evento (JSON):

{ "eventId": "e9c1...", "eventType": "SolicitacaoCrlveCriada", "occurredAt": "2026-01-16T10:30:00Z", "correlationId": "8f2a...", "payload": { "solicitacaoId": "b7f1...", "cpf": "***", "placa": "ABC1D23" } }

Idempotência e consistência em integrações

Idempotência: por que é essencial

Idempotência é a propriedade de executar a mesma operação múltiplas vezes e obter o mesmo resultado, sem efeitos colaterais duplicados. Em integrações com redes instáveis, timeouts e retries, é comum o cliente repetir requisições. Sem idempotência, pode haver duplicidade de solicitações, cobranças ou registros.

Onde aplicar:

• POST de criação (ex.: abrir solicitação): usar Idempotency-Key ou chave no corpo.
• Processamento assíncrono: consumidores de fila devem ser idempotentes (reentrega de mensagem é normal).

Passo a passo prático para idempotência em API:

• 1) Cliente gera uma Idempotency-Key única por intenção de operação.
• 2) Servidor armazena a chave associada ao resultado (ex.: solicitacaoId e status).
• 3) Se a mesma chave chegar novamente, o servidor retorna o mesmo resultado sem recriar.
• 4) Defina janela de retenção (ex.: 24h/72h) e política de limpeza.

Passo a passo prático para idempotência em consumidor de fila:

• 1) Inclua eventId único em cada mensagem/evento.
• 2) Antes de processar, verifique se eventId já foi aplicado (tabela de deduplicação).
• 3) Se já aplicado, confirme (ack) e não repita efeitos.
• 4) Se falhar, reprocessar com retry e enviar para DLQ após limite.

Tratamento de erros: contratos, status e resiliência

Padrão de resposta de erro em APIs

Padronizar erros facilita integração e suporte. Um formato consistente deve incluir: código interno, mensagem para o consumidor, detalhes opcionais e identificador de correlação.

HTTP/1.1 422 Unprocessable Entity Content-Type: application/json X-Correlation-Id: 8f2a... { "error": { "code": "VALIDACAO_DADOS", "message": "Dados inválidos para abertura da solicitação.", "details": [ { "field": "placa", "issue": "Formato inválido" } ] } }

• 400: requisição malformada.
• 401/403: falha de autenticação/autorização.
• 404: recurso inexistente.
• 409: conflito (ex.: solicitação já existente para mesma chave de negócio).
• 422: validação semântica.
• 429: limite de requisições.
• 5xx: falhas internas/indisponibilidade temporária.

Resiliência em integrações síncronas

Chamadas HTTP a sistemas internos/externos devem considerar falhas parciais: lentidão, indisponibilidade, respostas inconsistentes. Estratégias típicas:

• Timeouts: curtos e alinhados ao SLO do serviço chamado.
• Retries: apenas para erros transitórios; evitar retry em operações não idempotentes.
• Circuit breaker: interrompe chamadas quando o destino está falhando, protegendo o sistema.
• Fallback: resposta alternativa (ex.: retornar status “em processamento” e concluir via assíncrono).

Segurança conceitual em integrações: OAuth2 e JWT

Em integrações modernas, é comum usar OAuth2 para delegação de acesso e JWT como token portável. Conceitualmente:

• OAuth2: define como um cliente obtém um token para acessar uma API em nome de um usuário ou sistema.
• JWT: token assinado contendo claims (ex.: emissor, expiração, escopos/perfis). A API valida assinatura e regras de autorização.

Decisões práticas:

• Escopos/roles: mapear permissões por operação (ex.: solicitacoes:criar, solicitacoes:consultar).
• Expiração e renovação: tokens curtos reduzem risco; refresh token para sessões.
• Propagação de identidade: em cadeia de serviços, propagar claims necessários (mínimo privilégio) e sempre manter correlationId.

Observabilidade: logs, métricas e tracing

Logs estruturados e correlação

Logs estruturados (JSON) permitem busca e agregação. Para integrações, é essencial registrar: rota, status, tempo de resposta, sistema destino, erro normalizado e correlationId.

{ "timestamp": "2026-01-16T10:30:02Z", "level": "INFO", "service": "servico-solicitacoes", "operation": "POST /api/v1/solicitacoes-crlve", "correlationId": "8f2a...", "durationMs": 240, "result": "ACCEPTED" }

Passo a passo prático para padronizar logs:

• 1) Defina campos obrigatórios (timestamp, level, service, correlationId, operation, durationMs, errorCode).
• 2) Gere/propague X-Correlation-Id desde a borda (API Gateway) até filas e integrações.
• 3) Evite dados sensíveis; registre identificadores técnicos e mascaramento quando necessário.
• 4) Crie dashboards e alertas baseados em padrões de erro e latência.

Métricas e SLOs

Métricas quantificam saúde e desempenho. Para serviços digitais com integrações, foque em:

• Taxa de sucesso: % de 2xx/3xx vs 4xx/5xx por rota.
• Latência: p95/p99 por endpoint e por dependência externa.
• Fila: tamanho, tempo de espera, taxa de consumo, mensagens em DLQ.
• Disponibilidade: uptime e erro por janela (SLO).

Tracing distribuído

Tracing conecta uma requisição entre múltiplos serviços, mostrando onde o tempo foi gasto e onde ocorreu falha. Em integrações do DETRAN, tracing é especialmente útil quando há: API Gateway → serviço de orquestração → serviço de pagamentos → mensageria → serviço de emissão.

• TraceId/SpanId: identificadores para encadear chamadas.
• Propagação: headers de tracing em HTTP e metadados em mensagens.
• Uso prático: investigar aumento de latência e localizar dependência degradada.

Atividade prática: desenhar uma arquitetura de serviço digital com integrações

Enunciado

Desenhe a arquitetura de um serviço digital do DETRAN chamado Serviço de Solicitações, responsável por abrir e acompanhar solicitações (ex.: emissão de documento digital). O serviço deve integrar com sistemas internos (cadastro, validações) e externos (parceiros/órgãos), suportar processamento assíncrono e oferecer rastreabilidade ponta a ponta.

Requisitos mínimos

• Integrações síncronas: uma API interna de validação e uma API externa de consulta.
• Integrações assíncronas: fila de processamento e publicação de evento de mudança de status.
• Contratos de API: definir endpoints, payloads e códigos de resposta.
• Segurança (conceitual): OAuth2/JWT, escopos e expiração.
• Disponibilidade: definir requisito (ex.: 99,9%) e estratégia para degradação controlada.
• Observabilidade: logs estruturados, métricas e tracing com correlação.

Passo a passo para construir o desenho

• 1) Defina o fluxo principal: “cliente abre solicitação” → “validações” → “processamento” → “status atualizado”.
• 2) Escolha o estilo: camadas (monólito modular) ou microserviços (separar “Solicitações”, “Notificações”, “Emissão”). Justifique em 2–3 linhas.
• 3) Modele a borda: API Gateway/Load Balancer → Serviço de Solicitações (REST). Inclua autenticação e rate limit.
• 4) Desenhe integrações REST: setas para sistemas internos/externos. Para cada chamada, anote timeout e política de retry (sim/não).
• 5) Desenhe mensageria: fila “processar-solicitacao” e tópico “solicitacao-status”. Indique DLQ e retry.
• 6) Defina idempotência: onde entra a Idempotency-Key e como o consumidor deduplica por eventId.
• 7) Padronize erros: escolha formato de erro e mapeie 4 casos (400, 401/403, 409, 5xx).
• 8) Observabilidade: indique onde são gerados correlationId e traceId, e quais métricas serão coletadas (latência p95, taxa de erro, DLQ).
• 9) Disponibilidade: descreva comportamento em falha do parceiro externo (ex.: retornar 202 e finalizar via assíncrono; circuit breaker; fila para reprocesso).

Checklist de entrega (o que seu desenho deve conter)

• Componentes: Gateway, Serviço(s), Broker de mensagens, Consumidores, Sistemas internos/externos.
• Endpoints: pelo menos 2 (criar solicitação e consultar status) com versão /v1.
• Mensagens: 1 comando e 1 evento com campos eventId e correlationId.
• Segurança: token JWT, escopos e validação na borda.
• Resiliência: timeout, retry, DLQ, circuit breaker (onde aplicável).
• Observabilidade: logs estruturados + métricas + tracing distribuído.