Autenticación y claves API

Pro Plan

Asegure su acceso a la API con claves API. Cree y gestione claves para sus integraciones.

Información

La API REST de Zenovay es una función de pago. Necesita un plan Pro o superior para crear y usar claves API. Los equipos gratuitos aún pueden enviar eventos con el script de seguimiento, pero no pueden llamar a la API programática.

Métodos de autenticación

Claves API (Principal)

Autentíquese usando el encabezado X-API-Key (recomendado) o el encabezado Authorization: Bearer:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

O usando autenticación Bearer:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

Las claves API siempre comienzan con el prefijo zv_.

Creación de claves API

Las claves API en Zenovay son claves personales: cada solicitud se atribuye a usted, el usuario que creó la clave.

Paso 1: Abra la sección de claves API

Vaya a Configuración → Cuenta → Seguridad y acceso (/settings/account/security)
Encuentre la tarjeta Claves API personales
Haga clic en Nueva clave API

Página Configuración → Cuenta → Seguridad y acceso que muestra la tarjeta Claves API personales con claves existentes y el botón Nueva clave API — La página Seguridad y acceso es donde puede crear y gestionar sus claves API personales.

Paso 2: Configure la clave

El formulario de creación pide tres cosas:

┌─────────────────────────────────────────────────────┐
│ Crear clave API                                     │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Nombre de la clave                                  │
│ [ Integración de producción                ]        │
│                                                     │
│ Permisos                                            │
│ ● Acceso completo                                   │
│ ○ Solo permisos seleccionados…                      │
│     ☐ Leer  ☐ Escribir  ☐ Administrador            │
│                                                     │
│ Acceso al equipo                                    │
│ ● Todos los equipos a los que tiene acceso          │
│ ○ Solo equipos seleccionados…                       │
│                                                     │
│ [Cancelar] [Crear]                                  │
└─────────────────────────────────────────────────────┘

Permisos controla lo que la clave puede hacer. Acceso completo otorga cada alcance; u optar por alcances individuales (Leer, Escribir, Administrador). La API Externa es de solo lectura hoy, así que una clave Leer es suficiente para análisis.
Acceso al equipo controla qué espacios de trabajo puede alcanzar la clave. Déjelo en Todos los equipos a los que tiene acceso, o restrínjalo a equipos específicos.

Paso 3: Guarde su clave

Importante: la clave completa se muestra solo una vez. Cópiela antes de cerrar el diálogo.

┌─────────────────────────────────────────────────────┐
│ Su nueva clave API                                  │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Esta clave API no será visible en el futuro.       │
│ Por favor, cópiela ahora.                           │
│                                                     │
│ zv_abc123xyz789...                                 │
│                                                     │
│ [Copiar]                                            │
│                                                     │
└─────────────────────────────────────────────────────┘

Formato de la clave

Todas las claves API usan un único formato:

Prefijo: zv_
Las claves se almacenan como hashes SHA-256 por seguridad
La clave completa se muestra solo una vez en el momento de la creación

No existe un tipo de clave de prueba/sandbox separado. Para separar desarrollo y producción, cree múltiples claves con nombres descriptivos.

Permisos de la clave

Cuando crea una clave, elige sus permisos (alcances) y su acceso al equipo.

Alcance	Lo que otorga
Acceso completo	Cada alcance
Leer	Acceso de solo lectura a la API Externa
Escribir	Puntos finales de escritura (`POST`/`PATCH`/`DELETE`)
Administrador	Puntos finales solo para administradores (requiere propietario o rol de administrador en el equipo)

La superficie API Externa documentada a continuación es de solo lectura hoy, así que una clave Leer (o Acceso completo) es todo lo que necesita para análisis. La ingestión de seguimiento no usa una clave API en absoluto; usa el script de seguimiento.

A qué pueden acceder las claves API

Categoría de punto final	Puntos finales
Análisis	GET /analytics/:websiteId (resumen, visitantes, páginas, países, tecnología)
Sitios web	GET /websites, GET /websites/:websiteId
Mapas de calor	GET /heatmaps/:websiteId/pages
Reproducciones de sesión	GET /replays/:websiteId/sessions
Grupos de errores	GET /errors/:websiteId/groups
Uso	GET /usage

Restricciones de acceso al equipo

Todos los equipos

Por defecto, una clave puede alcanzar cada equipo (espacio de trabajo) a su cuenta pertenece, y cada sitio web dentro de esos equipos:

Configuración más simple
Buena para herramientas internas que leen en sus espacios de trabajo

Equipos seleccionados

Para limitar una clave, elija Solo equipos seleccionados… y seleccione los equipos a los que puede acceder. La clave funciona entonces solo para sitios web que pertenecen a esos equipos.

Casos de uso para restricciones

Escenario	Configuración
Clave para un espacio de trabajo	Solo equipos seleccionados (seleccione ese equipo)
Panel interno en todos sus espacios de trabajo	Todos los equipos a los que tiene acceso

Gestión de claves

Ver todas las claves

La tarjeta Claves API personales lista cada clave con su alcance, prefijo enmascarado y hora de último uso:

┌─────────────────────────────────────────────────────┐
│ Claves API personales             [+ Nueva clave]  │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Producción    [Acceso completo]   zv_abc…          │
│ Panel         [Leer]              zv_def…          │
│ Cliente A     [Leer]              zv_ghi…          │
│                                                     │
└─────────────────────────────────────────────────────┘

Detalles de la clave

Haga clic en una clave para abrir su vista detallada:

Nombre, alcance y acceso al equipo
Marcas de tiempo de creación y último uso
Actividad del lado del servidor (recuentos de eventos aceptados y eventos recientes para esta clave)

Editar una clave

En la vista de detalles, seleccione Editar en el menú (botón …) para renombrar la clave o cambiar sus alcances y acceso al equipo, luego guarde.

Revocar una clave

Si una clave está comprometida o no se usa:

Abra la vista detallada de la clave
En el menú …, haga clic en Revocar
Confirme

La clave se invalida inmediatamente. Para reemplazar una clave, revoque la anterior y cree una nueva.

Seguridad de las claves

Mejores prácticas

Práctica	Por qué
Usar variables de entorno	No codificar directamente
Otorgar el alcance y acceso al equipo más estrecho	Limitar el radio de explosión
Claves separadas por integración	Aislar dev/prod y clientes
Revocar claves no utilizadas	Reducir exposición
Supervisar la vista de actividad	Detectar anomalías

Variables de entorno

Almacene las claves de forma segura:

# Archivo .env (¡nunca lo incluya!)
ZENOVAY_API_KEY=zv_abc123...

// Usar en el código
const apiKey = process.env.ZENOVAY_API_KEY;

Rotación de claves

Zenovay no regenera una clave en su lugar. Para rotar:

Cree una nueva clave
Actualice sus aplicaciones para usarla
Verifique que todo funcione
Revoque la clave anterior

Usar claves API

cURL

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: {
    'X-API-Key': process.env.ZENOVAY_API_KEY,
  }
});

Python

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/websites',
    headers={'X-API-Key': api_key}
)

Solución de problemas

La API devuelve errores en la forma { "error": { "message": "...", "code": "..." } }.

Clave API faltante o inválida

{
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

Devuelve 401. Verifique:

La clave se copia correctamente, con el prefijo zv_
Sin espacios o saltos de línea adicionales
La clave no ha sido eliminada
La envió como X-API-Key o Authorization: Bearer

El plan no incluye acceso a la API

{
  "error": {
    "message": "The Zenovay API requires a paid plan. Upgrade to Pro or higher to use API keys.",
    "code": "API_PAID_PLAN_REQUIRED"
  }
}

Devuelve 403. La API Externa requiere un plan Pro o superior. Actualice su espacio de trabajo, luego cree una clave.

Prohibido para este sitio web

{
  "error": {
    "message": "Forbidden",
    "code": "FORBIDDEN"
  }
}

Devuelve 403. La clave no tiene acceso al sitio web solicitado, porque el sitio web pertenece a un equipo fuera del acceso al equipo de la clave. Utilice una clave cuyo acceso al equipo cubra ese sitio web, o amplíe el acceso al equipo de la clave.

Actividad y uso

Abra la vista detallada de una clave para ver su actividad del lado del servidor: recuentos de eventos aceptados (últimas 24 horas, últimos 7 días y todo el tiempo) y los eventos más recientes atribuidos a esa clave. Esto es útil para confirmar que una clave está activa y detectar uso inesperado.