Visão geral

O iGRP Notification Service é o microserviço de notificações do iGRP 3.0. Cada aplicação do Access Management envia notificações por um SDK (TypeScript ou Java) ou pela API REST; o serviço trata de canais, templates, retentativas, auditoria e RGPD.

Para ligar uma aplicação, segue a página Envio — SDKs e API. Templates e definições geram-se na Notifications UI, a consola de administração.

Canais suportadosCopy Anchor Link

Todos os providers vêm desligados: cada canal só envia depois de configurado — ver Configurar os canais.

Modos de envioCopy Anchor Link

Envio de notificaçõesCopy Anchor Link

Antes do primeiro envio, confirma estes quatro pontos. Cada um, se faltar, faz o pedido falhar com um erro diferente:

Com os requisitos cumpridos, o envio é um pedido M2M:

curl -X POST "$NOTIFICATION_SERVICE_BASE_URL/api/v1/notifications" \
  -H "Authorization: Bearer $TOKEN_M2M" \
  -H "Content-Type: application/json" \
  -d '{
    "channelStrategy": "SPECIFIC",
    "channels": ["EMAIL"],
    "recipients": [{ "email": "utente@exemplo.cv" }],
    "template": { "code": "pedido-confirmacao", "locale": "pt-CV" },
    "variables": { "nome": "Maria Silva", "numeroPedido": "PED-2026-0456" },
    "businessKey": "PED-2026-0456",
    "idempotencyKey": "pedido-confirmacao-PED-2026-0456"
  }'

A resposta é 202 Accepted, com uma entrega por destinatário e canal. A entrega segue em segundo plano: acompanha o estado (QUEUED → SENT → DELIVERED) em Envios na consola ou em GET /api/v1/notifications/{id}.

ArquiteturaCopy Anchor Link

1. A aplicação chama POST /api/v1/notifications com um token M2M. O serviço valida o pedido (aplicação, canal ativo, template publicado), grava-o e responde 202 Accepted com uma entrega por destinatário e canal.
2. O Temporal entrega em segundo plano, com filas por prioridade e retentativas. Se o Temporal não responder, a entrega é feita na hora, dentro do pedido.
3. O provider do canal envia (SMTP, FCM, …). Os recibos de entrega e leitura voltam por /webhooks/{providerId} e atualizam o estado (SENT → DELIVERED → READ).
4. IN_APP não sai do serviço: a mensagem fica na inbox do utilizador, lida com o token dele.

O código segue hexagonal + DDD em 13 módulos Maven:

Um canal novo é um módulo provider-* novo, sem mexer no núcleo.

Configurar os canaisCopy Anchor Link

Um envio para um canal sem provider ativo é recusado logo na API com 422 CHANNEL_NOT_ENABLED. O canal tem de estar ligado no serviço (provider) e na aplicação (Definições › Canais permitidos).

EMAIL (SMTP)Copy Anchor Link

Sem SMTP configurado, nenhum email sai. Liga o provider com o servidor de correio do ambiente:

Para testes sem enviar emails reais, aponta o SMTP para um servidor de captura (por exemplo Mailpit).

Outros canaisCopy Anchor Link

ObservabilidadeCopy Anchor Link

• OpenAPI em /v3/api-docs · Swagger UI em /swagger-ui.html
• Logs estruturados (ECS JSON em produção — LOG_STRUCTURED_FORMAT=ecs)
• OpenTelemetry: tracing ligado por omissão, exportado para OTEL_EXPORTER_OTLP_ENDPOINT (desliga com TRACING_ENABLED=false)
• GraphQL em /graphql (desliga a introspection em produção com GRAPHQL_INTROSPECTION=false)

Variáveis de ambienteCopy Anchor Link

O serviço é distribuído como imagem e corre no cluster ou no Docker do workspace, ao lado dos outros serviços da plataforma. Configura-se por variáveis de ambiente.

Autenticação e Access ManagementCopy Anchor Link

No arranque o serviço regista no Access Management as suas permissões (igrp.notification.*).

Base de dados, Temporal e anexosCopy Anchor Link

Canais e templatesCopy Anchor Link

ObservabilidadeCopy Anchor Link