Referencia completa de todos los puntos de terminación de la API REST de Zenovay. Para comenzar, consulte Descripción general de la API.
Se publica una especificación OpenAPI legible por máquinas en https://api.zenovay.com/api/external/v1/openapi.json si prefiere generar un cliente.
API externa
La API externa utiliza autenticación con clave API y es una función de pago: está disponible para planes Pro, Scale y Enterprise. Las claves de nivel gratuito se rechazan con 403 API_PAID_PLAN_REQUIRED.
URL base
https://api.zenovay.com/api/external/v1
Autenticación
Genere una clave en Cuenta → Seguridad y acceso (o abra app.zenovay.com/api-keys directamente). Las claves comienzan con zv_. Incluya su clave en cada solicitud usando el encabezado:
X-API-Key: zv_YOUR_API_KEY
# o
Authorization: Bearer zv_YOUR_API_KEY
Envolvente de respuesta
Cada respuesta de la API externa se envuelve en una envolvente estándar. Las respuestas exitosas se ven así:
{
"success": true,
"data": { },
"timestamp": "2026-06-13T00:00:00.000Z"
}
Los ejemplos a continuación muestran el contenido del objeto data. Los errores utilizan una forma diferente - ver Respuestas de error.
Puntos de terminación de análisis
Obtener resumen de análisis
GET /analytics/{websiteId}
Devuelve un resumen de análisis agregado para un sitio web.
Parámetros de consulta:
| Parámetro | Tipo | Descripción |
|---|---|---|
| range | string | Rango de tiempo: 24h, 7d, 30d, 90d, 1y (predeterminado: 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 contiene las filas analytics_daily sin procesar para el rango. Para una API de consulta de estilo Plausible (visitors, pageviews, bounce_rate, visit_duration con filtros y desglose), consulte la API de estadísticas.
Obtener visitantes
GET /analytics/{websiteId}/visitors
Devuelve registros de visitantes individuales para un sitio web.
Parámetros de consulta:
| Parámetro | Tipo | Descripción |
|---|---|---|
| range | string | Rango de tiempo (predeterminado: 7d) |
| limit | integer | Resultados por página (predeterminado: 100, máx: 1000) |
| offset | integer | Número de registros a omitir (predeterminado: 0) |
Obtener páginas
GET /analytics/{websiteId}/pages
Devuelve las páginas principales de un sitio web. Acepta range y limit (predeterminado 20, máx 100).
Obtener países
GET /analytics/{websiteId}/countries
Devuelve un desglose geográfico de visitantes por país. Acepta range y limit (predeterminado 20, máx 100).
Obtener tecnología
GET /analytics/{websiteId}/technology
Devuelve el desglose tecnológico - devices, browsers y operating_systems, cada uno con recuentos y porcentajes. Acepta range.
Puntos de terminación de sitios web
Listar sitios web
GET /websites
Devuelve todos los sitios web accesibles con su clave 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
}
Obtener detalles del sitio web
GET /websites/{websiteId}
Devuelve detalles de un sitio web específico bajo data.website.
Puntos de terminación de mapa de calor
Obtener páginas del mapa de calor
GET /heatmaps/{websiteId}/pages
Devuelve las páginas que tienen datos de mapa de calor recopilados. Acepta limit (predeterminado 20, máx 100).
Puntos de terminación de reproducción de sesión
Obtener sesiones de reproducción
GET /replays/{websiteId}/sessions
Devuelve las grabaciones de reproducción de sesión para un sitio web. Acepta limit (predeterminado 50, máx 200) y offset.
Puntos de terminación de rastreo de errores
Obtener grupos de errores
GET /errors/{websiteId}/groups
Devuelve datos de errores agrupados para un sitio web. Acepta limit (predeterminado 50, máx 200) y un filtro status opcional (open, resolved, ignored).
Puntos de terminación de IA y avanzados (Pro+)
Estos puntos de terminación requieren un plan Pro o superior y se limitan según el plan del equipo propietario del sitio web.
| Punto de terminación | Descripción |
|---|---|
GET /insights/{websiteId} | Información generada por IA para el sitio |
GET /anomalies/{websiteId} | Anomalías de tráfico/comportamiento detectadas |
GET /retention/{websiteId} | Análisis de cohorte de retención (granularity, periods) |
GET /revenue/{websiteId}/ltv | Análisis de cohorte de valor de por vida |
Consulta de lenguaje natural (Scale+)
POST /query/{websiteId}
Ejecuta una consulta de análisis en lenguaje natural. Requiere un plan Scale o superior. Envíe un cuerpo JSON con una cadena query (máx 500 caracteres); cada llamada consume 3 créditos de consulta.
API de estadísticas
Puntos de terminación de consulta de solo lectura compatibles con Plausible (Pro+). Estos le permiten consultar métricas, series de tiempo y desglose con filtros. Consulte la guía dedicada API de estadísticas para la referencia de parámetros completa.
| Punto de terminación | Descripción |
|---|---|
GET /stats/aggregate | Métricas de número único durante un período |
GET /stats/timeseries | Series con tiempo discretizado (interval=day/hour/month) |
GET /stats/breakdown | Métricas agrupadas (páginas principales, países principales, etc.) |
Los tres requieren site_id más period, metrics y filters opcional. Las métricas admitidas son visitors, pageviews, bounce_rate, visit_duration y events.
Punto de terminación de uso
Verificar uso de la API
GET /usage
Devuelve su uso actual de la API y sus límites.
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"
}
}
Puntos de terminación de rastreo (públicos)
Estos puntos de terminación no requieren autenticación con clave API. Utilizan el código de rastreo del sitio web y están abiertos en todos los planes (solo limitados por tasa).
Rastrear vista de página o evento
POST /e/{trackingCode}
Envía una vista de página o un evento personalizado. Esto es lo que el script de rastreo llama automáticamente. Para rastreo del lado del servidor, envíe el mismo formato de carga útil con los encabezados apropiados. Los eventos de latido también se pueden enviar como tipo de evento heartbeat a este punto de terminación.
Recuento de visitantes en vivo
GET /e/live/{trackingCode}
Devuelve el número actual de visitantes en vivo en el sitio, con una breve lista de sesiones activas.
Latido
POST /e/heartbeat/{trackingCode}
Envía un latido para mantener activa la sesión de un visitante. Requiere un session_id en el cuerpo JSON.
Respuestas de error
Formato de error
Los errores se devuelven con success: false y un 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 error comunes
| Código | Estado HTTP | Descripción |
|---|---|---|
| UNAUTHORIZED | 401 | Clave API inválida o faltante |
| API_PAID_PLAN_REQUIRED | 403 | El acceso a la API requiere un plan Pro o superior |
| FORBIDDEN | 403 | La clave no tiene acceso al sitio solicitado, o el nivel de plan es demasiado bajo |
| NOT_FOUND | 404 | Recurso no encontrado |
| VALIDATION_ERROR | 400 | Parámetro inválido o faltante |
| MISSING_SITE_ID | 400 | Se requiere el parámetro de consulta site_id (API de estadísticas) |
| RATE_LIMIT_EXCEEDED | 429 | Límite de tasa por minuto excedido |
| MONTHLY_LIMIT_EXCEEDED | 429 | Se ha alcanzado el límite mensual de solicitudes de API |
| INTERNAL_ERROR | 500 | Error interno |
Límites de tasa
Los límites de tasa de la API externa se aplican por clave API. (La fila Gratuito se muestra por completitud, pero las claves de nivel gratuito no pueden llamar a la API externa; es una función de pago.)
| Plan | Solicitudes/Minuto | Límite mensual |
|---|---|---|
| Pro | 30 | 10 000 |
| Scale | 60 | 100 000 |
| Enterprise | 120 | 1 000 000 |
Las respuestas incluyen encabezados de uso y límite de tasa:
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
Cuando se alcanza un límite por minuto, la respuesta también incluye un encabezado Retry-After (segundos a esperar).