Visão Geral da API

Pro Plano

A API do Zenovay oferece acesso programático aos seus dados de analytics. Crie integrações personalizadas, automatize fluxos de trabalho e amplie as capacidades do Zenovay.

O Que Você Pode Fazer

API Externa (Autenticação por Chave de API)

Capacidade	Endpoint
Visão geral do analytics	GET /api/external/v1/analytics/:websiteId
Dados de visitantes	GET /api/external/v1/analytics/:websiteId/visitors
Analytics de páginas	GET /api/external/v1/analytics/:websiteId/pages
Dados por país	GET /api/external/v1/analytics/:websiteId/countries
Detalhamento por tecnologia	GET /api/external/v1/analytics/:websiteId/technology
Listar sites	GET /api/external/v1/websites
Detalhes do site	GET /api/external/v1/websites/:websiteId
Uso da API	GET /api/external/v1/usage
Páginas de heatmap	GET /api/external/v1/heatmaps/:websiteId/pages
Gravações de sessão	GET /api/external/v1/replays/:websiteId/sessions
Grupos de erros	GET /api/external/v1/errors/:websiteId/groups

Rastreamento (Público)

Estes endpoints são usados pelo script de rastreamento — nenhuma chave de API necessária.

Capacidade	Endpoint
Rastrear pageview/evento	POST /e/:trackingCode
Contagem de visitantes ao vivo	GET /e/live/:trackingCode
Heartbeat	POST /e/heartbeat/:trackingCode

Acesso à API por Plano

A API REST é um recurso pago. Os espaços de trabalho gratuitos não podem criar ou usar chaves de API — os endpoints de rastreamento não autenticados acima permanecem disponíveis em todos os planos.

Plano	Acesso à API	Requisições/Minuto	Limite Mensal
Free	Não disponível	—	—
Pro	Completo	30	10.000
Scale	Completo	60	100.000
Enterprise	Completo	120	1.000.000

URL Base

A URL base da API Externa é:

https://api.zenovay.com/api/external/v1

Autenticação

Chaves de API

Autentique-se com chaves de API usando o header X-API-Key ou Authorization: Bearer:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Ou usando autenticação Bearer:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

As chaves de API sempre começam com o prefixo zv_.

Obtendo Sua Chave de API

Acesse Configurações → Segurança e abra a seção Chaves de API
Clique em "Criar Chave de API"
Nomeie sua chave
Defina seu escopo (todos os sites ou um site único)
Copie a chave (exibida apenas uma vez)

As chaves de API requerem um plano Pro ou superior. Em um plano gratuito, o botão de criação está desabilitado.

Veja Autenticação para detalhes.

Início Rápido

Listar Seus Sites

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Obter Resumo do Analytics

Os endpoints de analytics requerem uma ID do site (um UUID — copie-a da resposta "Listar Seus Sites" acima) e um range opcional (um de 24h, 7d, 30d, 90d, 1y):

curl "https://api.zenovay.com/api/external/v1/analytics/YOUR_WEBSITE_ID?range=30d" \
  -H "X-API-Key: zv_YOUR_API_KEY"

Verificar Uso da API

curl https://api.zenovay.com/api/external/v1/usage \
  -H "X-API-Key: zv_YOUR_API_KEY"

Formato da Requisição

Headers

Header obrigatório (use uma das formas):

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Envie Content-Type: application/json em requisições POST que contenham um corpo JSON.

Header opcional:

X-Request-ID: your-unique-id (devolvido para depuração)

Parâmetros de Query

Parâmetros comuns nos endpoints de analytics:

Parâmetro	Descrição	Exemplo
range	Janela de tempo: `24h`, `7d`, `30d`, `90d`, `1y` (padrão `7d`)	?range=30d
limit	Máx linhas para retornar	?limit=50
offset	Linhas a pular (para paginação)	?offset=100

Formato da Resposta

Resposta de Sucesso

As respostas bem-sucedidas são envolvidas em um envelope success/data:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-06-13T00:00:00.000Z"
}

A forma do objeto data depende do endpoint (por exemplo, a visão geral de analytics retorna website, summary e daily_stats). Os endpoints que paginam seus resultados incluem um objeto pagination dentro de data.

Resposta de Erro

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded (30 requests/minute). Try again in 12 seconds",
    "code": "RATE_LIMIT_EXCEEDED",
    "timestamp": "2026-06-13T00:00:00.000Z"
  }
}

Códigos de Status HTTP

Código	Significado
200	Sucesso
201	Criado
400	Requisição inválida
401	Não autorizado
403	Proibido
404	Não encontrado
429	Rate limitado
500	Erro no servidor

Bibliotecas Cliente

O Zenovay não possui pacotes SDK oficiais. Em vez disso, use o script de rastreamento CDN para rastreamento no navegador e requisições HTTP padrão (fetch, requests, curl, etc.) para acesso à API do lado do servidor.

JavaScript (Navegador)

Adicione o script de rastreamento ao seu HTML:

<script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>

Em seguida, use a função global zenovay:

// Rastrear eventos
zenovay('track', 'signup', { plan: 'pro' });

JavaScript (Lado do Servidor)

Use fetch para chamar a API Externa diretamente:

const response = await fetch('https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID', {
  headers: {
    'X-API-Key': 'zv_YOUR_API_KEY',
  },
});
const data = await response.json();

Python (usando requests)

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID',
    headers={'X-API-Key': 'zv_YOUR_API_KEY'}
)
data = response.json()

Casos de Uso Comuns

Dashboards Personalizados

Crie dashboards internos:

Obtenha métricas agregadas
Crie visualizações personalizadas
Combine com outros dados

Relatórios Automatizados

Gere relatórios personalizados:

Relatórios semanais para stakeholders
Alertas em tempo real
Monitoramento de limites

Integração com CRM

Conecte ao seu CRM:

Envie dados de visitantes
Atualize registros de contatos
Acione fluxos de trabalho

Limites de Taxa

Os limites de taxa da API Externa são por chave de API, por minuto, e dependem do plano da equipe a que a chave pertence:

Plano	Requisições/Minuto	Limite Mensal
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

Headers de Rate Limit

As respostas incluem headers de uso e rate limit:

X-RateLimit-Limit: 30
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2026-07-01T00:00:00.000Z

X-RateLimit-Remaining está incluído quando disponível. Quando você excede um limite, a API retorna 429 com um header Retry-After.

Veja Limites de Taxa para melhores práticas.

Melhores Práticas

Requisições Eficientes

Solicite apenas os campos necessários
Use filtros de data
Pagine resultados grandes
Use cache quando possível

Tratamento de Erros

Implemente retries
Trate rate limits
Registre erros
Monitore taxas de sucesso

Segurança

Mantenha as chaves em segredo
Use permissões mínimas
Rotacione as chaves regularmente
Audite o uso das chaves

Testes

Não existe sandbox separada — teste em produção com uma chave dedicada:

Acesse Configurações → Segurança e abra a seção Chaves de API
Crie uma chave e dê a ela um nome reconhecível (p. ex. "Test")
Escope-a para um único site de teste se possível
Use a URL padrão da API: https://api.zenovay.com/api/external/v1/
Delete a chave quando terminar