Saltar al contenido principal

API de analítica

La API de analítica ofrece acceso programático a las funciones de analítica de producto, incluidas las consultas de eventos, los embudos, el análisis de retención, el análisis de rutas y las cohortes.

Todos los endpoints de esta página son relativos a la URL base: https://api-eu1.joryio.com. Consulta el resumen de la API.

Autenticación​

Todos los endpoints requieren autenticación mediante clave de API:

Authorization: Bearer YOUR_API_KEY
X-Workspace-Id: YOUR_WORKSPACE_ID

Explorador de eventos​

Listar eventos​

Obtiene un resumen de todos los eventos rastreados.

GET /analytics/events

Parámetros de consulta:

ParámetroTipoDescripción
startDatecadenaFecha inicial (AAAA-MM-DD)
endDatecadenaFecha final (AAAA-MM-DD)
searchcadenaFiltra por nombre de evento
limitnúmeroMáximo de resultados (predeterminado: 100)

Respuesta:

{
  "events": [
    {
      "eventName": "signup_completed",
      "totalCount": 15420,
      "uniqueUsers": 12350,
      "lastSeen": "2024-01-15T14:30:00Z"
    }
  ],
  "total": 45
}

Obtener tendencia de eventos​

Obtiene los recuentos de eventos a lo largo del tiempo.

POST /analytics/events/trend

Cuerpo de la solicitud:

{
  "eventNames": ["signup_completed", "purchase_completed"],
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "timeGranularity": "day"
}

Respuesta:

[
  {
    "date": "2024-01-01",
    "count": 523,
    "uniqueUsers": 498
  }
]

Obtener propiedades de un evento​

Lista las propiedades de un evento concreto.

GET /analytics/events/:eventName/properties

Respuesta:

[
  {
    "propertyName": "plan_type",
    "valueCount": 4
  },
  {
    "propertyName": "source",
    "valueCount": 12
  }
]

Obtener desglose de una propiedad​

Obtiene la distribución de valores de una propiedad de evento.

POST /analytics/events/property-breakdown

Cuerpo de la solicitud:

{
  "eventName": "purchase_completed",
  "property": "payment_method",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
}

Respuesta:

{
  "total": 5420,
  "values": [
    { "value": "credit_card", "count": 3250, "percentage": 59.96 },
    { "value": "paypal", "count": 1520, "percentage": 28.04 },
    { "value": "bank_transfer", "count": 650, "percentage": 11.99 }
  ]
}

Análisis de embudos​

Crear un embudo​

Guarda una definición de embudo nueva.

POST /analytics/funnels

Cuerpo de la solicitud:

{
  "name": "Signup to Purchase",
  "steps": [
    {
      "id": "step_1",
      "order": 0,
      "eventName": "signup_completed",
      "filters": []
    },
    {
      "id": "step_2",
      "order": 1,
      "eventName": "onboarding_completed",
      "filters": []
    },
    {
      "id": "step_3",
      "order": 2,
      "eventName": "purchase_completed",
      "filters": []
    }
  ],
  "conversionWindowDays": 7
}

Listar embudos​

GET /analytics/funnels

Analizar un embudo​

Ejecuta un análisis sobre un embudo guardado.

POST /analytics/funnels/:id/analyze

Cuerpo de la solicitud:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "breakdown": {
    "type": "event_property",
    "property": "utm_source"
  }
}

Respuesta:

{
  "totalUsers": 10000,
  "overallConversion": 12.5,
  "steps": [
    {
      "id": "step_1",
      "order": 0,
      "eventName": "signup_completed",
      "enteredCount": 10000,
      "conversionRate": 100,
      "dropOffRate": 0
    },
    {
      "id": "step_2",
      "order": 1,
      "eventName": "onboarding_completed",
      "enteredCount": 6500,
      "conversionRate": 65,
      "dropOffRate": 35
    },
    {
      "id": "step_3",
      "order": 2,
      "eventName": "purchase_completed",
      "enteredCount": 1250,
      "conversionRate": 19.23,
      "dropOffRate": 80.77
    }
  ],
  "breakdown": [
    {
      "breakdownValue": "google",
      "overallConversion": 15.2,
      "steps": [...]
    }
  ]
}

Análisis rápido de embudo​

Analiza sin guardar.

POST /analytics/funnels/quick-analyze

Análisis de retención​

Analizar la retención​

POST /analytics/retention/analyze

Cuerpo de la solicitud:

{
  "startEvent": "signup_completed",
  "returnEvent": "session_started",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "timeUnit": "week",
  "periods": 8
}

Respuesta:

{
  "timeUnit": "week",
  "cohorts": [
    {
      "cohortDate": "2024-01-01",
      "cohortSize": 1250,
      "periods": [
        { "period": 0, "retainedCount": 1250, "retentionRate": 100 },
        { "period": 1, "retainedCount": 562, "retentionRate": 44.96 },
        { "period": 2, "retainedCount": 375, "retentionRate": 30.0 }
      ]
    }
  ],
  "overallRetention": [100, 45.2, 31.5, 25.8, 22.1, 19.5, 17.8, 16.2]
}

Exportar retención​

POST /analytics/retention/export

Devuelve datos CSV.

Análisis de rutas​

Analizar rutas​

POST /analytics/paths/analyze

Cuerpo de la solicitud:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "startEvent": "landing_page_view",
  "direction": "forward",
  "maxSteps": 5,
  "minPathCount": 10,
  "minPathPercent": 0.5,
  "maxBranchesPerStep": 5,
  "excludeEvents": ["heartbeat", "scroll"]
}

minPathCount (usuarios absolutos) y minPathPercent (porcentaje de usuarios que cumplen los requisitos, 0-100) definen el umbral de frecuencia: una ruta debe superar el mayor de los dos. Así, el porcentaje permite usar la regla en espacios de trabajo de cualquier tamaño. maxBranchesPerStep (de 1 a 50; 8 de forma predeterminada) limita el diagrama de flujo a los eventos siguientes más frecuentes de cada paso para que siga siendo legible con un volumen alto.

Respuesta:

{
  "totalUsers": 25000,
  "totalPaths": 342,
  "paths": [
    {
      "path": ["landing_page_view", "signup_started", "signup_completed"],
      "count": 3250,
      "percentage": 13.0
    }
  ],
  "sankey": {
    "nodes": [
      { "id": "landing_page_view_0", "name": "landing_page_view" }
    ],
    "links": [
      { "source": "landing_page_view_0", "target": "signup_started_1", "value": 5200 }
    ]
  }
}

Cohortes​

Crear una cohorte​

POST /analytics/cohorts

Cuerpo de la solicitud:

{
  "name": "Power Users",
  "description": "Users who engage frequently",
  "rules": [
    {
      "type": "event",
      "operator": "did_count",
      "eventName": "session_started",
      "count": 10,
      "timeWindow": { "value": 30, "unit": "day" }
    }
  ]
}

Listar cohortes​

GET /analytics/cohorts

Obtener una cohorte​

GET /analytics/cohorts/:id

Actualizar una cohorte​

PUT /analytics/cohorts/:id

Eliminar una cohorte​

DELETE /analytics/cohorts/:id

Actualizar el recuento de la cohorte​

POST /analytics/cohorts/:id/refresh

Crear un segmento a partir de una cohorte​

Vincula una cohorte con un segmento para dirigir campañas.

POST /analytics/cohorts/:id/create-segment

Cuerpo de la solicitud:

{
  "segmentName": "Power Users Segment"
}

Dashboards​

Crear un dashboard​

POST /analytics/dashboards

Cuerpo de la solicitud:

{
  "name": "Executive Dashboard",
  "description": "Key metrics overview",
  "widgets": [
    {
      "id": "widget-1",
      "type": "metric",
      "title": "Active Users",
      "config": {
        "eventName": "session_started",
        "metric": "unique_users"
      },
      "layout": { "x": 0, "y": 0, "width": 3, "height": 2 }
    }
  ]
}

Listar dashboards​

GET /analytics/dashboards

Obtener un dashboard​

GET /analytics/dashboards/:id

Actualizar un dashboard​

PUT /analytics/dashboards/:id

Eliminar un dashboard​

DELETE /analytics/dashboards/:id

Analítica en tiempo real​

Obtener usuarios activos​

GET /analytics/realtime/active-users

Respuesta:

{
  "count": 1523,
  "trend": 5.2
}

Flujo de eventos en vivo (SSE)​

GET /analytics/realtime/events/stream

Devuelve un flujo Server-Sent Events de eventos en vivo.

Respuestas de error​

Todos los endpoints devuelven respuestas de error estándar:

{
  "statusCode": 400,
  "message": "Invalid date range",
  "error": "Bad Request"
}
Código de estadoDescripción
400Solicitud incorrecta o error de validación
401No autorizado
403Prohibido
404Recurso no encontrado
500Error interno del servidor