Endpoint de diagnóstico: monitorar instâncias WhatsApp sem SSH

São 3h da manhã, seu pager apita: "instância principal silenciosa há 4 horas". Você abre o laptop, tenta SSH na VPS, aguarda autenticação 2FA, conecta no Postgres, executa query manual, vê 0 mensagens nas últimas horas. Diagnóstico no escuro, dependendo de SSH e conhecimento ad-hoc do banco. Inviável em produção séria.

O endpoint de diagnóstico da ZAP-API resolve exatamente isso. Uma única chamada HTTP autenticada por token retorna snapshot completo da saúde da plataforma: alertas ativos, performance dos endpoints, thresholds atuais, recomendações de ação. Sem SSH, sem banco, sem dependência de quem implementou.

O endpoint

GET https://api.zap-api.tech/v1/diagnostics/agent-snapshot
Header: X-Diagnostic-Token: dt_xxxxxxxxxxxxxxxxxxxxxx

Resposta JSON:

{
  "timestamp": "2026-05-21T15:42:00Z",
  "silent_alerts": {
    "sent_last_7d": 3,
    "currently_silent": [
      { "instanceId": "inst_abc123", "lastActivityAt": "2026-05-20T08:11:00Z" }
    ]
  },
  "summary_endpoint": {
    "timings_ms": [142, 98, 124, 187, 156],
    "uses_index": true,
    "explain_plan": "Index Scan using idx_zap_message_log_created_direction...",
    "bucket_seconds": 3600
  },
  "thresholds_for_action": {
    "silent_alert_min_inbound_count": 5,
    "silent_alert_window_hours": 24,
    "rate_limit_429_per_5min": 10,
    "circuit_breaker_open_minutes": 5
  }
}

Os 3 blocos da resposta

• silent_alerts — alertas disparados nos últimos 7 dias e instâncias atualmente em silêncio anormal
• summary_endpoint — performance do endpoint de agregação (5 últimos timings em ms, plano de query, uso de índice)
• thresholds_for_action — limites configurados que disparam ações automatizadas

Token de menor privilégio

O X-Diagnostic-Token é diferente do seu token normal. Características:

• Só leitura — não permite criar/atualizar/deletar nada
• Escopo limitado — só o endpoint /v1/diagnostics/*
• Sem acesso a SSH/DB — operações de leitura via API REST somente
• Comparação timing-safe no servidor (resiste a timing attacks)
• Rotação fácil — gere novo, invalide antigo, sem afetar tokens normais

Como gerar

No painel: Configurações > API Tokens > Diagnostic Token > Generate. Você recebe o token uma vez (formato dt_xxxxxxxxx...) — copie e armazene.

Cron de monitoramento que abre issue automática

Use o snapshot a cada 5 minutos e dispare alerta no GitHub Issues quando algum threshold for ultrapassado:

// monitor-cron.ts
import axios from "axios";

const ZAP = axios.create({
  baseURL: "https://api.zap-api.tech/v1",
  headers: { "X-Diagnostic-Token": process.env.ZAP_DIAGNOSTIC_TOKEN! },
});

const GITHUB = axios.create({
  baseURL: "https://api.github.com",
  headers: { Authorization: `Bearer ${process.env.GH_TOKEN}` },
});

async function check() {
  const { data } = await ZAP.get("/diagnostics/agent-snapshot");

  const issues: string[] = [];

  // Regra 1: muitas instâncias silenciosas
  if (data.silent_alerts.currently_silent.length >= 3) {
    issues.push(`${data.silent_alerts.currently_silent.length} instâncias silenciosas`);
  }

  // Regra 2: latência do summary acima do esperado
  const p95 = data.summary_endpoint.timings_ms.sort((a,b) => a-b)[Math.floor(0.95 * 5)];
  if (p95 > 500) {
    issues.push(`Summary p95 = ${p95}ms (> 500ms)`);
  }

  // Regra 3: index não está sendo usado
  if (!data.summary_endpoint.uses_index) {
    issues.push(`Summary endpoint não está usando índice`);
  }

  if (issues.length > 0) {
    await GITHUB.post("/repos/seu-usuario/seu-projeto/issues", {
      title: `[ZAP-MONITOR] ${issues.length} alertas`,
      body: `${issues.join("\n- ")}\n\nSnapshot:\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\``,
      labels: ["monitoring", "auto"],
    });
  }
}

check().catch(console.error);

// Crontab: */5 * * * * node monitor-cron.js

Integração com Uptime Robot / Better Uptime

Configure um monitor HTTP que requer:

• URL: https://api.zap-api.tech/v1/diagnostics/agent-snapshot
• Header: X-Diagnostic-Token: dt_seu_token
• Status esperado: 200
• Timeout: 5s
• Frequência: 1-5 min

Você pode até validar conteúdo: "string contém deve incluir timestamp". Falha → SMS/email/Slack para o time.

Exporter Prometheus / Grafana

Para times com stack de observabilidade própria, faça pequeno adapter que converte o JSON em métricas Prometheus:

// prom-exporter.ts
import express from "express";
import axios from "axios";

const app = express();
const ZAP = axios.create({
  baseURL: "https://api.zap-api.tech/v1",
  headers: { "X-Diagnostic-Token": process.env.ZAP_DIAGNOSTIC_TOKEN! },
});

app.get("/metrics", async (req, res) => {
  const { data } = await ZAP.get("/diagnostics/agent-snapshot");
  const lines: string[] = [];

  lines.push(`# HELP zap_silent_alerts_7d Alertas silenciosos nos últimos 7d`);
  lines.push(`# TYPE zap_silent_alerts_7d gauge`);
  lines.push(`zap_silent_alerts_7d ${data.silent_alerts.sent_last_7d}`);

  lines.push(`# HELP zap_silent_currently Instâncias silenciosas agora`);
  lines.push(`# TYPE zap_silent_currently gauge`);
  lines.push(`zap_silent_currently ${data.silent_alerts.currently_silent.length}`);

  const timings = data.summary_endpoint.timings_ms;
  lines.push(`# HELP zap_summary_latency_ms Latência do endpoint summary`);
  lines.push(`# TYPE zap_summary_latency_ms histogram`);
  for (const t of timings) {
    lines.push(`zap_summary_latency_ms_bucket{le="${t}"} 1`);
  }

  res.set("Content-Type", "text/plain");
  res.send(lines.join("\n"));
});

app.listen(9100);

Configure scrape no Prometheus apontando para esse endpoint. Em seguida monte dashboard Grafana com gráficos das métricas.

Casos práticos

Caso 1: SaaS B2B com SLA 99,9%

Empresa precisa provar uptime para clientes corporativos. Monitor a cada 1 minuto bate o endpoint, registra latência em InfluxDB, gera relatório automatizado de SLA mensal. Quando alerta dispara, sistema também aciona PagerDuty (escala on-call). Time não precisa lembrar de checar nada — a infra avisa.

Caso 2: Time pequeno sem ops dedicado

Startup de 3 devs sem Sysadmin. Cron rodando no GitHub Actions a cada 10 min consulta o endpoint e abre issue automática. Dev de plantão lê issues toda manhã e age. Não precisa SSH, monitoring stack, ou pessoa 24/7.

Caso 3: Auditoria pré-deploy

Pipeline CI/CD bate o endpoint antes de aprovar deploy de produção. Se alguma instância está silenciosa ou latência está alta, deploy é bloqueado. Evita "deploy em cima de fogo" — não introduzir mudanças quando ambiente já está degradado.

FAQ

Como gero o token?

No painel: Configurações > API Tokens > Aba Diagnostic > Generate New. Token aparece uma vez no momento da criação — copie e armazene em vault. Para rotação, gere novo e invalide antigo (não afeta tokens normais de API).

Quanto tempo os dados ficam armazenados?

Snapshot é gerado em tempo real — não tem retenção. Para histórico, você precisa armazenar localmente após cada scrape. Recomendamos InfluxDB ou Postgres com TimescaleDB para séries temporais.

Qual a frequência ideal de chamada?

1-5 minutos. Mais frequente que isso é overkill (dados não mudam tão rápido). Menos frequente que 10 minutos arrisca não detectar incidente em janela aceitável. O endpoint é leve (latência típica 50-150ms) e não tem rate limit agressivo.

SSE/streaming vs polling?

Hoje só polling. Se você precisa de notificação em real-time (delta push), use webhooks específicos (instance.silent_alert, etc.) que entregam o evento no momento. O snapshot é para "estado atual completo", complementar.

Existe dashboard pronto?

Painel ZAP-API tem gráficos básicos em /super-admin/instances. Para algo mais elaborado, recomendamos integrar com Grafana via exporter Prometheus (mostrado acima). Em breve disponibilizamos dashboard Grafana pré-configurado para importar.

Próximo passo

Gere seu Diagnostic Token e monte o monitoramento em 30 minutos. Criar conta grátis e configure o endpoint no seu pipeline de observabilidade.