Endpoints de Notificações

Visão Geral

A API de Notificações fornece um sistema de notificações em tempo real para alertas, eventos do sistema, atualizações de assinatura e confirmações de pagamento.

Novo na v1.3.0

Sistema completo de notificações com filtragem por tipo e status de leitura, operações em massa e criação automática de notificações em eventos críticos.

Todos os endpoints requerem autenticação.

Authorization: Bearer <token>

---

Tipos de Notificação

Tipo	Descrição	Exemplos
ALERT	Avisos de qualidade da água, problemas de dispositivos	Oxigênio baixo, temperatura alta, dispositivo offline
SYSTEM	Manutenção e atualizações do sistema	Atualização do sistema, manutenção agendada
SUBSCRIPTION	Mudanças de plano e avisos de limites	Plano atualizado, limite se aproximando
PAYMENT	Notificações relacionadas a pagamentos	Pagamento bem-sucedido, pagamento falhou, fatura pronta

---

GET /notifications/

Listar notificações com filtragem opcional e paginação.

Requisição

GET /api/v1/notifications/?type={type}&unread_only={bool}&page={page}&page_size={size}
Authorization: Bearer <token>

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
type	enum	❌	-	Filtrar por tipo de notificação
unread_only	boolean	❌	false	Mostrar apenas notificações não lidas
page	integer	❌	1	Número da página
page_size	integer	❌	20	Itens por página (máx: 100)

Resposta 200 OK

{
  "notifications": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "user-uuid",
      "type": "ALERT",
      "title": "Alerta de Oxigênio Baixo",
      "message": "Nível de oxigênio dissolvido está abaixo de 4.0 mg/L no Viveiro VV-01",
      "data": {
        "pond_id": "pond-uuid",
        "pond_cod": "VV-01",
        "parameter": "dissolved_oxygen",
        "value": 3.2,
        "threshold": 4.0
      },
      "is_read": false,
      "created_at": "2026-02-19T10:30:00Z",
      "read_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 45,
    "total_pages": 3,
    "has_next": true,
    "has_previous": false
  }
}

---

PATCH /notifications/{notification_id}/read

Marcar uma notificação específica como lida.

Parâmetros de Caminho

Parâmetro	Tipo	Descrição
notification_id	UUID	ID da notificação

Requisição

PATCH /api/v1/notifications/{notification_id}/read
Authorization: Bearer <token>

Resposta 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_read": true,
  "read_at": "2026-02-19T11:00:00Z"
}

---

POST /notifications/mark-all-read

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

Requisição

POST /api/v1/notifications/mark-all-read
Authorization: Bearer <token>

Resposta 200 OK

{
  "message": "Todas as notificações foram marcadas como lidas",
  "updated_count": 12
}

---

Notificações Automáticas

O sistema cria automaticamente notificações para os seguintes eventos:

Alertas de Qualidade da Água

• Oxigênio dissolvido abaixo do limite (< 4.0 mg/L)
• Temperatura fora da faixa (< 26°C ou > 32°C)
• pH fora da faixa (< 7.5 ou > 8.5)
• Amônia acima do limite (> 0.1 mg/L)
• Nitrito acima do limite (> 0.1 mg/L)

Alertas de Dispositivos

• Dispositivo offline por mais de 10 minutos
• Falha de energia detectada
• Erros de comunicação

Eventos de Assinatura

• Assinatura criada ou atualizada
• Assinatura cancelada
• Aproximando-se dos limites de recursos (80% do máximo)
• Limite de recursos atingido

Eventos de Pagamento

• Pagamento bem-sucedido
• Pagamento falhou
• Fatura pronta
• Método de pagamento expirado

---

Exemplos de Uso

Obter Notificações de Alerta Não Lidas

async function getUnreadAlerts(token) {
  const response = await fetch(
    'https://api.aeraplus.com/v1/notifications/?type=ALERT&unread_only=true',
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  const data = await response.json();
  return data.notifications;
}

Marcar Notificação como Lida

async function markAsRead(notificationId, token) {
  const response = await fetch(
    `https://api.aeraplus.com/v1/notifications/${notificationId}/read`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  return response.json();
}

Polling de Notificações em Tempo Real

class NotificationPoller {
  constructor(token, interval = 30000) { // Poll a cada 30 segundos
    this.token = token;
    this.interval = interval;
    this.timer = null;
  }

  async checkNotifications() {
    const response = await fetch(
      'https://api.aeraplus.com/v1/notifications/?unread_only=true&page_size=10',
      {
        headers: {
          'Authorization': `Bearer ${this.token}`
        }
      }
    );

    const data = await response.json();

    // Mostrar badge de notificação
    const unreadCount = data.notifications.length;
    this.onUnreadCountChange(unreadCount);
  }

  start() {
    this.checkNotifications();
    this.timer = setInterval(() => {
      this.checkNotifications();
    }, this.interval);
  }

  stop() {
    if (this.timer) {
      clearInterval(this.timer);
      this.timer = null;
    }
  }

  onUnreadCountChange(count) {
    console.log(`Notificações não lidas: ${count}`);
  }
}

// Uso
const poller = new NotificationPoller(token);
poller.start();

Dica

Para aplicações em produção, considere usar WebSockets ou Server-Sent Events (SSE) para notificações em tempo real em vez de polling.

---

GET /notifications/unread/count

Obtém a contagem de notificações não lidas para o usuário autenticado.

Requisição

GET /api/v1/notifications/unread/count
Authorization: Bearer <token>

Resposta 200 OK

{
  "unread_count": 5,
  "by_type": {
    "ALERT": 3,
    "SYSTEM": 0,
    "SUBSCRIPTION": 1,
    "PAYMENT": 1
  }
}

Dica

Use este endpoint para exibir badges de notificação na sua interface. É leve e otimizado para polling frequente.