Referência completa de todos os endpoints da API REST do Zenovay. Para começar, veja Visão Geral da API.
Uma especificação OpenAPI legível por máquina é publicada em https://api.zenovay.com/api/external/v1/openapi.json se você preferir gerar um cliente.
API Externa
A API Externa usa autenticação por chave de API e é um recurso pago — está disponível para planos Pro, Scale e Enterprise. Chaves do nível gratuito são rejeitadas com 403 API_PAID_PLAN_REQUIRED.
URL Base
https://api.zenovay.com/api/external/v1
Autenticação
Gere uma chave em Conta → Segurança e acesso (ou abra app.zenovay.com/api-keys diretamente). As chaves começam com zv_. Inclua sua chave em cada requisição usando o header:
X-API-Key: zv_YOUR_API_KEY
# ou
Authorization: Bearer zv_YOUR_API_KEY
Envelope de resposta
Cada resposta da API Externa é envolvida em um envelope padrão. As respostas bem-sucedidas ficam assim:
{
"success": true,
"data": { },
"timestamp": "2026-06-13T00:00:00.000Z"
}
Os exemplos abaixo mostram o conteúdo do objeto data. Erros usam uma forma diferente — veja Respostas de Erro.
Endpoints de Analytics
Obter Visão Geral do Analytics
GET /analytics/{websiteId}
Retorna um resumo de analytics agregado para um site.
Parâmetros de query:
| Parâmetro | Tipo | Descrição |
|---|---|---|
| range | string | Intervalo de tempo: 24h, 7d, 30d, 90d, 1y (padrão: 7d) |
data:
{
"website": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"domain": "example.com",
"name": "My Website"
},
"time_range": "7d",
"date_range": {
"start": "2026-06-06",
"end": "2026-06-13"
},
"summary": {
"total_visitors": 1247,
"total_page_views": 3891,
"unique_visitors": 982
},
"daily_stats": []
}
daily_stats contém as linhas analytics_daily brutas para o intervalo. Para uma API de consulta no estilo Plausible (visitors, pageviews, bounce_rate, visit_duration com filtros e breakdowns), veja a API de Stats.
Obter Visitantes
GET /analytics/{websiteId}/visitors
Retorna registros de visitantes individuais para um site.
Parâmetros de query:
| Parâmetro | Tipo | Descrição |
|---|---|---|
| range | string | Intervalo de tempo (padrão: 7d) |
| limit | integer | Resultados por página (padrão: 100, máx: 1000) |
| offset | integer | Número de registros a pular (padrão: 0) |
Obter Páginas
GET /analytics/{websiteId}/pages
Retorna as principais páginas de um site. Aceita range e limit (padrão 20, máx 100).
Obter Países
GET /analytics/{websiteId}/countries
Retorna uma divisão geográfica de visitantes por país. Aceita range e limit (padrão 20, máx 100).
Obter Tecnologia
GET /analytics/{websiteId}/technology
Retorna a divisão de tecnologia — devices, browsers e operating_systems, cada um com contagens e percentuais. Aceita range.
Endpoints de Sites
Listar Sites
GET /websites
Retorna todos os sites acessíveis pela sua chave de API.
data:
{
"websites": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"domain": "example.com",
"name": "My Website",
"tracking_code": "abc123def456",
"is_active": true,
"created_at": "2026-01-01T00:00:00Z"
}
],
"total": 1
}
Obter Detalhes do Site
GET /websites/{websiteId}
Retorna detalhes de um site específico em data.website.
Endpoints de Heatmap
Obter Páginas do Heatmap
GET /heatmaps/{websiteId}/pages
Retorna páginas que têm dados de heatmap coletados. Aceita limit (padrão 20, máx 100).
Endpoints de Gravação de Sessão
Obter Sessões de Gravação
GET /replays/{websiteId}/sessions
Retorna as gravações de session replay de um site. Aceita limit (padrão 50, máx 200) e offset.
Endpoints de Rastreamento de Erros
Obter Grupos de Erros
GET /errors/{websiteId}/groups
Retorna dados de erros agrupados de um site. Aceita limit (padrão 50, máx 200) e um filtro status opcional (open, resolved, ignored).
Endpoints de IA e Avançados (Pro+)
Estes endpoints requerem um plano Pro ou superior e são limitados baseado no plano do time que é dono do site.
| Endpoint | Descrição |
|---|---|
GET /insights/{websiteId} | Insights gerados por IA para o site |
GET /anomalies/{websiteId} | Anomalias de tráfego/comportamento detectadas |
GET /retention/{websiteId} | Análise de coorte de retenção (granularity, periods) |
GET /revenue/{websiteId}/ltv | Análise de coorte de valor de vida útil |
Consulta em Linguagem Natural (Scale+)
POST /query/{websiteId}
Executa uma consulta de analytics em linguagem natural. Requer um plano Scale ou superior. Envie um corpo JSON com uma string query (máx 500 caracteres); cada chamada consome 3 créditos de consulta.
API de Stats
Endpoints de consulta somente leitura compatíveis com Plausible (Pro+). Estes permitem consultar métricas, séries temporais e breakdowns com filtros. Veja o guia dedicado API de Stats para a referência de parâmetros completa.
| Endpoint | Descrição |
|---|---|
GET /stats/aggregate | Métricas de número único durante um período |
GET /stats/timeseries | Séries com tempo discretizado (interval=day/hour/month) |
GET /stats/breakdown | Métricas agrupadas (principais páginas, principais países, etc.) |
Os três requerem site_id mais period, metrics e filters opcional. As métricas suportadas são visitors, pageviews, bounce_rate, visit_duration e events.
Endpoint de Uso
Verificar Uso da API
GET /usage
Retorna seu uso atual da API e limites.
data:
{
"api_key": {
"id": "key_123",
"name": "Personal API key",
"permission": "full_access",
"website_id": null,
"auth_kind": "user"
},
"usage": {
"monthly_requests": 4521,
"monthly_limit": 10000,
"monthly_remaining": 5479,
"monthly_reset_at": "2026-07-01T00:00:00.000Z",
"total_requests": 18204,
"scope": "user"
},
"rate_limits": {
"requests_per_minute": 30
},
"subscription": {
"tier": "Pro"
}
}
Endpoints de Rastreamento (Públicos)
Estes endpoints não requerem autenticação por chave de API. Eles usam o código de rastreamento do site e estão abertos em todos os planos (limitados apenas por taxa).
Rastrear Pageview ou Evento
POST /e/{trackingCode}
Envia uma pageview ou evento personalizado. Isto é o que o script de rastreamento chama automaticamente. Para rastreamento no lado do servidor, envie o mesmo formato de payload com os headers apropriados. Eventos de heartbeat também podem ser enviados como tipo de evento heartbeat para este endpoint.
Contagem de Visitantes ao Vivo
GET /e/live/{trackingCode}
Retorna o número atual de visitantes ao vivo no site, com uma breve lista de sessões ativas.
Heartbeat
POST /e/heartbeat/{trackingCode}
Envia um heartbeat para manter uma sessão de visitante ativa. Requer um session_id no corpo JSON.
Respostas de Erro
Formato de Erro
Erros são retornados com success: false e um objeto error:
{
"success": false,
"error": {
"message": "site_id parameter is required",
"code": "MISSING_SITE_ID",
"timestamp": "2026-06-13T00:00:00.000Z"
}
}
Códigos de Erro Comuns
| Código | Status HTTP | Descrição |
|---|---|---|
| UNAUTHORIZED | 401 | Chave de API inválida ou ausente |
| API_PAID_PLAN_REQUIRED | 403 | O acesso à API requer um plano Pro ou superior |
| FORBIDDEN | 403 | A chave não tem acesso ao site solicitado, ou o nível do plano é muito baixo |
| NOT_FOUND | 404 | Recurso não encontrado |
| VALIDATION_ERROR | 400 | Parâmetro inválido ou ausente |
| MISSING_SITE_ID | 400 | O parâmetro de query site_id é obrigatório (API de Stats) |
| RATE_LIMIT_EXCEEDED | 429 | Limite de taxa por minuto excedido |
| MONTHLY_LIMIT_EXCEEDED | 429 | Limite mensal de requisições da API atingido |
| INTERNAL_ERROR | 500 | Erro interno |
Limites de Taxa
Os limites de taxa da API Externa se aplicam por chave de API. (A linha Gratuito é mostrada por completude, mas as chaves do nível gratuito não podem chamar a API Externa — é um recurso pago.)
| Plano | Requisições/Minuto | Limite Mensal |
|---|---|---|
| Pro | 30 | 10 000 |
| Scale | 60 | 100 000 |
| Enterprise | 120 | 1 000 000 |
As respostas incluem headers de uso e limite de taxa:
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2026-07-01T00:00:00.000Z
Quando um limite por minuto é atingido, a resposta também inclui um header Retry-After (segundos a aguardar).