API REST


Base	`<base do serviço>/api/v1` — no workspace do Studio: `http://<slug>:<porta>/gateway-api/igrp-notification-service/api/v1`
OpenAPI	`/v3/api-docs` · Swagger UI em `/swagger-ui.html`
Autenticação	`Authorization: Bearer <jwt>` emitido pelo Access Management, exceto health/info, OpenAPI, Swagger e `/webhooks/**`
GraphQL	também disponível (consultas de notificações e templates)

Os clientes TypeScript e Java cobrem todos estes endpoints.

Permissões e aplicação

Cada endpoint exige uma permissão, lida das claims do token:

Permissão	Para quê
`igrp.notification.send`	Enviar, reenviar, anexar, cancelar lotes
`igrp.notification.read`	Consultar notificações, lotes, anexos, estatísticas
`igrp.notification.inbox`	Inbox do próprio utilizador
`igrp.notification.admin`	Templates, destinatários, grupos, recorrências, configuração, RGPD
`igrp.notification.manual_status`	Mudar à mão o estado de uma entrega OFFLINE

Os pedidos pertencem a uma aplicação. O serviço usa o claim application_code do token; sem ele, usa o applicationCode do pedido (query nas leituras, corpo nas escritas). Erros: 400 APPLICATION_CODE_REQUIRED, 403 APPLICATION_ACCESS_DENIED, 422 ACCESS_MANAGER_UNAVAILABLE.

Os envios (POST /notifications, bulk e CSV) são M2M: token client_credentials.

Notificações

EMAIL precisa de SMTP configurado

Para enviar por EMAIL, o provider SMTP tem de estar configurado no Notification Service (NOTIFICATION_PROVIDERS_EMAILSMTP_*: servidor, porta, credenciais e remetente). Sem ele, o envio é recusado com 422 CHANNEL_NOT_ENABLED e nenhum email sai — ver Configurar os canais › EMAIL (SMTP). O canal também tem de estar ativo nas Definições da aplicação.

Método	Endpoint	Permissão	Descrição
`POST`	`/notifications`	`send`	Enviar. Responde 202 com `id` e `deliveries`
`GET`	`/notifications`	`read`	Listar com filtros
`GET`	`/notifications/{id}`	`read`	Detalhe, entregas e conteúdo renderizado
`POST`	`/notifications/{id}/resend`	`send`	Reenviar (canais/destinatários opcionais)

Filtros da listagem: businessKey, category, priority, channel, status, batchId, recurrenceId, recipient, createdFrom, createdTo (ISO 8601), applicationCode, page, size, sort.

Corpo do envio

Campo	Descrição
`channelStrategy`	Obrigatório. `SPECIFIC`, `ALL` ou `PREFERRED`
`channels`	`EMAIL`, `SMS`, `WHATSAPP`, `PUSH`, `IN_APP`, `OFFLINE`
`recipients`	`[{ userId?, email?, phone?, pushToken? }]`
`groups`	`[{ groupId \| departmentCode \| roleCode \| permissionName }]` — resolvidos no envio
`template`	`{ code, locale? }` — template publicado
`inline`	`{ subject?, title?, body? }` — em vez de `template`
`variables`	Valores das variáveis do template
`priority`	`LOW`, `NORMAL`, `HIGH`, `URGENT`
`attachments`	`[{ filename, contentRef }]`
`idempotencyKey`	Evita envios duplicados
`businessKey`, `category`, `correlationId`	Rastreio e agrupamento
`locale`, `scheduledAt`, `expiresAt`	Opcionais
`callbackUrl`	HTTPS, num domínio registado nas definições da aplicação

Envios em massa e lotes

Método	Endpoint	Permissão	Descrição
`POST`	`/notifications/bulk`	`send`	Mesmo pedido para muitos destinatários → `batchId`
`POST`	`/notifications/bulk/csv`	`send`	Multipart: parte `request` (JSON) + parte `file` (CSV)
`GET`	`/batches/{batchId}`	`read`	Progresso do lote
`POST`	`/batches/{batchId}/cancel`	`send`	Cancelar as entregas ainda pendentes

Anexos

Método	Endpoint	Permissão	Descrição
`POST`	`/attachments`	`send`	Upload multipart (parte `file`) → `id`, `contentRef`, `filename`, `mimeType`, `sizeBytes`, `checksum`
`GET`	`/attachments/{id}`	`read`	Download

Inbox (IN_APP)

Token do utilizador (o userId sai do token). Permissão igrp.notification.inbox.

Método	Endpoint	Descrição
`GET`	`/inbox`	Listar. Filtros `unreadOnly`, `includeArchived`; página de 20 por omissão
`GET`	`/inbox/unread-count`	`{ "unreadCount": n }`
`POST`	`/inbox/{deliveryId}/read`	Marcar como lida
`POST`	`/inbox/read`	Marcar todas como lidas
`POST`	`/inbox/{deliveryId}/archive`	Arquivar

Templates

Todos exigem igrp.notification.admin.

Método	Endpoint	Descrição
`GET`	`/templates`	Listar. Filtros `code`, `channel`, `status`, `locale`
`POST`	`/templates`	Criar (rascunho)
`GET`	`/templates/{id}`	Obter
`PUT`	`/templates/{id}`	Atualizar
`POST`	`/templates/{id}/publish`	Publicar
`POST`	`/templates/{id}/archive`	Arquivar
`POST`	`/templates/{id}/preview`	Renderizar com variáveis de teste

Não há obtenção por código: para encontrar um template publicado, lista com code e status=PUBLISHED. Ver Templates.

Destinatários e grupos

Todos exigem igrp.notification.admin.

Método	Endpoint	Descrição
`GET`	`/recipients/{userId}`	Contactos e preferências de um utilizador
`PUT`	`/recipients/{userId}`	Criar ou atualizar
`PUT`	`/recipients/{userId}/preferences`	Canais preferidos (usados por `PREFERRED`)
`PUT`	`/recipients/{userId}/opt-outs`	Opt-outs por canal/categoria
`DELETE`	`/recipients/{userId}`	Remover
`GET`, `POST`	`/groups`	Listar, criar grupo
`GET`, `PUT`, `DELETE`	`/groups/{id}`	Obter, atualizar, remover

Recorrências

Método	Endpoint	Permissão	Descrição
`GET`, `POST`	`/recurrences`	`admin`	Listar, criar
`GET`, `DELETE`	`/recurrences/{id}`	`admin`	Obter, remover
`POST`	`/recurrences/{id}/pause`	`admin`	Pausar
`POST`	`/recurrences/{id}/resume`	`admin`	Retomar
`GET`	`/recurrences/{id}/executions`	`read`	Execuções

Entregas e estatísticas

Método	Endpoint	Permissão	Descrição
`POST`	`/deliveries/{id}/status`	`manual_status`	Mudar o estado de uma entrega OFFLINE
`GET`	`/stats/deliveries`	`read`	Contagens agrupadas: `groupBy` (obrigatório: `CHANNEL`, `STATUS`, `APPLICATION`), `from`, `to`, `allApplications`, `applicationCode`

Configuração e administração

Método	Endpoint	Permissão	Descrição
`GET`, `PUT`	`/settings`	`admin`	Definições da aplicação: canais, remetentes, quotas, domínios de callback, retenção
`POST`	`/admin/recipients/{userId}/forget`	`admin`	Anonimizar os contactos de um utilizador (RGPD)
`POST`	`/admin/retention/purge`	`admin`	Apagar dados fora do prazo de retenção

Webhooks dos providers

Sem /api/v1 e sem token (a autenticidade é validada por provider):

Método	Endpoint	Descrição
`POST`	`/webhooks/{providerId}`	Recibos de entrega e leitura enviados pelo provider
`GET`	`/webhooks/{providerId}`	Verificação do webhook (`hub.*`)

Exemplo: email com template

EMAIL precisa de SMTP configurado

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

Resposta 202 Accepted: a entrega é assíncrona. O estado de cada entrega consulta-se em GET /notifications/{id}.

Erros

Corpo de erro: { "code": "…", "message": "…" }.

HTTP	Códigos
400	`VALIDATION_ERROR`, `INVALID_REQUEST`, `APPLICATION_CODE_REQUIRED`
403	`APPLICATION_ACCESS_DENIED`, `ATTACHMENT_ACCESS_DENIED`, `MISSING_USER_ID`
404	`TEMPLATE_NOT_FOUND`, `NOTIFICATION_NOT_FOUND`, `RECIPIENT_NOT_FOUND`, `GROUP_NOT_FOUND`, `BATCH_NOT_FOUND`, `DELIVERY_NOT_FOUND`, `INBOX_ITEM_NOT_FOUND`, `ATTACHMENT_NOT_FOUND`, …
413	`ATTACHMENT_TOO_LARGE`
422	`TEMPLATE_ERROR`, `CHANNEL_NOT_ENABLED`, `CHANNEL_NOT_ALLOWED`, `CSV_INVALID`, `CALLBACK_DOMAIN_NOT_ALLOWED`, `SCHEDULING_NOT_SUPPORTED`, `INVALID_STATE_TRANSITION`, `ACCESS_MANAGER_UNAVAILABLE`
429	`QUOTA_EXCEEDED`

Estados de entrega (`DeliveryStatus`)

Estado	Descrição
`PENDING`	Aceite, à espera (ou agendada para `scheduledAt`)
`QUEUED`	Na fila de processamento
`SENDING`	Envio em curso
`SENT`	Aceite pelo provider
`DELIVERED`	Entrega confirmada (recibo do provider, IN_APP guardada, OFFLINE entregue à mão)
`READ`	Leitura confirmada (recibo de leitura, IN_APP aberta, marcação manual)
`FAILED`	Falha definitiva depois das tentativas
`CANCELLED`	Cancelada antes do envio
`EXPIRED`	`expiresAt` passou sem envio

API REST

Permissões e aplicaçãoCopy Anchor Link

NotificaçõesCopy Anchor Link

Corpo do envioCopy Anchor Link

Envios em massa e lotesCopy Anchor Link

AnexosCopy Anchor Link

Inbox (IN_APP)Copy Anchor Link

TemplatesCopy Anchor Link

Destinatários e gruposCopy Anchor Link

RecorrênciasCopy Anchor Link

Entregas e estatísticasCopy Anchor Link

Configuração e administraçãoCopy Anchor Link

Webhooks dos providersCopy Anchor Link

Exemplo: email com templateCopy Anchor Link

ErrosCopy Anchor Link

Estados de entrega (DeliveryStatus)Copy Anchor Link

On this page