API REST


Base	`<base do serviço>/api/v1` — no workspace do Studio: `http://<slug>:<porta>/gateway-api/igrp-notification-service/api/v1`
Referência	Gerada do OpenAPI do serviço (`/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.

Referência

Cada endpoint, com a permissão, os parâmetros, o corpo do pedido, as respostas e exemplos em várias linguagens, está na referência gerada a partir do OpenAPI do serviço:

Testar no playground

O botão Testar no playground envia o pedido a partir do browser para o servidor indicado (por omissão, o gateway do workspace em localhost:2575). Preenche o host do teu ambiente e um token em Autorização. O gateway tem de aceitar pedidos (CORS) vindos da origem da documentação; se não aceitar, usa os exemplos curl.

Corpo do envio

O corpo de POST /notifications (e dos envios em massa):

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

Exemplo: email com template

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.

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çãoCopiar link da secção

ReferênciaCopiar link da secção

Notificações e lotes

Anexos

Inbox

Templates

Destinatários e grupos

Recorrências

Entregas e estatísticas

Configuração e administração

Webhooks dos providers

Corpo do envioCopiar link da secção

Exemplo: email com templateCopiar link da secção

ErrosCopiar link da secção

Estados de entrega (DeliveryStatus)Copiar link da secção