Descripción general de la API

Pro Plan

La API de Zenovay proporciona acceso programático a sus datos de análisis. Cree integraciones personalizadas, automatice flujos de trabajo y amplie las capacidades de Zenovay.

Qué puede hacer

API externa (autenticación con clave API)

Capacidad	Endpoint
Resumen de análisis	GET /api/external/v1/analytics/:websiteId
Datos de visitantes	GET /api/external/v1/analytics/:websiteId/visitors
Análisis de páginas	GET /api/external/v1/analytics/:websiteId/pages
Datos por país	GET /api/external/v1/analytics/:websiteId/countries
Desglose tecnológico	GET /api/external/v1/analytics/:websiteId/technology
Listar sitios web	GET /api/external/v1/websites
Detalles del sitio web	GET /api/external/v1/websites/:websiteId
Uso de la API	GET /api/external/v1/usage
Páginas de heatmap	GET /api/external/v1/heatmaps/:websiteId/pages
Grabaciones de sesión	GET /api/external/v1/replays/:websiteId/sessions
Grupos de errores	GET /api/external/v1/errors/:websiteId/groups

Rastreo (Público)

Estos endpoints son utilizados por el script de rastreo — no se requiere clave API.

Capacidad	Endpoint
Registrar vista de página/evento	POST /e/:trackingCode
Recuento de visitantes en vivo	GET /e/live/:trackingCode
Latido	POST /e/heartbeat/:trackingCode

Acceso a la API por plan

La API REST es una función de pago. Los espacios de trabajo gratuitos no pueden crear ni usar claves API — los endpoints de rastreo no autenticados anteriores permanecen disponibles en todos los planes.

Plan	Acceso API	Solicitudes/Minuto	Límite mensual
Free	No disponible	—	—
Pro	Completo	30	10.000
Scale	Completo	60	100.000
Enterprise	Completo	120	1.000.000

URL base

La URL base de la API externa es:

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

Autenticación

Claves API

Autentíquese con claves API usando el encabezado X-API-Key o el encabezado Authorization: Bearer:

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

O usando autenticación Bearer:

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

Las claves API siempre comienzan con el prefijo zv_.

Obtener su clave API

Vaya a Configuración → Seguridad y abra la sección Claves API
Haga clic en "Crear clave API"
Asigne un nombre a su clave
Establezca su alcance (todos los sitios web o un sitio web único)
Copie la clave (se muestra una sola vez)

Las claves API requieren un plan Pro o superior. En un plan gratuito, el botón de creación está deshabilitado.

Consulte Autenticación para más detalles.

Inicio rápido

Listar sus sitios web

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

Obtener resumen de análisis

Los endpoints de análisis requieren una ID de sitio web (un UUID — cópielo de la respuesta "Listar sus sitios web" anterior) y un range opcional (uno 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 el uso de la API

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

Formato de solicitud

Encabezados

Encabezado requerido (use cualquiera de las formas):

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Envíe Content-Type: application/json en solicitudes POST que contengan un cuerpo JSON.

Encabezado opcional:

X-Request-ID: your-unique-id (devuelto para depuración)

Parámetros de consulta

Parámetros comunes en los endpoints de análisis:

Parámetro	Descripción	Ejemplo
range	Ventana de tiempo: `24h`, `7d`, `30d`, `90d`, `1y` (por defecto `7d`)	?range=30d
limit	Máx. filas a devolver	?limit=50
offset	Filas a saltar (para paginación)	?offset=100

Formato de respuesta

Respuesta exitosa

Las respuestas exitosas se envuelven en una envoltura success/data:

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

La forma del objeto data depende del endpoint (por ejemplo, el resumen de análisis devuelve website, summary y daily_stats). Los endpoints que paginan sus resultados incluyen un objeto pagination dentro de data.

Respuesta de error

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

Código	Significado
200	Éxito
201	Creado
400	Solicitud incorrecta
401	No autorizado
403	Prohibido
404	No encontrado
429	Límite de tasa alcanzado
500	Error del servidor

Bibliotecas cliente

Zenovay no tiene paquetes SDK oficiales. En su lugar, use el script de rastreo CDN para rastreo del lado del navegador y solicitudes HTTP estándar (fetch, requests, curl, etc.) para acceso a la API del lado del servidor.

JavaScript (Navegador)

Agregue el script de rastreo a su HTML:

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

Luego use la función global zenovay:

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

JavaScript (Lado del servidor)

Use fetch para llamar a la API externa directamente:

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 comunes

Paneles personalizados

Cree paneles internos:

Obtenga métricas agregadas
Cree visualizaciones personalizadas
Combine con otros datos

Informes automatizados

Genere informes personalizados:

Informes semanales para partes interesadas
Alertas en tiempo real
Monitoreo de umbrales

Integración con CRM

Conéctese a su CRM:

Envíe datos de visitantes
Actualice registros de contactos
Dispare flujos de trabajo

Límites de tasa

Los límites de tasa de la API externa son por clave API, por minuto, y dependen del plan del equipo al que pertenece la clave:

Plan	Solicitudes/Minuto	Límite mensual
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

Encabezados de límite de tasa

Las respuestas incluyen encabezados de uso y límite de tasa:

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

X-RateLimit-Remaining se incluye cuando está disponible. Cuando supera un límite, la API devuelve 429 con un encabezado Retry-After.

Consulte Límites de tasa para conocer las mejores prácticas.

Mejores prácticas

Solicitudes eficientes

Solicite solo los campos necesarios
Use filtros de fecha
Pagine los resultados grandes
Almacene en caché cuando sea posible

Manejo de errores

Implemente reintentos
Gestione los límites de tasa
Registre los errores
Monitoree las tasas de éxito

Seguridad

Mantenga las claves en secreto
Use permisos mínimos
Rote las claves periódicamente
Audite el uso de las claves

Pruebas

No hay sandbox separado — pruebe en producción con una clave dedicada:

Vaya a Configuración → Seguridad y abra la sección Claves API
Cree una clave y dale un nombre reconocible (p. ej. "Test")
Limítela a un único sitio web de prueba si es posible
Use la URL estándar de la API: https://api.zenovay.com/api/external/v1/
Elimine la clave cuando haya terminado