API de Analítica (v1)

Consulta por demanda de tus métricas de conversión, suscripciones, planes, reglas, contenidos y campañas — pensada para alimentar tus propias herramientas de analítica sin depender del dashboard.

Requiere plan habilitado: esta API es una capacidad adicional del plan de licencia, no viene incluida por defecto. Si tu tenant no la tiene habilitada, cada endpoint responde 403 Forbidden. Contacta a Nivelics para activarla.

Autenticación

Se autentica con el mismo X-API-Key que ya usas para /access/check — no hay un token separado para analítica.

curl https://engine.paywl.io/v1/analytics/conversions \
  -H "X-API-Key: npe_tu_api_key"

Formato de respuesta

Todos los endpoints devuelven el mismo sobre (envelope): los datos en data, y metadatos de la consulta en meta.

{
  "data": [ ... ],
  "meta": {
    "tenant_id": "4596c45d-...",
    "range": { "from": "2026-08-17T00:00:00.000Z", "to": "2026-09-16T00:00:00.000Z" },
    "generated_at": "2026-09-16T22:10:03.512Z"
  }
}

Los endpoints con serie temporal aceptan from/to (ISO 8601) por query string. Sin esos parámetros, el rango por defecto son los últimos 30 días.

Rate limiting

Cada tenant tiene un límite de requests por minuto (definido por su plan). Al superarlo, la API responde 429 Too Many Requests con un header Retry-After indicando cuántos segundos esperar antes de reintentar.

HTTP/1.1 429 Too Many Requests
Retry-After: 34

{ "message": "Rate limit exceeded (30 requests/minute). Retry after 34s.", "statusCode": 429 }

Además, la respuesta de cada endpoint se cachea internamente por unos minutos — si vuelves a pedir exactamente la misma consulta poco después, puede llegar más rápido sin contar doble contra tu límite de solicitudes reales a la base de datos.

Sin datos personales

Todos los endpoints devuelven datos agregados (conteos, tasas, montos) — nunca el email, nombre o documento de un suscriptor individual. Si necesitas cruzar una métrica con un suscriptor puntual, usa el dashboard o la Subscriptions API.

Endpoints

Endpoint	Parámetros	Devuelve
`GET /v1/analytics/conversions`	`from`, `to`	Conversiones clasificadas por fuente: campaña, landing externa, contenido, o directo.
`GET /v1/analytics/campaigns`	`from`, `to`	Conversiones desglosadas por el valor real de `utm_campaign` (una fila por campaña + fuente + medio) — para medir landings específicas, como la de una campaña de lanzamiento.
`GET /v1/analytics/subscriptions`	`from`, `to`	Suscriptores activos y cancelaciones por mes.
`GET /v1/analytics/plans`	—	Suscripciones activas/canceladas y MRR por plan, calculado sobre el precio efectivo real (monto variable, fase de precio, o descuento de retención vigente).
`GET /v1/analytics/rules`	`from`, `to`	Veces que se activó cada regla, y su tasa de grants/denegaciones.
`GET /v1/analytics/content`	`from`, `to`	Desempeño por artículo/contenido: checks de acceso, grants, denegaciones.
`GET /v1/analytics/funnel`	`from`, `to`	Wall views únicos, clics, y tasas de stop/conversión/click-through.
`GET /v1/analytics/subscribers`	—	Conteo de suscriptores agrupado por estado (activo, cancelado, etc.) — sin PII.
`GET /v1/analytics/mrr`	—	MRR/ARR total, desglose por plan, y movimiento del mes en curso (MRR nuevo vs. perdido por cancelación).
`GET /v1/analytics/ltv`	—	LTV agregado por suscriptor: promedio, mediana, distribución por rangos — sin la lista de suscriptores top (esa vista, con email, solo existe en el dashboard interno).
`GET /v1/analytics/cohorts`	—	Retención por cohorte de mes de adquisición: tamaño de cada cohorte y % retenido en los meses siguientes.
`GET /v1/analytics/churn-risk`	—	Resumen del modelo de riesgo de cancelación: total de suscriptores puntuados, conteo por nivel de riesgo (bajo/medio/alto), score promedio, y fecha del último cálculo — sin scores por suscriptor individual.
`GET /v1/analytics/propensity`	—	Resumen del modelo de propensión de conversión: total de prospectos puntuados, conteo por nivel de oportunidad (bajo/medio/alto), score promedio, y fecha del último cálculo — sin scores por prospecto individual.

Ejemplo: métricas de una campaña específica

Para medir las páginas de destino de una campaña (por ejemplo, la de lanzamiento de un libro), usa /v1/analytics/campaigns — te da conversiones reales por utm_campaign, no solo el bucket genérico "campaña" de /v1/analytics/conversions.

curl "https://engine.paywl.io/v1/analytics/campaigns?from=2026-09-01&to=2026-09-30" \
  -H "X-API-Key: npe_tu_api_key"

{
  "data": [
    { "utm_campaign": "libro-2026", "utm_source": "facebook", "utm_medium": "cpc", "conversions": 42 },
    { "utm_campaign": "libro-2026", "utm_source": "newsletter", "utm_medium": "email", "conversions": 15 }
  ],
  "meta": { "tenant_id": "...", "range": { "from": "2026-09-01", "to": "2026-09-30" }, "generated_at": "..." }
}