4 min de leitura

Referência da API

A API Zenovay permite que você acesse seus dados de análise de forma programática.

Autenticação

Todas as requisições da API exigem autenticação. A API Externa utiliza o cabeçalho X-API-Key. As chaves de API estão disponíveis no plano Pro e superior — gere uma em Settings → Security → API keys no dashboard.

Authentication HeaderBash

curl -H "X-API-Key: YOUR_API_KEY" \
https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID

URL Base

A URL base da API Externa é:

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

Limites de Taxa

A API Externa está disponível em planos pagos. Planos gratuitos não incluem acesso à API programática.

Plano	Requisições por Minuto	Limite Mensal
Gratuito	Sem acesso à API	Sem acesso à API
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

Cabeçalhos de limite de taxa estão incluídos em todas as respostas:

X-RateLimit-Limit: Limite de requisições
X-RateLimit-Remaining: Requisições restantes
X-RateLimit-Reset: Timestamp Unix quando o limite é redefinido

Endpoints

Analytics

GET/analytics/{websiteId}

Obtenha dados de análise para um site

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`websiteId`	string	Sim	ID do Site
`range`	string	Não	Intervalo de tempo: `24h`, `7d`, `30d`, `90d` (padrão: `7d`)

Resposta

ResponseJSON

{
"website": {
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "domain": "example.com",
  "name": "My Website"
},
"timeRange": "7d",
"totalVisitors": 1247,
"totalPageViews": 3891,
"bounceRate": 42.3,
"topCountries": [
  {
    "name": "United States",
    "code": "US",
    "visitors": 456,
    "percentage": 36.6
  }
],
"dailyStats": [
  {
    "date": "2025-01-01",
    "visitors": 178,
    "pageViews": 542,
    "bounceRate": 38.2
  }
]
}

Dados em Tempo Real

GET/track/realtime/{websiteId}

Obtenha dados de visitantes em tempo real

Resposta

ResponseJSON

{
"count": 23,
"visitors": [
  {
    "id": "visitor-123",
    "country_name": "United States",
    "city": "New York",
    "device_type": "desktop",
    "value_score": 78,
    "visited_at": "2025-01-01T12:34:56Z"
  }
],
"timestamp": "2025-01-01T12:35:00Z"
}

Gerenciamento de Sites

GET/websites

Liste todos os sites

Resposta

ResponseJSON

{
"websites": [
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "example.com",
    "name": "My Website",
    "tracking_code": "abc123def456",
    "is_active": true,
    "created_at": "2025-01-01T00:00:00Z"
  }
]
}

POST/websites

Crie um novo site

Corpo da Requisição

RequestJSON

{
"domain": "newsite.com",
"name": "My New Website"
}

Resposta

ResponseJSON

{
"website": {
  "id": "789e0123-e89b-12d3-a456-426614174000",
  "domain": "newsite.com",
  "name": "My New Website",
  "tracking_code": "xyz789abc123",
  "is_active": true,
  "created_at": "2025-01-01T12:00:00Z"
}
}

Tratamento de Erros

A API utiliza códigos de status HTTP padrão:

Código de Status	Descrição
200	Sucesso
400	Requisição Inválida - Parâmetros inválidos
401	Não Autorizado - Chave de API inválida
403	Proibido - Permissões insuficientes
404	Não Encontrado - Recurso não existe
429	Muitas Requisições - Limite de taxa excedido
500	Erro Interno do Servidor

Error ResponseJSON

{
"error": "Website not found",
"message": "The specified website ID does not exist or you don't have access to it"
}

Usando a API

Você pode chamar a API Externa de qualquer linguagem usando requisições HTTP padrão:

cURL

curl -X GET "https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID" \
-H "X-API-Key: YOUR_API_KEY"

Bash