RDS
Digital Signage RDS — Documentación
ES EN CA FR PT

Introducció a l'API

L'API REST pública de Digital Signage RDS et permet integrar tercers amb el teu compte, automatitzar tasques o construir el teu propi panell.

1. Comença en 3 passos

  1. Entra al teu Perfil i obre la pestanya API.
  2. Crea una nova clau amb un nom (p. ex. Zapier), tria la caducitat i els permisos (només lectura o lectura + escriptura).
  3. Copia el token (rds_live_…). No es tornarà a mostrar. Si el perds, n'has de crear un altre.

2. Autenticació

Passa el token a la capçalera Authorization com a Bearer token:

curl -H "Authorization: Bearer rds_live_xxxxx" \
     https://rds.digitalsignagerds.com/api/v1/me

Una bona primera prova és GET /me: et torna la clau i l'empresa associada.

Permisos (scopes)

Cada clau té un conjunt de permisos:

Permís Què permet
read Llistar i llegir recursos (GET)
write Pujar contingut i modificar recursos (POST)

Les claus de només lectura no poden pujar imatges/vídeos ni modificar res. Tornaran 403 insufficient_scope.

Caducitat i revocació

Les claus poden caducar automàticament (30 dies, 90 dies, 1 any o "Sense caducitat"). També les pots revocar manualment des del teu perfil. Una clau caducada o revocada torna 401 Token has expired o 401 Token has been revoked.

3. Límit de freqüència

60 peticions per minut per token. Quan el superis, rebràs un 429 Too Many Requests amb una capçalera Retry-After: <segons> que indica quant has d'esperar.

4. Respostes

Recurs únic

{
  "object": "device",
  "id": 1138,
  "code": "RDSDF25",
  "...": "..."
}

Llistes (paginació amb cursor)

{
  "object": "list",
  "url": "/api/v1/devices",
  "data": [ { ... }, { ... } ],
  "has_more": true,
  "next_cursor": "1142"
}

Per obtenir la pàgina següent, passa el next_cursor com a starting_after:

GET /api/v1/devices?starting_after=1142&limit=20

Paràmetres acceptats a les llistes:

Paràmetre Valor Per defecte
limit 1–100 20
starting_after id enter 0 (primer resultat)

Errors

{
  "error": {
    "type": "unauthorized",
    "message": "Invalid token"
  }
}

Tipus d'error freqüents:

Codi Type Quan
401 unauthorized Token absent, malformat, desconegut, revocat o caducat
403 insufficient_scope La clau no té el permís necessari
403 quota_exceeded Has arribat al límit de l'empresa (devices, images, videos)
404 not_found El recurs no existeix o no és visible per a la teva empresa
405 method_not_allowed Mètode HTTP no admès en aquesta ruta
413 file_too_large Fitxer pujat supera el límit
415 unsupported_media_type Extensió o contingut del fitxer no admès
429 rate_limited Has superat les 60 peticions per minut
500 server_error Error inesperat del servidor

5. Endpoints disponibles

Compte

Mètode Ruta Descripció
GET /me Dades de la clau (prova ràpida d'auth)
GET /account Empresa: adreça, contacte, límits, ús i subscripció
GET /subscription Subscripció: cicle actual, comptadors i proper pagament
GET /invoices Factures (Stripe), més recents primer

Dispositius

Mètode Ruta Descripció
GET /devices Llista de dispositius (exclou els retirats)
GET /devices/{id_o_codi} Un dispositiu (admet id enter o codi RDSxxx)
GET /devices?code=RDSF8B8 Filtra llista per codi exacte

Cada dispositiu exposa is_online, last_seen_at, playlist_id + playlist_name, workspace_id + workspace_name (+ pare si és sub-seu), kiosk_mode, kiosk_whitelist, branch_*, dates de contracte i més.

Seus (workspaces)

Mètode Ruta Descripció
GET /workspaces Llista (seus i sub-seus)
GET /workspaces/{id} Una seu amb etiquetes, contingut per defecte i mapa

Playlists

Mètode Ruta Descripció
GET /playlists Llista de playlists
GET /playlists/{id} Playlist amb comptatge de dispositius / imatges / vídeos

Imatges

Mètode Ruta Descripció
GET /images Llista
GET /images/{id} Una imatge (inclou url per descarregar el binari)
POST /images Pujar (requereix scope write)

Vídeos

Mètode Ruta Descripció
GET /videos Llista
GET /videos/{id} Un vídeo (inclou url per descarregar el binari)
POST /videos Pujar (requereix scope write)

6. Pujar contingut

Els endpoints POST /images i POST /videos accepten multipart/form-data amb dues parts: file (binari, obligatori) i name (text opcional amb el títol visible per al client).

curl -X POST https://rds.digitalsignagerds.com/api/v1/images \
  -H "Authorization: Bearer rds_live_xxxxx" \
  -F "name=Cartell Nadal" \
  -F "file=@/ruta/al/cartell.png"

Restriccions d'imatges:

Restriccions de vídeos:

La resposta d'un POST exitós és 201 Created amb el recurs acabat de crear (inclou id, filename, url i crc).

7. Referència interactiva

Per provar cada endpoint en directe, veure els esquemes exactes de resposta i descarregar l'OpenAPI YAML, vés a la pàgina Referència (Swagger).