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

Introduzione all'API

L'API REST pubblica di Digital Signage RDS le permette di integrare servizi di terzi con il suo account, automatizzare attività o costruire un pannello di controllo proprio.

1. Iniziare in 3 passi

  1. Entri nel suo Profilo e apra la scheda API.
  2. Crei una nuova chiave assegnandole un nome (ad es. Zapier), scegliendo la scadenza e i permessi (sola lettura oppure lettura + scrittura).
  3. Copi il token (rds_live_…). Non verrà mostrato di nuovo. Se lo perde, dovrà crearne un altro.

2. Autenticazione

Passi il token nell'intestazione Authorization come Bearer token:

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

Un buon primo test è GET /me: restituisce la chiave e l'azienda associata.

Permessi (scope)

Ogni chiave ha un insieme di permessi:

Permesso Cosa consente
read Elencare e leggere le risorse (GET)
write Caricare contenuti e modificare le risorse (POST)

Le chiavi di sola lettura non possono caricare immagini/video né modificare alcunché. Restituiranno 403 insufficient_scope.

Scadenza e revoca

Le chiavi possono scadere automaticamente (30 giorni, 90 giorni, 1 anno o "Senza scadenza"). Può anche revocarle manualmente dal suo profilo. Una chiave scaduta o revocata restituisce 401 Token has expired oppure 401 Token has been revoked.

3. Limite di frequenza

60 richieste al minuto per token. Quando supera il limite, riceverà un 429 Too Many Requests con un'intestazione Retry-After: <segundos> che indica quanto attendere.

4. Risposte

Risorsa singola

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

Elenchi (paginazione con cursore)

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

Per ottenere la pagina successiva, passi il next_cursor come starting_after:

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

Parametri accettati negli elenchi:

Parametro Valore Predefinito
limit 1–100 20
starting_after id intero 0 (primo risultato)

Errori

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

Tipi di errore frequenti:

Codice Type Quando
401 unauthorized Token assente, malformato, sconosciuto, revocato o scaduto
403 insufficient_scope La chiave non ha il permesso necessario
403 quota_exceeded Ha raggiunto la quota dell'azienda (devices, images, videos)
404 not_found La risorsa non esiste o non è visibile per la sua azienda
405 method_not_allowed Metodo HTTP non ammesso su quel percorso
413 file_too_large Il file caricato supera il limite
415 unsupported_media_type Estensione o contenuto del file non ammessi
429 rate_limited Ha superato le 60 richieste al minuto
500 server_error Errore imprevisto del server

5. Endpoint disponibili

Account

Metodo Percorso Descrizione
GET /me Dati della chiave (test rapido di autenticazione)
GET /account Azienda: indirizzo, contatto, limiti, utilizzo e abbonamento
GET /subscription Abbonamento: ciclo attuale, contatori e prossimo pagamento
GET /invoices Fatture (Stripe), dalle più recenti

Dispositivi

Metodo Percorso Descrizione
GET /devices Elenco dei dispositivi (esclusi quelli ritirati)
GET /devices/{id_o_codigo} Un dispositivo (accetta id intero o codice RDSxxx)
GET /devices?code=RDSF8B8 Filtra l'elenco per codice esatto

Ogni dispositivo espone is_online, last_seen_at, playlist_id + playlist_name, workspace_id + workspace_name (+ il padre se è una sotto-sede), kiosk_mode, kiosk_whitelist, branch_*, le date di contratto e altro ancora.

Sedi (workspaces)

Metodo Percorso Descrizione
GET /workspaces Elenco (sedi e sotto-sedi)
GET /workspaces/{id} Una sede con etichette, contenuto predefinito e mappa

Playlist

Metodo Percorso Descrizione
GET /playlists Elenco delle playlist
GET /playlists/{id} Playlist con il conteggio di dispositivi / immagini / video

Immagini

Metodo Percorso Descrizione
GET /images Elenco
GET /images/{id} Un'immagine (include url per scaricare il binario)
POST /images Caricare (richiede lo scope write)

Video

Metodo Percorso Descrizione
GET /videos Elenco
GET /videos/{id} Un video (include url per scaricare il binario)
POST /videos Caricare (richiede lo scope write)

6. Caricare contenuti

Gli endpoint POST /images e POST /videos accettano multipart/form-data con due parti: file (binario, obbligatorio) e name (testo facoltativo con il titolo visibile per il cliente).

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

Restrizioni per le immagini:

Restrizioni per i video:

La risposta di un POST andato a buon fine è 201 Created con la risorsa appena creata (include id, filename, url e crc).

7. Riferimento interattivo

Per provare ogni endpoint in tempo reale, consultare gli schemi esatti di risposta e scaricare l'OpenAPI YAML, vada alla pagina Riferimento (Swagger).