Reference des endpoints API

Documentation complete pour tous les endpoints de l'API REST disponibles.

Organisation et introspection

Obtenez des informations sur votre contexte API actuel et votre organisation.

Obtenir le contexte actuel

GET /api/v1/me

Retourne des informations sur votre cle API, organisation, limites de debit et fonctionnalites disponibles. Cet endpoint ne compte pas dans votre limite de debit.

Exemple de requete :

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

Exemple de reponse :

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "uuid",
      "name": "Ma cle API",
      "keyPrefix": "sk_live_abc123",
      "scopes": ["screens:read", "screens:write", "playlists:read"],
      "expiresAt": null,
      "lastUsedAt": "2024-01-15T10:30:00Z"
    },
    "organization": {
      "id": "uuid",
      "name": "Mon Entreprise",
      "planId": "growth",
      "subscriptionStatus": "active",
      "trialEndsAt": null,
      "maxScreensAllowed": 50,
      "activeScreensCount": 12
    },
    "rateLimits": {
      "limit": 100000,
      "used": 45,
      "remaining": 99955,
      "resetAtMs": 1704153600000
    },
    "features": {
      "sequences": true,
      "schedules": true,
      "api": true
    }
  }
}

Lister les organisations

GET /api/v1/organizations

Retourne les organisations accessibles avec votre cle API. Actuellement, chaque cle API appartient a exactement une organisation.

Parametres de requete :

Exemple de requete :

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

Exemple de reponse :

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Mon Entreprise",
        "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
    }
  }
}

---

Ecrans

Gerez vos ecrans d'affichage numerique.

Lister les ecrans

GET /api/v1/screens

Parametres de requete :

Exemple de requete :

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

Exemple de reponse :

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Affichage Hall",
        "description": "Ecran de l'entree principale",
        "isActive": true,
        "isOnline": true,
        "lastSeenAt": "2024-01-01T12:00:00Z",
        "orientation": "landscape",
        "rotation": "0",
        "timezone": "Europe/Madrid",
        "location": "Batiment A, Etage 1",
        "cityName": "Madrid",
        "latitude": 40.4168,
        "longitude": -3.7038,
        "workspaceId": "uuid",
        "screenGroupId": null,
        "currentPlaylistId": "uuid",
        "currentSequenceId": null,
        "defaultPlaylistId": "uuid",
        "defaultSequenceId": null,
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasMore": true
    }
  }
}

Obtenir un ecran

GET /api/v1/screens/:screenId

Parametres de chemin :

Exemple de reponse :

Retourne un objet ecran unique avec la meme structure que la reponse de liste.

Creer un ecran

POST /api/v1/screens

Corps de la requete :

Exemple de requete :

curl -X POST "https://www.screenzzie.com/api/v1/screens" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salle de conference A",
    "orientation": "landscape",
    "rotation": "0",
    "timezone": "Europe/Madrid",
    "location": "Batiment B, Salle 101"
  }'

Exemple de reponse :

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Salle de conference A",
    "description": null,
    "isActive": true,
    "isOnline": false,
    "lastSeenAt": null,
    "orientation": "landscape",
    "rotation": "0",
    "timezone": "Europe/Madrid",
    "location": "Batiment B, Salle 101",
    "cityName": null,
    "latitude": null,
    "longitude": null,
    "workspaceId": null,
    "screenGroupId": null,
    "currentPlaylistId": null,
    "currentSequenceId": null,
    "defaultPlaylistId": null,
    "defaultSequenceId": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Mettre a jour un ecran

PATCH /api/v1/screens/:screenId

Tous les champs sont optionnels. Incluez uniquement les champs que vous souhaitez mettre a jour.

Corps de la requete :

Exemple de requete :

curl -X PATCH "https://www.screenzzie.com/api/v1/screens/abc123" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nom d affichage mis a jour",
    "currentPlaylistId": "playlist-uuid"
  }'

---

Playlists

Gerez les playlists de contenu pour vos ecrans.

Lister les playlists

GET /api/v1/playlists

Parametres de requete :

Exemple de reponse :

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Contenu principal",
        "description": "Playlist principale pour les ecrans du hall",
        "itemCount": 5,
        "totalDuration": 120,
        "workspaceId": null,
        "createdBy": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}

Obtenir une playlist

GET /api/v1/playlists/:playlistId

Retourne la playlist avec ses elements. Les elements sont toujours inclus dans la reponse.

Parametres de chemin :

Exemple de reponse :

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Contenu principal",
    "description": "Playlist principale pour les ecrans du hall",
    "itemCount": 2,
    "totalDuration": 45,
    "workspaceId": null,
    "createdBy": "user-uuid",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T12:00:00Z",
    "items": [
      {
        "id": "item-uuid-1",
        "position": 0,
        "duration": 15,
        "itemType": "media",
        "mediaId": "media-uuid",
        "config": null,
        "createdAt": "2024-01-01T00:00:00Z"
      },
      {
        "id": "item-uuid-2",
        "position": 1,
        "duration": 30,
        "itemType": "website",
        "mediaId": null,
        "config": { "url": "https://example.com" },
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Creer une playlist

POST /api/v1/playlists

Corps de la requete :

Exemple de requete :

curl -X POST "https://www.screenzzie.com/api/v1/playlists" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promotions de fetes",
    "description": "Contenu saisonnier pour decembre"
  }'

Mettre a jour une playlist

PATCH /api/v1/playlists/:playlistId

Corps de la requete :

Supprimer une playlist

DELETE /api/v1/playlists/:playlistId

Retourne 204 No Content en cas de succes.

---

Medias

Accedez et enregistrez des fichiers medias dans votre bibliotheque.

Lister les medias

GET /api/v1/media

Parametres de requete :

Exemple de reponse :

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "video-promo.mp4",
        "type": "video",
        "fileUrl": "https://...",
        "thumbnailUrl": "https://...",
        "fileSize": 15728640,
        "duration": 30,
        "folderId": null,
        "workspaceId": null,
        "uploadedBy": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}

Obtenir un media

GET /api/v1/media/:mediaId

Retourne un objet media unique avec la meme structure que la reponse de liste.

Enregistrer un media

POST /api/v1/media

Enregistre un fichier media qui a deja ete televerse vers le stockage. Cet endpoint ne gere pas les televersements de fichiers directement - utilisez le tableau de bord web pour les televersements de fichiers.

Corps de la requete :

Exemple de requete :

curl -X POST "https://www.screenzzie.com/api/v1/media" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Logo entreprise",
    "type": "image",
    "fileUrl": "https://votre-stockage.com/logo.png",
    "thumbnailUrl": "https://votre-stockage.com/logo-thumb.png",
    "fileSize": 102400
  }'

Supprimer un media

DELETE /api/v1/media/:mediaId

Retourne 204 No Content en cas de succes.

---

Planifications

Planifiez du contenu a diffuser a des moments specifiques.

Lister les planifications

GET /api/v1/schedules

Parametres de requete :

Exemple de reponse :

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Promotions du week-end",
        "playlistId": "playlist-uuid",
        "sequenceId": null,
        "screenId": null,
        "screenGroupId": null,
        "targetType": "all_screens",
        "dayOfWeek": [0, 6],
        "startTime": "09:00",
        "endTime": "21:00",
        "startDate": null,
        "endDate": null,
        "priority": 10,
        "isActive": true,
        "color": "#3B82F6",
        "workspaceId": null,
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}

Obtenir une planification

GET /api/v1/schedules/:scheduleId

Retourne un objet planification unique avec la meme structure que la reponse de liste.

Creer une planification

POST /api/v1/schedules

Corps de la requete :

*Soit playlistId soit sequenceId doit etre fourni pour planifier du contenu.

Exigences conditionnelles par type de cible :

Exemple de requete :

curl -X POST "https://www.screenzzie.com/api/v1/schedules" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promotions du week-end",
    "playlistId": "abc123",
    "targetType": "all_screens",
    "dayOfWeek": [0, 6],
    "startTime": "09:00",
    "endTime": "21:00",
    "priority": 10,
    "color": "#3B82F6"
  }'

Mettre a jour une planification

PATCH /api/v1/schedules/:scheduleId

Tous les champs sont optionnels. Utilise les memes definitions de champs que Creer une planification.

Supprimer une planification

DELETE /api/v1/schedules/:scheduleId

Retourne 204 No Content en cas de succes.

---

Codes de statut HTTP