Descripción General de la API REST

La API REST de Screenzzie te permite gestionar programáticamente tus pantallas de señalización digital, listas de reproducción, medios y horarios. Perfecta para integraciones, automatización y aplicaciones personalizadas.

URL Base

Todos los endpoints de la API están disponibles en:

https://www.screenzzie.com/api/v1

Autenticación

La API usa autenticación Bearer token con claves API. Incluye tu clave API en el header Authorization:

curl -X GET "https://www.screenzzie.com/api/v1/screens" \
  -H "Authorization: Bearer sk_live_tu_clave_api_aqui" \
  -H "Content-Type: application/json"

Obtener una Clave API

Ve a Configuración > Claves API en tu panel de Screenzzie
Haz clic en Crear Clave API
Elige un nombre descriptivo y selecciona los permisos
Copia tu clave inmediatamente (solo se muestra una vez!)

Mantén tu clave API segura! Nunca la expongas en código del lado del cliente o repositorios públicos.

Alcances de Claves API

Al crear una clave API, puedes elegir entre tres niveles de permisos:

Alcance	Permisos
Lectura	Ver pantallas, listas, medios, horarios
Escritura	Lectura + Crear, actualizar, eliminar recursos
Admin	Acceso completo incluyendo gestión de claves API

Límites de Tasa

Las solicitudes API están limitadas según tu plan de suscripción:

Plan	Solicitudes por Día
Business	1,000
Growth	100,000
Enterprise	Ilimitado

Los headers de límite de tasa se incluyen en todas las respuestas:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067200

Formato de Respuesta

Todas las respuestas se devuelven en formato JSON con una estructura consistente:

Respuesta Exitosa

{
  "success": true,
  "data": {
    // Datos del recurso aquí
  }
}

Respuesta Paginada

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5,
      "hasMore": true
    }
  }
}

Respuesta de Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El nombre es requerido",
    "details": { ... }
  }
}

Códigos de Error

Código	Descripción
`UNAUTHORIZED`	Clave API inválida o faltante
`FORBIDDEN`	Permisos insuficientes
`NOT_FOUND`	Recurso no encontrado
`VALIDATION_ERROR`	Parámetros de solicitud inválidos
`RATE_LIMIT_EXCEEDED`	Demasiadas solicitudes
`FEATURE_NOT_AVAILABLE`	La característica requiere un plan superior
`INTERNAL_ERROR`	Error del servidor

Endpoints Disponibles

La API proporciona los siguientes recursos:

Pantallas - Gestiona tus pantallas de señalización digital
Listas de Reproducción - Crea y gestiona listas
Medios - Accede y registra archivos de medios
Horarios - Programa contenido (plan Growth)

Siguientes Pasos

Ver la referencia de Endpoints de la API
Crear tu primera Clave API en el panel

Descripción General de la API

Acceso a la API REST