Pular para o conteúdo principal

Sistema de Notificações

Notificação de Teste - /api/notifications/test​

  • Endpoint: /api/notifications/test

  • Método: POST

  • Descrição: Enviar notificações de teste (simples, baseadas em modelo ou e-mail) para verificar a configuração de notificações.

  • Autenticação: Requer sessão de administrador e token CSRF

  • Corpo da Solicitação: Para teste simples:

    {
      "type": "simple",
      "ntfyConfig": {
        "url": "https://ntfy.sh",
        "topic": "test-topic",
        "accessToken": "optional-access-token"
      }
    }

Para teste de modelo:

{
  "type": "template",
  "ntfyConfig": {
    "url": "https://ntfy.sh",
    "topic": "test-topic",
    "accessToken": "optional-access-token"
  },
  "template": {
    "title": "Test Title",
    "message": "Test message with {variable}",
    "priority": "default",
    "tags": "test"
  }
}

Para teste de e-mail:

{
  "type": "email"
}

  • Resposta: Para teste simples:

    {
      "message": "Test notification sent successfully"
    }

Para teste de modelo:

{
  "success": true,
  "message": "Test notifications sent successfully via NTFY and Email",
  "channels": ["NTFY", "Email"]
}

Para teste de e-mail:

{
  "message": "Test email sent successfully"
}

O conteúdo do e-mail de teste exibe:

  • Nome do servidor SMTP e porta
  • Tipo de conexão (SMTP Simples, STARTTLS ou SSL/TLS Direto)
  • Status de requisito de autenticação SMTP
  • Nome de usuário SMTP (mostrado apenas quando a autenticação é necessária)
  • E-mail do destinatário
  • Endereço de origem e nome do remetente usado para o e-mail
  • Timestamp do teste
  • Respostas de Erro:
    • 401: Não autorizado - Sessão inválida ou token CSRF inválido
    • 400: Configuração do NTFY é necessária, configuração inválida ou e-mail não configurado
    • 500: Falha ao enviar notificação de teste com detalhes do erro
  • Notas:
    • Suporta mensagens de teste simples, notificações baseadas em modelo e testes de e-mail
    • Testes de modelo usam dados de amostra para substituir variáveis de modelo
    • Inclui timestamp na mensagem de teste
    • Testes do NTFY usam a configuração do NTFY armazenada; uma URL do NTFY fornecida pelo cliente não é usada
    • Usa campo accessToken para autenticação quando armazenado
    • Para testes de modelo, envia notificações para NTFY e e-mail (se configurado)
    • Testes de e-mail requerem que a configuração SMTP seja definida
    • O endpoint de e-mail de teste limpa o cache de solicitação antes de ler a configuração SMTP, garantindo que scripts externos possam atualizar a configuração e tê-la imediatamente refletida em e-mails de teste
    • Testes de modelo e envio imediato de Resumo Diário contornam a supressão por backup

Visualização de Modelo de Notificação - /api/notifications/preview​

  • Endpoint: /api/notifications/preview
  • Método: POST
  • Descrição: Renderiza um modelo de notificação com o renderizador Markdown de produção sem enviar. O corpo inclui kind (success, warning, overdueBackup ou dailySummaryEmail) e o modelo sendo editado. Visualizações de Resumo Diário usam o snapshot real atual; outros tipos usam valores de amostra determinísticos. E-mail HTML é destinado a um iframe em sandbox. Sucesso, Aviso/Erro e Atrasado também retornam o payload do NTFY (ntfyMessage); qualquer cabeçalho de tabela GFM é omitido e linhas de corpo são texto simples.
  • Autenticação: Requer sessão válida e token CSRF

Verificar Backups Atrasados - /api/notifications/check-overdue​

  • Endpoint: /api/notifications/check-overdue

  • Método: POST

  • Descrição: Dispara manualmente a verificação de backup atrasado e envia notificações.

  • Autenticação: Requer sessão válida e token CSRF

  • Resposta:

    {
      "message": "Overdue backup check completed",
      "statistics": {
        "totalBackupConfigs": 5,
        "checkedBackups": 5,
        "overdueBackupsFound": 2,
        "notificationsSent": 2
      }
    }

  • Respostas de Erro:

    • 500: Falha ao verificar backups atrasados

  • Notas:

    • Aciona manualmente a verificação de backups atrasados
    • Retorna estatísticas sobre o processo de verificação
    • Envia notificações para backups atrasados encontrados

Alertas do Canal de Notificação - /api/notification-channel-alerts​

  • Endpoint: /api/notification-channel-alerts

  • Método: GET, POST

  • Descrição: Lista as falhas de entrega de e-mail e NTFY em aberto para o administrador conectado, ou limpa os canais listados até que uma nova falha seja registrada.

  • Autenticação: Requer uma sessão de administrador. O POST também requer um token CSRF no cabeçalho X-CSRF-Token.

  • Corpo da Requisição (POST):

    {
      "channels": ["email", "ntfy"]
    }

channels deve conter um ou ambos: email e ntfy.

  • Resposta:

    {
      "alerts": [
        {
          "channel": "email",
          "error": "SMTP authentication failed",
          "latestTimestamp": "2026-09-23 22:10:00",
          "failureCount": 3,
          "settingsTab": "email",
          "host": "smtp.gmail.com"
        }
      ]
    }

Cada alerta inclui channel, error (no máximo 500 caracteres), latestTimestamp, failureCount e settingsTab (email ou ntfy). Alertas de e-mail podem incluir host. Alertas do NTFY podem incluir topic.

  • Respostas de Erro:
    • 400 INVALID_CONFIGURATION: O corpo do POST está ausente, ou channels está vazio ou contém um valor desconhecido
    • 500 INTERNAL_ERROR: Falha na Leitura ou ao Limpar os alertas
  • Observações:
    • O GET retorna os canais que ainda estão com falha para este administrador
    • O POST registra uma limpeza por administrador para cada canal listado que esteja atualmente aberto e, em seguida, retorna os alertas restantes
    • Uma falha posterior mostra o canal novamente, mesmo quando o texto do erro permanece inalterado
    • Uma entrega bem-sucedida posterior para esse canal o mantém oculto
    • O marcador de limpeza é armazenado na configuração e não inclui segredos

Limpar Timestamps de Backups Atrasados - /api/notifications/clear-overdue-timestamps​

  • Endpoint: /api/notifications/clear-overdue-timestamps

  • Método: POST

  • Descrição: Limpa todos os timestamps de notificação de backup atrasado, permitindo que as notificações sejam enviadas novamente.

  • Autenticação: Requer sessão válida e token CSRF

  • Resposta:

    {
      "message": "Overdue backup notification timestamps cleared successfully"
    }

  • Respostas de Erro:

    • 500: Falha ao limpar os carimbos de data/hora dos backups atrasados

  • Notas:

    • Limpa todos os carimbos de data/hora das notificações de backups atrasados
    • Permite que as notificações sejam enviadas novamente
    • Útil para testar o sistema de notificações