Notifications

Endpoints da WebApiAlcance para o domínio de notificações internas - mensagens dirigidas a um usuário destinatário (usuario_id), usadas para avisar sobre falhas de automação, eventos de sistemas internos e outros avisos exibidos no sino de notificações do Hub. Cada notificação carrega uma origem (sistema) e uma severidade (tipo), e pode referenciar a atividade que a originou (activity_id).

Base path

/api/v1/notifications

Escopos necessários

• notifications:read - listagem e contagem de não lidas
• notifications:write - marcar como lida (uma ou todas) e criação

O escopo é derivado do prefixo público da rota: /notifications vira o recurso notifications (já sem hífen), e o método HTTP define a ação (read para GET, write para POST/PATCH).

Envelope de resposta

Toda resposta segue o envelope padrão da WebApi:

{
  "status": "success",
  "message": "Mensagem em PT-BR",
  "data": {}
}

Erros de regra de negócio (registro não encontrado, acesso negado) respondem { "message": "<mensagem>" } no status HTTP correspondente. Erros de validação do corpo da requisição (schema Pydantic - campo obrigatório ausente, sistema/tipo fora do vocabulário permitido etc.) seguem o formato padrão do FastAPI: { "detail": [...] }, sempre com 422 Unprocessable Entity.

Endpoints

GET /notifications/

Lista as notificações do usuário autenticado. Com all=true e perfil de acesso total (administrador ou diretoria), lista as de todos os usuários.

Parâmetros de query

Request

GET /api/v1/notifications/?sistema=certidao&unread_only=true&limit=20

Response 200 OK

{
  "status": "success",
  "message": "Notificações recuperadas com sucesso!",
  "data": [
    {
      "id": 981,
      "sistema": "certidao",
      "usuario_id": 42,
      "tipo": "error",
      "titulo": "Falha na automação de certidões",
      "mensagem": "Timeout ao consultar o portal da prefeitura de Salvador.",
      "link": "/certidoes/123",
      "activity_id": 15230,
      "lida": false,
      "lida_em": null,
      "created_at": "2026-08-15T13:42:00"
    }
  ]
}

data: [] (lista vazia) é um estado normal - não é erro. all=true sem acesso total responde 403 com { "message": "Acesso negado: listar todas exige acesso total." }.

Escopo: notifications:read

GET /notifications/unread-count

Contagem de notificações não lidas do usuário autenticado.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Response 200 OK

{
  "status": "success",
  "message": "Contagem de não-lidas recuperada com sucesso!",
  "data": {
    "unread": 3
  }
}

Escopo: notifications:read

POST /notifications/read-all

Marca todas as notificações do usuário autenticado como lidas.

Parâmetros

Este endpoint não recebe parâmetros de rota, query ou corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Notificações marcadas como lidas!",
  "data": {
    "updated": 12
  }
}

updated é a quantidade de notificações que estavam não lidas e passaram a lidas nesta chamada (pode ser 0).

Escopo: notifications:write

POST /notifications/

Cria uma notificação para um usuário destinatário. Rota de uso interno (geração automática a partir de falhas de automação e eventos de sistema).

Parâmetros

Sem parâmetros de rota ou query - o corpo é um NotificacaoCreate.

Request

{
  "sistema": "certidao",
  "usuario_id": 42,
  "tipo": "error",
  "titulo": "Falha na automação de certidões",
  "mensagem": "Timeout ao consultar o portal da prefeitura de Salvador.",
  "link": "/certidoes/123",
  "activity_id": 15230
}

Response 201 Created

{
  "status": "success",
  "message": "Notificação criada com sucesso!",
  "data": {
    "id": 982,
    "sistema": "certidao",
    "usuario_id": 42,
    "tipo": "error",
    "titulo": "Falha na automação de certidões",
    "mensagem": "Timeout ao consultar o portal da prefeitura de Salvador.",
    "link": "/certidoes/123",
    "activity_id": 15230,
    "lida": false,
    "lida_em": null,
    "created_at": "2026-08-17T10:05:00"
  }
}

Escopo: notifications:write + perfil administrador ou diretoria

PATCH /notifications/{notificacao_id}/read

Marca uma notificação como lida.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Notificação marcada como lida!",
  "data": {
    "id": 982,
    "sistema": "certidao",
    "usuario_id": 42,
    "tipo": "error",
    "titulo": "Falha na automação de certidões",
    "mensagem": "Timeout ao consultar o portal da prefeitura de Salvador.",
    "link": "/certidoes/123",
    "activity_id": 15230,
    "lida": true,
    "lida_em": "2026-08-17T10:12:00",
    "created_at": "2026-08-17T10:05:00"
  }
}

Só o dono da notificação (ou usuário com acesso total) pode marcá-la como lida. Para notificação inexistente ou de outro usuário sem acesso total, a resposta é igual: 404 Not Found com { "message": "Notificação não encontrada." } - a rota não confirma se a notificação existe quando não é sua.

Escopo: notifications:write

Schemas

NotificacaoCreate

Corpo de POST /notifications/.

NotificacaoRead

data retornado por todos os endpoints, exceto unread-count e read-all.

NotificacaoUnreadCount

data de GET /notifications/unread-count.

Notas

• Ordem de rotas (FastAPI): GET /unread-count e POST /read-all (prefixos estáticos) são declaradas antes de PATCH /{notificacao_id}/read (path dinâmico), para o match ocorrer na ordem correta.
• Datas (created_at, lida_em) são UTC sem timezone - diferente de outros domínios da casa que localizam em America/Sao_Paulo. Converta no cliente quando for exibir.
• sistema e tipo são validados apenas na criação; notificações antigas podem carregar valores legados de setores (histórico), mas isso não afeta a leitura.
• Excluir o usuário destinatário remove suas notificações (vínculo ON DELETE CASCADE); excluir a atividade de origem só desvincula (activity_id vira null), a notificação permanece.