← Documentação

Referência da API

Autenticação

Dois tipos de autenticação:

  • Ingestão pelo navegador — usa o seu site_key + Allowed origins. Não precisa de chave secreta (e no navegador não dá para mantê-la em segredo).
  • Ingestão pelo servidor + API pública de leitura — usa a secret_key do app via Authorization: Bearer <secret>. Rotacione pelo dashboard.

Ingestão — POST /v1/i

Base do endpoint: https://api.www.useanalisa.com/v1/i

POST /v1/i
Content-Type: application/json
Authorization: Bearer <secret_key>   # obrigatório no servidor; o navegador usa o site_key

{
  "site_key": "YOUR_SITE_KEY",
  "batch": [
    {
      "event": "page_view",
      "ts": 1715346000000,
      "url": "https://example.com/pricing",
      "path": "/pricing",
      "referrer": "https://google.com/",
      "anon_id": "anon_abc",
      "session_id": "sess_xyz",
      "user_id": "user_123",          // opcional
      "utm": { "source": "google", "medium": "cpc", "campaign": "launch" },
      "lang": "en-US",
      "tz": "America/Sao_Paulo",
      "viewport": { "w": 1920, "h": 1080 },
      "screen":   { "w": 1920, "h": 1080 },
      "props": {}
    }
  ]
}

Resposta 200: {"ok":true,"received":1}.

Códigos de erro comuns: 400 payload inválido, 401 não autorizado, 403 origin não permitida, 402 cota excedida, 413 payload grande demais.

API pública de leitura

Base: https://www.useanalisa.com/api/v1/public. Todos os endpoints exigem from e to (ISO 8601) e aceitam, opcionalmente, siteKey (precisa bater com a chave secreta) e limit. Autenticação via Authorization: Bearer <secret_key>.

As janelas têm limite: até 366 dias nos endpoints de relatório, até 7 dias em errors e snapshot (eles leem os eventos brutos para trazer dados frescos). Erros sempre voltam em JSON: {"error":"..."} com 400 (janela inválida), 401 (chave secreta inválida ou ausente), 403 (site pausado ou siteKey diferente), 429 (limite de requisições, veja Retry-After) ou 500.

GET /api/v1/public/overview

Retorna pageviews, unique_visitors, sessions e uma série temporal.

curl "https://www.useanalisa.com/api/v1/public/overview?siteKey=YOUR_KEY&from=2026-05-01&to=2026-05-08" \
  -H "Authorization: Bearer YOUR_SECRET"

GET /api/v1/public/top-pages

Páginas mais vistas por pageviews/visitantes únicos.

GET /api/v1/public/referrers

Principais origens de tráfego.

GET /api/v1/public/countries

Principais países.

GET /api/v1/public/errors

Grupos de erros de JavaScript vistos na janela (capturados automaticamente pelo SDK), dos mais frequentes para os menos. Só dados agregados: sem IPs, ids de usuário, ids de sessão ou stacks completas — apenas o frame do topo.

curl "https://www.useanalisa.com/api/v1/public/errors?from=2026-09-29T10:00:00Z&to=2026-09-29T11:00:00Z" \
  -H "Authorization: Bearer YOUR_SECRET"

{
  "from": "2026-09-29T10:00:00.000Z",
  "to": "2026-09-29T11:00:00.000Z",
  "errors": [
    {
      "fingerprint": "1x9k2",
      "type": "TypeError",
      "message": "x is undefined",
      "count": 2,
      "users_affected": 2,
      "first_seen": "2026-09-29T10:10:00Z",
      "last_seen": "2026-09-29T10:20:00Z",
      "handled": false,
      "kind": "onerror",
      "sample_path": "/checkout",
      "top_frame": "at pay (checkout.js:10:5)"
    }
  ]
}

GET /api/v1/public/snapshot

Tráfego, conversões (por meta) e Web Vitals p75 da janela, mais a mesma janela uma semana antes como baseline — mesmo dia da semana, para que a sazonalidade semanal não pareça uma queda. deltas são variações percentuais, null quando o baseline é zero. Cada vital traz a contagem de samples, para você poder ignorar um p75 calculado com poucos pageviews.

curl "https://www.useanalisa.com/api/v1/public/snapshot?from=2026-09-29T10:00:00Z&to=2026-09-29T11:00:00Z" \
  -H "Authorization: Bearer YOUR_SECRET"

{
  "current":  { "from": "...", "to": "...", "visitors": 5, "pageviews": 10, "sessions": 5,
                "conversions": 2, "goals": [{ "id": "...", "name": "Signup", "conversions": 2 }],
                "web_vitals": { "LCP": { "p75": 3250, "samples": 4 }, "INP": { "p75": null, "samples": 0 }, ... } },
  "baseline": { ...mesmo formato, 7 dias antes... },
  "deltas":   { "visitors": -50, "pageviews": -50, "conversions": -50 }
}

Endpoints de LGPD/GDPR

Veja LGPD/GDPR e privacidade para POST /api/gdpr/export e POST /api/gdpr/delete.

Limites de requisição

  • Ingestão: 100 KB por requisição, 1000 eventos por lote, sem limite fixo de requisições por segundo (limitamos IPs abusivos).
  • API pública de leitura: 120 requisições/minuto por site, por padrão (RATE_LIMIT_PUBLIC_READS se você hospedar por conta própria). 429 com Retry-After se passar do limite.
Referência da API · Analisa