Autenticación

Toda solicitud debe enviar tres encabezados:

Encabezado	Valor
`X-Api-Token`	Tu API key
`X-Api-Version`	`v1`, la versión actual
`User-Agent`	Un nombre no vacío para tu integración, como `mi-integracion/1.0`

Cómo obtener tu API key

Genera tu clave en el panel, en API de Analytics. La clave identifica a tu empresa: cada consulta solo ve los reproductores y los datos de esa empresa.

Trata la clave como una contraseña. Guárdala en tu servidor, léela de una variable de entorno y nunca la subas al control de versiones ni la envíes al navegador. Si se filtra, genera una nueva en el panel.

Cómo comprobar tus credenciales

GET /quota/usage no recibe parámetros, lo que lo convierte en una buena primera llamada:

curl 'https://analytics.vturb.com/quota/usage' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: mi-integracion/1.0'

Un 200 significa que la clave funciona. El ejemplo en JavaScript se ejecuta en Node.js 18 o posterior, en tu servidor.

Cómo enviar una consulta

Las consultas son solicitudes POST con un cuerpo JSON, enviadas con los mismos tres encabezados más Content-Type:

curl -X POST 'https://analytics.vturb.com/conversions/active_platforms' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: mi-integracion/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "start_date": "2026-09-01 00:00:00",
    "timezone": "America/Sao_Paulo"
  }'

Errores de autenticación

Estado	Respuesta	Causa
`401`	`{"error":"missing token"}`	`X-Api-Token` falta o está vacío
`401`	`{"error":"invalid credentials"}`	La clave no existe, o la cuenta no puede usar la API
`401`	`{"error":"...","code":516}`	La empresa no tiene acceso a la API de Analytics
`401`	`{"error":"...","code":241}`	El plan de la clave no permite esta consulta
`403`	Página HTML	`User-Agent` falta o está vacío
`404`	`{"error_msg":"404 Route Not Found"}`	`X-Api-Version` falta o no es `v1`

El 403 y el 404 vienen del edge, antes de que la solicitud llegue a la API, por eso sus cuerpos no son errores JSON de la API.

Buenas prácticas

Envía el mismo User-Agent descriptivo desde todas las partes de tu integración; así distinguimos tu tráfico cuando pides soporte.
Reintenta un 429 después de resets_at, y un 503 tras una espera corta, con backoff exponencial. No reintentes 400, 401, 403 ni 404: fallarán de la misma forma hasta que la solicitud cambie.
Registra el estado y el cuerpo de las solicitudes que fallen. Es lo que te pedirá el soporte.

Si aun así no consigues autenticarte, contacta con nuestro soporte en help.vturb.com.