Acceso a datos en tiempo real

Extraiga datos de análisis de Zenovay para construir sus propios paneles y herramientas de monitoreo.

Zenovay no expone una secuencia WebSocket pública. El panel renderiza la actividad de visitantes en directo internamente, pero para sus propias integraciones el patrón compatible es el sondeo de la API externa. Esta guía muestra cómo hacerlo de manera eficiente.

Dónde se encuentran los datos en tiempo real

Caso de uso	Mejor enfoque
Vea visitantes en vivo usted mismo	La pestaña Vista en directo en su panel (se actualiza en tiempo real)
Panel personalizado	Sondee la API externa
Datos históricos	API externa con un filtro range
Incrustar un contador de visitantes en directo en su sitio	La función Widgets (un widget HTML independiente)

Para ver quién está en su sitio ahora, abra el panel de su sitio web y seleccione la pestaña Vista en directo — se actualiza automáticamente. Las secciones a continuación cubren la creación de su propia integración externa en la API.

Sondeo de la API externa

Para los datos de análisis, use la API externa con su clave API. La URL base es:

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

Autentíquese con uno de estos encabezados:

X-API-Key: zv_YOUR_API_KEY
Authorization: Bearer zv_YOUR_API_KEY

Análisis reciente

El punto de conexión del resumen de análisis acepta un parámetro de consulta range (24h, 7d, 30d, 90d, 1y — por defecto 7d):

const API_KEY = process.env.ZENOVAY_API_KEY;
const WEBSITE_ID = 'your-website-id';

async function getRecentAnalytics() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}?range=24h`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  return await response.json();
}

Cada respuesta de la API externa se envuelve en un sobre { success, data, timestamp }, y los totales se encuentran en data.summary:

{
  "success": true,
  "data": {
    "summary": {
      "total_visitors": 1247,
      "total_page_views": 3891,
      "unique_visitors": 1102
    },
    "time_range": "24h",
    "daily_stats": [ /* ... */ ]
  },
  "timestamp": "2026-06-13T00:00:00.000Z"
}

Datos de visitantes

async function getVisitors() {
  const response = await fetch(
    `https://api.zenovay.com/api/external/v1/analytics/${WEBSITE_ID}/visitors`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );

  return await response.json();
}

Dentro del sobre data, esto devuelve un array visitors más un objeto pagination (limit, offset, has_more). Use los parámetros de consulta limit y offset para paginar a través de resultados.

Crear un panel personalizado

Ejemplo con React

import { useState, useEffect } from 'react';

function LiveDashboard({ websiteId, apiKey }) {
  const [analytics, setAnalytics] = useState(null);

  // Actualice el resumen de análisis en un intervalo que respete su límite de velocidad
  useEffect(() => {
    async function fetchAnalytics() {
      try {
        const response = await fetch(
          `https://api.zenovay.com/api/external/v1/analytics/${websiteId}?range=24h`,
          {
            headers: { 'X-API-Key': apiKey }
          }
        );
        const body = await response.json();
        // Las respuestas están envueltas en un sobre { success, data, timestamp }.
        setAnalytics(body.data);
      } catch (error) {
        console.error('Analytics fetch error:', error);
      }
    }

    fetchAnalytics();
    const interval = setInterval(fetchAnalytics, 5 * 60 * 1000);
    return () => clearInterval(interval);
  }, [websiteId, apiKey]);

  return (
    <div>
      {analytics && (
        <div>
          <h2>Últimas 24 horas</h2>
          <p>Visitantes: {analytics.summary.total_visitors}</p>
          <p>Vistas de página: {analytics.summary.total_page_views}</p>
          <p>Visitantes únicos: {analytics.summary.unique_visitors}</p>
        </div>
      )}
    </div>
  );
}

Consideraciones sobre los límites de velocidad

Los límites de velocidad de la API externa son por clave API, y la API solo está disponible de pago — la fila Free se muestra por completitud, pero las claves del tier Free no pueden llamarla.

Plan	Solicitudes/minuto	Intervalo de sondeo recomendado
Free	No disponible	—
Pro	30	Cada 5 minutos
Scale	60	Cada 2 minutos
Enterprise	120	Cada minuto

Las respuestas incluyen los encabezados X-RateLimit-Limit y X-RateLimit-Remaining (en la ruta de respaldo), por lo que puede leerlos y retroceder a medida que se acerca al límite.

Mejores prácticas

• No sondee más rápido de lo que su límite de velocidad de plan permite — los datos de análisis se actualizan en el orden de minutos, no segundos.
• Almacene en caché las respuestas localmente entre sondeos.
• Implemente el manejo de errores con retroceso exponencial.
• Para ver visitantes en directo usted mismo, use la pestaña Vista en directo en lugar de sondear — está diseñada para eso.

Próximos pasos

• Referencia de la API REST
• Descripción general de la API
• Obtener una clave API