Este documento descreve os endpoints disponíveis nas APIs que compõem o ecossistema de notificações utilizado no Portal do Cidadão.
As APIs estão organizadas da seguinte forma:
MAESTRO-API: responsável pela orquestração das notificações, gerenciamento de preferências e consulta das notificações.
PUSH-API: responsável pelo cadastro de dispositivos e envio de notificações push.
O MAESTRO-API utiliza a PUSH-API para realizar o envio de notificações web push quando o tipo de notificação configurado pelo usuário incluir esse canal.
A MAESTRO-API centraliza o processo de notificações, permitindo:
/NotificacoesFinalidade:
Cadastra uma nova notificação para um usuário.
Quando usar:
Quando um sistema precisar registrar uma notificação que será processada pelo MAESTRO-API.
Payload esperado (NotificacaoDto):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cpf | string | Sim | CPF do destinatário |
| titulo | string | Sim | Título da notificação |
| mensagem | string | Sim | Conteúdo da mensagem |
| link | string | Sim | URL para redirecionamento |
| sistemaId | UUID | Sim | Identificador do sistema origem |
| protocolo | string | Não | Protocolo de negócio |
| dataParaExecucao | datetime | Sim | Data/hora programada para envio |
| nome | string | Não | Nome do destinatário |
Resposta: 200 OK
/Notificacoes/{id}/Cpf/{cpf}Finalidade:
Consulta uma notificação específica de um usuário.
Quando usar:
Para obter detalhes de uma notificação pelo seu identificador.
Parâmetros:
id: identificador da notificação.cpf: CPF do destinatário.Respostas:
200 OK404 Not Found/Notificacoes/Cpf/{cpf}/SistemaId/{sistemaId}Finalidade:
Lista as notificações de um usuário em um sistema específico.
Parâmetros:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cpf | string | Sim | CPF do usuário |
| sistemaId | UUID | Sim | Sistema de origem |
| notificacoesLidas | boolean | Não | Inclui notificações já lidas |
Resposta: 200 OK
/Notificacoes/{id}/Cpf/{cpf}/MarcarComoLidaFinalidade:
Marca uma notificação como lida.
Quando usar:
Após o usuário visualizar a notificação.
Resposta:
200 OK400 Bad Request/Notificacoes/EnviarFinalidade:
Dispara o processamento das notificações pendentes.
Quando usar:
Normalmente utilizado por agendadores ou processos automatizados.
Resposta: 202 Accepted
Comportamento interno:
O MAESTRO-API:
/Notificacoes/Protocolo/{protocolo}/InativarFinalidade:
Inativa notificações vinculadas a um protocolo.
Quando usar:
Quando o processo de negócio for cancelado ou concluído.
Parâmetros:
protocolo: identificador do processo.Body:
sistemaId.Resposta: 200 OK
/Preferencias/Cpf/{cpf}Finalidade:
Consulta as preferências de notificação do usuário.
Quando usar:
Para verificar os canais habilitados.
Resposta:
200 OK404 Not Found/Preferencias/AtivarFinalidade:
Ativa um tipo de notificação para o usuário.
Payload (PreferenciaDto):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cpf | string | Sim | CPF do usuário |
| tipoDeNotificacao | enum | Sim | Tipo a ser ativado |
Resposta: 200 OK
/Preferencias/InativarFinalidade:
Desativa um tipo de notificação para o usuário.
Payload (PreferenciaDto):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cpf | string | Sim | CPF do usuário |
| tipoDeNotificacao | enum | Sim | Tipo a ser ativado |
Resposta: 200 OK
/TiposDeNotificacoesFinalidade:
Retorna a lista de tipos de notificação suportados.
Resposta: 200 OK
Enum TipoDeNotificacao:
| Valor | Descrição |
|---|---|
| 0 | Não definido |
| 1 | Push |
| 2 | |
| 3 | Push e E-mail |
O valor retornado neste endpoint é utilizado pelo MAESTRO-API para determinar quais APIs devem ser acionadas durante o envio.
A PUSH-API gerencia os dispositivos cadastrados e realiza o envio de notificações push utilizando o padrão Web Push com VAPID.
/Devices/subscribeFinalidade:
Registra um dispositivo do usuário para recebimento de notificações push.
Payload (PushSubscriptionDto):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cpf | string | Sim | CPF do usuário |
| endpoint | string | Sim | Endpoint do navegador |
| p256Dh | string | Sim | Chave pública da assinatura |
| auth | string | Sim | Token de autenticação |
Resposta: 200 OK
/Devices/unsubscribeFinalidade:
Remove o vínculo de um dispositivo.
Quando usar:
Quando o usuário desativar as notificações ou limpar o navegador.
Payload (PushSubscriptionDto):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cpf | string | Sim | CPF do usuário |
| endpoint | string | Sim | Endpoint do navegador |
| p256Dh | string | Sim | Chave pública da assinatura |
| auth | string | Sim | Token de autenticação |
Resposta: 200 OK
/Devices/{code}/cpfFinalidade:
Obtém o CPF associado a um dispositivo cadastrado.
Parâmetros:
code: identificador do dispositivo.Resposta: 200 OK
/Pushs/vapid-details/public-keyFinalidade:
Retorna a chave pública VAPID.
Quando usar:
Antes de chamar o subscribe no navegador.
Resposta:
200 OK/Pushs/sendFinalidade:
Envia notificações push para os dispositivos informados.
Payload (SendDto):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| delay | integer | Não | Tempo de atraso antes do envio |
| notificationDto | object | Sim | Dados da notificação |
| devices | array | Não | IDs dos dispositivos |
| Campo | Descrição |
|---|---|
| title | Título da notificação |
| body | Mensagem |
| icon | Ícone |
| image | Imagem |
| badge | Badge |
| tag | Identificador da notificação |
| timestamp | Data/hora |
| requireInteraction | Mantém visível até interação |
| actions | Botões de ação |
| data | Dados adicionais |
Resposta: 200 OK
Um sistema cliente chama POST /Notificacoes na MAESTRO-API.
A notificação é armazenada para processamento.
O endpoint POST /Notificacoes/Enviar é executado.
O MAESTRO-API consulta as preferências do usuário.
O MAESTRO-API identifica o TipoDeNotificacao.
Caso o tipo inclua Push (1 ou 3):
POST /Pushs/send.POST /Notificacoes
Content-Type: application/json
{
"cpf": "12345678901",
"titulo": "Solicitação Atualizada",
"mensagem": "Sua solicitação foi concluída.",
"link": "https://portaldocidadao.ro.gov.br/minhas-solicitacoes",
"sistemaId": "550e8400-e29b-41d4-a716-446655440000",
"protocolo": "PROC-2026-001",
"dataParaExecucao": "2026-05-20T14:00:00Z",
"nome": "João da Silva"
}
POST /Devices/subscribe
Content-Type: application/json
{
"cpf": "12345678901",
"endpoint": "https://fcm.googleapis.com/...",
"p256Dh": "...",
"auth": "..."
}
A MAESTRO-API utiliza os seguintes headers de segurança:
AuthorizationAccept-OriginEsses cabeçalhos devem ser enviados conforme a política de autenticação adotada no ambiente.
| API | Responsabilidade |
|---|---|
| MAESTRO-API | Orquestração, cadastro, consulta e processamento de notificações |
| PUSH-API | Gerenciamento de dispositivos e envio de notificações push |
| HERMES-API | Serviço de envio de e-mails |