Autenticacion

La API de Zelta Grid usa tokens Bearer para autenticar todas las peticiones. Obtiene un token desde el panel de administracion y usalo en cada llamada a la API.

URL base

https://api.zelta.dev/grid/v1

Obtener un token de API

1. Inicia sesion en .
2. Ve a Configuracion > API > Tokens.
3. Haz clic en Generar token.
4. Asigna un nombre descriptivo (ej: Integracion CMS, App movil).
5. Selecciona los permisos (scopes) necesarios.
6. Haz clic en Crear.
7. Copia el token generado inmediatamente.

Seguridad

El token solo se muestra una vez al momento de crearlo. Si lo pierdes, deberas generar uno nuevo y revocar el anterior. Nunca compartas tus tokens de API ni los incluyas en codigo fuente publico.

Usar el token

Incluye el token en el header Authorization de todas tus peticiones:

curl -X GET https://api.zelta.dev/grid/v1/screens \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json"

Ejemplo con respuesta

curl -X GET https://api.zelta.dev/grid/v1/screens \
  -H "Authorization: Bearer grd_sk_a1b2c3d4e5f6..."

{
  "data": [
    {
      "id": "scr_abc123",
      "name": "Recepcion - Planta Baja",
      "status": "online",
      "current_playlist": "pl_xyz789"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "per_page": 25
  }
}

Scopes disponibles

Los scopes controlan que operaciones puede realizar tu token:

Scope	Descripcion
grid:screens:read	Consultar pantallas, estados y configuraciones
grid:screens:write	Vincular, configurar y ejecutar acciones en pantallas
grid:media:read	Consultar la biblioteca de medios
grid:media:write	Subir, editar y eliminar archivos multimedia
grid:playlists:read	Consultar playlists y layouts
grid:playlists:write	Crear, editar y eliminar playlists y layouts
grid:schedules:read	Consultar programaciones
grid:schedules:write	Crear, editar y eliminar programaciones
grid:analytics:read	Consultar analiticas y reportes de reproduccion
grid:admin	Administracion completa (incluye todos los scopes anteriores)

Principio de minimo privilegio

Solicita unicamente los scopes que tu integracion necesita. Por ejemplo, si solo necesitas consultar el estado de las pantallas, usa grid:screens:read en lugar de grid:admin.

Limites de la API

Plan	Peticiones por minuto	Peticiones por dia
Starter	60	10,000
Pro	300	50,000
Enterprise	1,000	Ilimitadas

Headers de rate limiting

Cada respuesta incluye informacion sobre tu uso actual:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1709145600

Header	Descripcion
X-RateLimit-Limit	Maximo de peticiones permitidas en la ventana actual
X-RateLimit-Remaining	Peticiones restantes en la ventana actual
X-RateLimit-Reset	Timestamp Unix de cuando se reinicia el contador

Errores de autenticacion

Codigo HTTP	Error	Descripcion
401	unauthorized	Token ausente, expirado o invalido
403	forbidden	El token no tiene los scopes necesarios
429	rate_limited	Se excedio el limite de peticiones

Ejemplo de error

{
  "error": "unauthorized",
  "message": "El token de acceso es invalido o ha sido revocado.",
  "hint": "Genera un nuevo token desde Configuracion > API > Tokens."
}

Revocar un token

Para revocar un token activo:

1. Ve a Configuracion > API > Tokens.
2. Localiza el token que deseas revocar.
3. Haz clic en Revocar.
4. Confirma la revocacion.

Rotacion de tokens

Se recomienda rotar tus tokens de API periodicamente (cada 90 dias). Crea un nuevo token antes de revocar el anterior para evitar interrupciones en tus integraciones.