¿Cómo consulto mis análisis mediante programación (Stats API)?

La Stats API es una interfaz de consulta pública y con límite de velocidad que le permite obtener sus análisis de Zenovay por HTTP. Úsela para construir paneles personalizados, integrar métricas en vivo en herramientas de BI o migrar scripts desde Plausible.

Qué puede consultar

Endpoint	Qué devuelve
GET /stats/aggregate	Totales durante un periodo (visitantes, páginas vistas, tasa de rebote, duración media de sesión).
GET /stats/timeseries	Un punto de datos por día, hora o mes durante el periodo.
GET /stats/breakdown	Páginas principales, países principales, navegadores principales: cualquier dimensión única, ordenada por visitantes.

Referencia completa, tablas de parámetros y ejemplos: docs.zenovay.com/api/external-api (busque la sección "Stats API").

La especificación OpenAPI 3.1 en vivo está disponible en /api/external/v1/openapi.json — impórtela en Postman, Insomnia o úsela con un generador de código.

Requisitos del plan

La Stats API está disponible en los planes Pro, Scale y Enterprise. El plan gratuito no puede crear ni utilizar claves API — las llamadas devuelven un error 403 API_PAID_PLAN_REQUIRED. Actualice en Configuración → Facturación.

Límites de velocidad por nivel

Plan	Límite de velocidad (por minuto, objetivo)	Cuota mensual de solicitudes
Gratuito	10	1.000
Pro	30	10.000
Scale	60	100.000
Empresa	120	1.000.000

Cuando supere el límite de velocidad de su nivel, la API devuelve 429 Too Many Requests con una cabecera Retry-After que indica cuántos segundos esperar.

Cómo se aplica el límite de velocidad. El límite por minuto es un objetivo, no un techo rígido. Utilizamos el límite de velocidad del edge de Cloudflare, que es por centro de datos con una pequeña tolerancia de picos: un cliente sostenido puede ver transitoriamente 1,5-3× el número indicado antes de ser limitado, especialmente si las solicitudes se distribuyen entre regiones. El límite máximo es la cuota mensual de solicitudes, que se aplica atómicamente a su cuenta sin importar de dónde provengan las solicitudes. Planifique las cargas de trabajo sensibles a la capacidad según la cuota mensual; trate el número por minuto como un objetivo de suavizado.

Primeros pasos

1. Obtenga una clave API (Pro+): consulte ¿Cómo obtengo una clave API?. Las claves comienzan con zv_.
2. Encuentre el UUID de su sitio: abra el sitio web en su panel de Zenovay. El UUID está en la URL: app.zenovay.com/domains/<UUID>.
3. Haga su primera llamada:

curl -G "https://api.zenovay.com/api/external/v1/stats/aggregate" \
  -H "X-API-Key: zv_YOUR_KEY" \
  --data-urlencode "site_id=YOUR_SITE_UUID" \
  --data-urlencode "period=7d" \
  --data-urlencode "metrics=visitors,pageviews"

Debería obtener algo como:

{
  "success": true,
  "data": {
    "results": {
      "visitors":  { "value": 12453 },
      "pageviews": { "value": 38219 }
    },
    "meta": { "period": "7d", "period_start": "...", "period_end": "..." }
  }
}

Casos de uso comunes

• Paneles personalizados: extraiga métricas agregadas en Notion, Coda, Retool o una herramienta de BI interna cada hora.
• Migración desde Plausible: la forma de los parámetros (site_id, period, date, metrics, filters, property) es intencionalmente compatible con Plausible. La mayoría de los scripts de migración funcionan después de reemplazar la URL base y remapear site_id de un dominio a su UUID de Zenovay.
• Embeds: muestre recuentos de visitantes en vivo en su página de estado o sitio de marketing (use un proxy del lado del servidor; nunca exponga su clave API en código del lado del cliente).
• Informes programados: obtenga datos de desglose una vez al día y publíquelos en Slack o por email.

Filtros

Puede limitar cualquier consulta a un subconjunto de visitantes con filtros al estilo de Plausible:

# Solo visitantes estadounidenses
--data-urlencode "filters=country==US"

# Visitantes estadounidenses + canadienses usando Chrome
--data-urlencode "filters=country==US,CA;browser==Chrome"

# Todos excepto páginas /admin
--data-urlencode "filters=page!=/admin"

Claves de filtro permitidas: country, browser, device, os, source, utm_source, utm_medium, utm_campaign, page.

Limitación de V1: Cuando proporciona filters, solo se calcula la métrica visitors en V1; las demás métricas devuelven null con un indicador meta.note. El soporte completo de filtros en todas las métricas llega en V2. Las consultas sin filtros admiten todas las métricas hoy.

Resolución de problemas

Síntoma	Causa	Solución
401 UNAUTHORIZED "Missing API key"	Sin cabecera X-API-Key o Authorization: Bearer	Añada la cabecera. Genere una clave en Configuración → Cuenta → Seguridad y acceso si no tiene una.
401 UNAUTHORIZED "Invalid API key"	La clave fue revocada, tiene un error tipográfico o no comienza con zv_	Vuelva a copiarla desde Configuración → Cuenta → Seguridad y acceso.
403 FORBIDDEN "requires a Pro plan"	Su equipo está en el plan gratuito	Actualice en Configuración → Facturación.
403 FORBIDDEN "does not have access"	La clave API tiene ámbito de un solo sitio, pero site_id no coincide	Cree una clave de acceso completo o llame con el site_id correcto.
404 NOT_FOUND "Website not found"	UUID de site_id incorrecto	Verifique en la URL del panel.
400 MISSING_*	Falta un parámetro de consulta requerido	Añada site_id, period y metrics (siempre requeridos).
400 INVALID_METRIC	Nombre de métrica desconocido	Use visitors, pageviews, visit_duration, bounce_rate o events.
400 INTERVAL_PERIOD_MISMATCH	interval=hour con period distinto a day	Use period=day con interval=hour, o use interval=day para periodos más largos.
429 Too Many Requests	Límite de velocidad por nivel alcanzado	Respete la cabecera Retry-After. Actualice de nivel si regularmente alcanza este límite.

Migración desde Plausible

La forma de los parámetros es intencionalmente cercana a la Stats API v1 de Plausible. Diferencias:

Plausible	Zenovay	Notas
site_id=mysite.com	site_id=<UUID>	Plausible usa una cadena de dominio; Zenovay usa un UUID. Mapéelo una vez mediante GET /websites.
period, date	period, date	Misma lista permitida + custom:YYYY-MM-DD,YYYY-MM-DD.
metrics	metrics	visitors, pageviews, bounce_rate, visit_duration se mapean 1:1.
filters (formato de cadena v1)	filters	Misma forma key==value;key!=value.
filters (array JSON v2)	(V2 de la Stats API de Zenovay)	Llega más adelante.

Siguientes pasos

• Referencia completa de la Stats API (docs) — cada parámetro, cada endpoint, cada código de error.
• Especificación OpenAPI 3.1 — para generación de código y herramientas de prueba de API.
• Autenticación — cabeceras Bearer vs X-API-Key, rotación de claves.
• Resumen de la API — todos los demás endpoints públicos de Zenovay (insights, anomalías, retención, LTV, consulta en lenguaje natural).