Referencia de Endpoints de la API

Documentación completa de todos los endpoints disponibles de la API REST.

Organización e Introspección

Obtén información sobre tu contexto actual de API y organización.

Obtener Contexto Actual

GET /api/v1/me

Devuelve información sobre tu clave API, organización, límites de tasa y funciones disponibles. Este endpoint no cuenta para tu límite de tasa.

Ejemplo de Solicitud:

curl -X GET "https://www.screenzzie.com/api/v1/me" \
  -H "Authorization: Bearer sk_live_xxx"

Ejemplo de Respuesta:

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "uuid",
      "name": "Mi Clave API",
      "keyPrefix": "sk_live_abc123",
      "scopes": ["screens:read", "screens:write", "playlists:read"],
      "expiresAt": null
    },
    "organization": {
      "id": "uuid",
      "name": "Mi Empresa",
      "planId": "growth",
      "subscriptionStatus": "active",
      "maxScreensAllowed": 50,
      "activeScreensCount": 12
    },
    "rateLimits": {
      "limit": 1000,
      "used": 45,
      "remaining": 955,
      "resetAtMs": 1704153600000
    },
    "features": {
      "sequences": true,
      "schedules": true,
      "api": true
    }
  }
}

Listar Organizaciones

GET /api/v1/organizations

Devuelve las organizaciones accesibles con tu clave API. Actualmente, cada clave API pertenece a exactamente una organización.

Parámetros de Consulta:

Ejemplo de Solicitud:

curl -X GET "https://www.screenzzie.com/api/v1/organizations" \
  -H "Authorization: Bearer sk_live_xxx"

Ejemplo de Respuesta:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Mi Empresa",
        "planId": "growth",
        "subscriptionStatus": "active",
        "maxScreensAllowed": 50,
        "activeScreensCount": 12,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasMore": false
    }
  }
}

---

Pantallas

Gestiona tus pantallas de señalización digital.

Listar Pantallas

GET /api/v1/screens

Parámetros de Consulta:

Ejemplo de Solicitud:

curl -X GET "https://www.screenzzie.com/api/v1/screens?status=online&limit=10" \
  -H "Authorization: Bearer sk_live_xxx"

Ejemplo de Respuesta:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Pantalla del Lobby",
        "status": "online",
        "orientation": "landscape",
        "resolution": "1920x1080",
        "playlistId": "uuid",
        "screenGroupId": null,
        "lastPingAt": "2024-01-01T12:00:00Z",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasMore": true
    }
  }
}

Obtener Pantalla

GET /api/v1/screens/:screenId

Parámetros de Ruta:

Crear Pantalla

POST /api/v1/screens

Cuerpo de la Solicitud:

Ejemplo de Solicitud:

curl -X POST "https://www.screenzzie.com/api/v1/screens" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sala de Conferencias A",
    "orientation": "landscape",
    "playlistId": "abc123"
  }'

Actualizar Pantalla

PATCH /api/v1/screens/:screenId

Cuerpo de la Solicitud:

Todos los campos son opcionales. Solo incluye los campos que deseas actualizar.

---

Listas de Reproducción

Gestiona listas de contenido para tus pantallas.

Listar Listas de Reproducción

GET /api/v1/playlists

Parámetros de Consulta:

Obtener Lista de Reproducción

GET /api/v1/playlists/:playlistId

Parámetros de Consulta:

Crear Lista de Reproducción

POST /api/v1/playlists

Cuerpo de la Solicitud:

Actualizar Lista de Reproducción

PATCH /api/v1/playlists/:playlistId

Cuerpo de la Solicitud:

Eliminar Lista de Reproducción

DELETE /api/v1/playlists/:playlistId

Devuelve 204 No Content en caso de éxito.

---

Medios

Accede a tu biblioteca de medios.

Listar Medios

GET /api/v1/media

Parámetros de Consulta:

Ejemplo de Respuesta:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "video-promo.mp4",
        "type": "video",
        "url": "https://...",
        "thumbnailUrl": "https://...",
        "fileSize": 15728640,
        "mimeType": "video/mp4",
        "duration": 30,
        "width": 1920,
        "height": 1080,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}

Obtener Medio

GET /api/v1/media/:mediaId

Eliminar Medio

DELETE /api/v1/media/:mediaId

Devuelve 204 No Content en caso de éxito.

---

Horarios

Programa contenido para reproducir en horarios específicos.

Listar Horarios

GET /api/v1/schedules

Parámetros de Consulta:

Obtener Horario

GET /api/v1/schedules/:scheduleId

Crear Horario

POST /api/v1/schedules

Cuerpo de la Solicitud:

Ejemplo de Solicitud:

curl -X POST "https://www.screenzzie.com/api/v1/schedules" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promociones de Fin de Semana",
    "playlistId": "abc123",
    "targetType": "all_screens",
    "dayOfWeek": [0, 6],
    "startTime": "09:00",
    "endTime": "21:00",
    "priority": 10
  }'

Actualizar Horario

PATCH /api/v1/schedules/:scheduleId

Todos los campos son opcionales.

Eliminar Horario

DELETE /api/v1/schedules/:scheduleId

Devuelve 204 No Content en caso de éxito.

---

Códigos de Estado HTTP