Puntos finales de la API

Zenovay proporciona varios grupos de puntos finales de API para acceder a tus datos de análisis mediante programación.

Autenticación

Todas las solicitudes de API requieren autenticación. El método depende de la API que uses:

Consulta Autenticación para obtener detalles sobre la gestión de claves de API.

API externa

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

API del lado del servidor para acceder a datos de análisis con autenticación de clave de API (encabezado X-API-Key).

Puntos finales disponibles

Cada punto final tiene una página de referencia dedicada con parámetros, esquemas de respuesta, interfaces de TypeScript y ejemplos de código en cURL, JavaScript, Python y TypeScript.

Consulta también la descripción general de la API externa para una introducción de alto nivel.

Widgets incrustables

URL base: https://api.zenovay.com/widgets

Widgets listos para usar que no requieren autenticación. Usa tu código de seguimiento para identificar el sitio web.

Consulta Widgets para obtener ejemplos de incrustación.

Datos en tiempo real

URL base: https://api.zenovay.com/e

Puntos finales JSON públicos para estadísticas en vivo. No se requiere autenticación.

Consulta Datos en tiempo real para obtener guías de integración.

Límites de velocidad

Los límites de velocidad de la API varían según el plan:

Los encabezados de límite de velocidad se incluyen en todas las respuestas:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1642771200

El valor X-RateLimit-Limit refleja el límite por minuto de tu plan (p. ej., 10 para Gratuito, 30 para Pro, 60 para Escala, 120 para Empresa).

Consulta Límites de velocidad para obtener detalles sobre cómo manejar errores de límite de velocidad.

Códigos de error

{
"success": true,
"data": { ... },
"timestamp": "2026-02-07T12:00:00.000Z"
}

{
"success": false,
"error": {
  "message": "The provided API key is missing or invalid",
  "code": "UNAUTHORIZED",
  "timestamp": "2026-02-07T12:00:00.000Z"
}
}

Webhooks

Configura webhooks para recibir notificaciones en tiempo real:

Eventos disponibles

• visitor.identified - Cuando se identifica un visitante
• visitor.high_value - Cuando la puntuación del visitante llega a 80+
• event.tracked - Cuando se realiza un seguimiento de cualquier evento
• goal.completed - Cuando se completa un objetivo
• visitor.converted - Cuando un visitante se convierte

Carga útil de webhook

{
"event": "visitor.high_value",
"timestamp": "2025-01-20T15:30:00Z",
"data": {
  "visitor_id": "vis_abc123",
  "score": 92,
  "current_page": "/pricing",
  "time_on_site": 420
}
}

Descripción general de la API del panel

Los siguientes grupos de API alimentan el panel de Zenovay. Todos los puntos finales requieren un token JWT de portador en el encabezado Authorization. Las respuestas utilizan una envolvente estándar:

{ "success": true, "data": { ... }, "timestamp": "..." }

Permisos basados en roles

Los puntos finales de API de configuración de sitios web aplican acceso basado en funciones. Los roles en orden de privilegio:

API de conversaciones

URL base: https://api.zenovay.com/api/conversations

Autenticación: Se requiere JWT de portador. Se verifica la pertenencia al equipo para todas las solicitudes.

Operaciones CRUD para conversaciones con inteligencia artificial dentro de equipos. El parámetro de consulta team_id utiliza de forma predeterminada la organización del usuario autenticado si no se proporciona.

Puntos finales

GET /conversations

Devuelve conversaciones sin contenido de mensaje para mejorar el rendimiento.

Parámetros de consulta:

• team_id (opcional) — utiliza de forma predeterminada la organización del usuario

{
"success": true,
"data": [
  {
    "id": "uuid",
    "team_id": "uuid",
    "title": "Analytics Q3 review",
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-07T14:30:00Z"
  }
]
}

GET /conversations/:id

Devuelve la conversación completa incluida la matriz de mensajes.

{
"success": true,
"data": {
  "id": "uuid",
  "team_id": "uuid",
  "title": "Analytics Q3 review",
  "messages": [
    { "role": "user", "content": "Show top pages", "timestamp": "2026-02-07T14:30:00Z" },
    { "role": "assistant", "content": "Here are your top pages...", "timestamp": "2026-02-07T14:30:01Z" }
  ],
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:30:01Z"
}
}

POST /conversations

{
"title": "New conversation",
"team_id": "uuid"
}

• title (obligatorio) — cadena no vacía
• team_id (opcional) — utiliza de forma predeterminada la organización del usuario

Respuesta: 201 con la conversación creada (incluye messages: [] vacío).

PUT /conversations/:id

{
"title": "Updated title",
"messages": [...]
}

Ambos campos son opcionales. Acepta actualizaciones parciales.

DELETE /conversations/:id

Respuesta: 200 con { "deleted": true }.

POST /conversations/:id/messages

Agrega un mensaje a la conversación. El servidor agrega una timestamp a cada mensaje.

{
"role": "user",
"content": "What were last week's top referrers?"
}

• role (obligatorio) — rol del mensaje (p. ej., "user", "assistant")
• content (obligatorio) — texto del mensaje

Respuesta: 201 con la conversación completa actualizada incluyendo todos los mensajes.

API de configuración de sitio web

URL base: https://api.zenovay.com/api/websites

Autenticación: Se requiere JWT de portador. Cada punto final aplica un rol mínimo.

Administra la configuración del sitio web, incluida la configuración general, notificaciones, exclusiones de tráfico, seguimiento de ingresos, dominios y miembros del equipo. Todas las rutas están limitadas por :websiteId.

Puntos finales

PUT /:websiteId/general

{
"domain": "example.com",
"name": "My Website",
"timezone": "America/New_York",
"primary_color": "#4F46E5",
"kpi_goal": 10000,
"public_dashboard": true,
"allowed_domains": ["example.com", "www.example.com"]
}

{
"success": true,
"data": {
  "id": "uuid",
  "domain": "example.com",
  "name": "My Website",
  "timezone": "America/New_York",
  "primary_color": "#4F46E5",
  "kpi_goal": 10000,
  "public_dashboard": true,
  "allowed_domains": ["example.com", "www.example.com"],
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/notifications

Devuelve preferencias de notificación. Si no se han establecido, devuelve un objeto predeterminado con solo website_id.

PUT /:websiteId/notifications

Acepta cualquier campo de preferencia de notificación. Utiliza un patrón upsert: crea el registro en la primera llamada, actualiza en llamadas posteriores.

GET /:websiteId/exclusions

Devuelve tanto exclusiones de IP como de ruta en una sola respuesta.

{
"success": true,
"data": {
  "ip_exclusions": [
    { "id": "uuid", "website_id": "uuid", "ip_address": "192.168.1.1", "description": "Office IP", "created_at": "..." }
  ],
  "path_exclusions": [
    { "id": "uuid", "website_id": "uuid", "path_pattern": "/admin/*", "description": "Admin pages", "created_at": "..." }
  ]
}
}

POST /:websiteId/exclusions/ip

{
"ip_address": "192.168.1.1",
"description": "Office IP"
}

• ip_address (obligatorio)
• description (opcional)

Respuesta: 201. Devuelve 409 si la IP ya está excluida.

POST /:websiteId/exclusions/path

{
"path_pattern": "/admin/*",
"description": "Admin pages"
}

• path_pattern (obligatorio)
• description (opcional)

Respuesta: 201. Devuelve 409 si el patrón de ruta ya está excluido.

PUT /:websiteId/revenue

Requiere rol de administrador.

{
"revenue_provider": "stripe",
"revenue_currency": "USD"
}

{
"success": true,
"data": {
  "id": "uuid",
  "revenue_provider": "stripe",
  "revenue_currency": "USD",
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/domains

{
"success": true,
"data": {
  "primary_domain": "example.com",
  "allowed_domains": ["example.com", "www.example.com"],
  "verification_status": "verified"
}
}

PUT /:websiteId/domains

Requiere rol de administrador.

{
"domain": "example.com",
"allowed_domains": ["example.com", "www.example.com"]
}

allowed_domains debe ser una matriz si se proporciona.

GET /:websiteId/team-members

Devuelve miembros del equipo enriquecidos con datos de perfil de usuario.

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "deactivated_at": null,
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "avatar_url": "https://..."
    }
  }
]
}

POST /:websiteId/team-members

Invita a un usuario por correo electrónico. Requiere rol de administrador.

{
"email": "[email protected]",
"role": "editor"
}

• email (obligatorio) — debe ser un usuario registrado de Zenovay
• role (opcional) — utiliza de forma predeterminada "viewer". Debe ser uno de: owner, admin, editor, viewer

Respuesta: 201. Devuelve 404 si el correo electrónico no se encuentra, 409 si ya es miembro.

PUT /:websiteId/team-members/:memberId

Actualiza el rol de un miembro. Requiere rol de administrador.

{
"role": "admin"
}

• role (obligatorio) — debe ser uno de: owner, admin, editor, viewer

DELETE /:websiteId/team-members/:memberId

Elimina un miembro del equipo (eliminación lógica). Requiere rol de administrador.

Respuesta: 200 con { "deleted": true }.

API de incorporación

URL base: https://api.zenovay.com/api/onboarding

Autenticación: Se requiere JWT de portador. Limitado al usuario (sin comprobaciones de equipo o rol).

Rastrea el progreso de incorporación del usuario. Cada usuario tiene un único registro de incorporación que persiste entre sesiones.

Puntos finales

GET /onboarding/progress

Devuelve el estado de incorporación del usuario. Si no existe un registro, devuelve valores predeterminados.

{
"success": true,
"data": {
  "user_id": "uuid",
  "current_step": "add_website",
  "completed": false,
  "data": { "welcomed": true },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:00:00Z"
}
}

POST /onboarding/progress

Utiliza un patrón upsert: crea el registro en la primera llamada, actualiza en llamadas posteriores.

{
"step": "install_tracking",
"data": { "welcomed": true, "website_added": true },
"completed": false
}

• step — guardado como current_step en la base de datos
• data — objeto JSON arbitrario para almacenar estado específico del paso
• completed — utiliza de forma predeterminada false

API de equipos

URL base: https://api.zenovay.com/api/teams

Autenticación: Se requiere JWT de portador. Se verifica la pertenencia al equipo (cualquier miembro activo puede acceder).

Puntos finales de contexto de equipo de solo lectura para permisos, estadísticas de uso y listas de miembros. Para acciones de administración de equipos (invitar, cambios de rol, eliminación), utiliza los puntos finales de miembros del equipo de la API de configuración de sitio web.

Puntos finales

GET /teams/:id/permissions

Devuelve el rol del usuario autenticado, el plan del equipo, los recuentos de uso actual y las banderas de permisos calculadas.

{
"success": true,
"data": {
  "team_id": "uuid",
  "role": "admin",
  "plan": "Pro",
  "plan_limits": {
    "maxWebsites": 5,
    "maxTeamMembers": 5,
    "eventsPerMonth": 10000,
    "dataRetentionDays": 730
  },
  "current_usage": {
    "websites": 3,
    "team_members": 5
  },
  "permissions": {
    "can_manage_billing": false,
    "can_manage_team": true,
    "can_edit_settings": true,
    "can_view": true
  }
}
}

GET /teams/:id/usage

Devuelve estadísticas de uso del período de facturación actual (mes hasta la fecha).

{
"success": true,
"data": {
  "team_id": "uuid",
  "plan": "Pro",
  "period": {
    "start": "2026-02-01T00:00:00.000Z",
    "end": "2026-02-07T12:00:00.000Z"
  },
  "usage": {
    "events": 4521,
    "events_limit": 10000,
    "websites": 3,
    "websites_limit": 10,
    "team_members": 5,
    "team_members_limit": 10
  }
}
}

GET /teams/:id/members

Devuelve miembros del equipo enriquecidos con datos de perfil de usuario.

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "name": "Jane",
      "avatar_url": "https://..."
    }
  }
]
}

API de perfil de usuario

URL base: https://api.zenovay.com/api/users

Autenticación: Se requiere JWT de portador. Limitado al usuario (solo perfil propio).

Administra el perfil y la dirección de correo electrónico del usuario autenticado.

Puntos finales

PUT /users/me/email

Punto final dedicado para cambios de correo electrónico con detección de proveedor SSO. Si el usuario se registró a través de un proveedor OAuth (Google, GitHub, etc.), la solicitud se rechaza con un mensaje para actualizar el correo electrónico a través de ese proveedor.

{
"email": "[email protected]"
}

• email (obligatorio) — debe ser un correo electrónico válido, diferente del actual

Respuesta: 200 con el registro de usuario actualizado. Devuelve 400 si el usuario es una cuenta SSO o el correo electrónico no es válido/sin cambios.

Pasos siguientes

• API externa - Análisis del lado del servidor con autenticación de clave de API
• Widgets - Widgets incrustables prediseñados
• Datos en tiempo real - Puntos finales de datos de visitantes en vivo
• Autenticación - Gestión de claves de API
• Límites de velocidad - Descripción de los límites