4 min de lectura

Referencia de API

La API de Zenovay te permite acceder a tus datos de análisis de forma programática.

Autenticación

Todas las solicitudes de API requieren autenticación. La API Externa utiliza el encabezado X-API-Key. Las claves API están disponibles en el plan Pro y superior — genera una desde Settings → Security → API keys en el panel.

Encabezado de AutenticaciónBash

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

URL Base

La URL base de la API Externa es:

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

Límites de Tasa

La API Externa está disponible en planes pagados. Los planes gratuitos no incluyen acceso API programático.

Plan	Solicitudes por Minuto	Límite Mensual
Gratuito	Sin acceso API	Sin acceso API
Pro	30	10,000
Scale	60	100,000
Enterprise	120	1,000,000

Los encabezados de límite de tasa se incluyen en todas las respuestas:

X-RateLimit-Limit: Límite de solicitudes
X-RateLimit-Remaining: Solicitudes restantes
X-RateLimit-Reset: Marca de tiempo Unix cuando se reinicia el límite

Endpoints

Analytics

GET/analytics/{websiteId}

Obtener datos de análisis de un sitio web

Parámetros

Parámetro	Tipo	Requerido	Descripción
`websiteId`	string	Sí	ID del sitio web
`range`	string	No	Rango de tiempo: `24h`, `7d`, `30d`, `90d` (predeterminado: `7d`)

Respuesta

RespuestaJSON

{
"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
  }
]
}

Datos en Tiempo Real

GET/track/realtime/{websiteId}

Obtener datos de visitantes en tiempo real

Respuesta

RespuestaJSON

{
"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"
}

Gestión de Sitios Web

GET/websites

Listar todos los sitios web

Respuesta

RespuestaJSON

{
"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

Crear un nuevo sitio web

Cuerpo de la Solicitud

SolicitudJSON

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

Respuesta

RespuestaJSON

{
"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"
}
}

Manejo de Errores

La API utiliza códigos de estado HTTP estándar:

Código de Estado	Descripción
200	Éxito
400	Solicitud Incorrecta - Parámetros inválidos
401	No Autorizado - Clave API inválida
403	Prohibido - Permisos insuficientes
404	No Encontrado - El recurso no existe
429	Demasiadas Solicitudes - Límite de tasa excedido
500	Error Interno del Servidor

Respuesta de ErrorJSON

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

Uso de la API

Puedes llamar a la API Externa desde cualquier lenguaje usando solicitudes HTTP estándar:

cURL

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

Bash