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

Einführung in die API

Über die öffentliche REST-API von Digital Signage RDS können Sie Drittsysteme mit Ihrem Konto verbinden, Aufgaben automatisieren oder ein eigenes Panel bauen.

1. In 3 Schritten loslegen

  1. Öffnen Sie Ihr Profil und wechseln Sie zur Registerkarte API.
  2. Erstellen Sie einen neuen Schlüssel: Vergeben Sie einen Namen (z. B. Zapier) und wählen Sie die Gültigkeitsdauer sowie die Berechtigungen (nur lesen oder lesen + schreiben).
  3. Kopieren Sie das Token (rds_live_…). Es wird nicht erneut angezeigt. Geht es verloren, müssen Sie einen neuen Schlüssel erstellen.

2. Authentifizierung

Übergeben Sie das Token im Header Authorization als Bearer-Token:

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

Ein guter erster Test ist GET /me: Es liefert den Schlüssel und das zugehörige Unternehmen zurück.

Berechtigungen (Scopes)

Jeder Schlüssel besitzt eine Reihe von Berechtigungen:

Berechtigung Was sie erlaubt
read Ressourcen auflisten und lesen (GET)
write Inhalte hochladen und Ressourcen ändern (POST)

Schlüssel mit reinem Lesezugriff können keine Bilder/Videos hochladen und nichts ändern. Sie liefern 403 insufficient_scope zurück.

Gültigkeitsdauer und Widerruf

Schlüssel können automatisch ablaufen (30 Tage, 90 Tage, 1 Jahr oder "Unbegrenzt"). Sie können sie außerdem in Ihrem Profil manuell widerrufen. Ein abgelaufener oder widerrufener Schlüssel liefert 401 Token has expired oder 401 Token has been revoked.

3. Ratenbegrenzung

60 Anfragen pro Minute je Token. Bei Überschreitung erhalten Sie ein 429 Too Many Requests mit einem Header Retry-After: <Sekunden>, der angibt, wie lange Sie warten müssen.

4. Antworten

Einzelne Ressource

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

Listen (Paginierung per Cursor)

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

Um die nächste Seite abzurufen, übergeben Sie den next_cursor als starting_after:

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

In Listen akzeptierte Parameter:

Parameter Wert Standard
limit 1–100 20
starting_after Ganzzahlige ID 0 (erstes Ergebnis)

Fehler

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

Häufige Fehlertypen:

Code Type Wann
401 unauthorized Token fehlt, ist fehlerhaft, unbekannt, widerrufen oder abgelaufen
403 insufficient_scope Der Schlüssel hat nicht die nötige Berechtigung
403 quota_exceeded Das Kontingent des Unternehmens ist erreicht (devices, images, videos)
404 not_found Die Ressource existiert nicht oder ist für Ihr Unternehmen nicht sichtbar
405 method_not_allowed HTTP-Methode auf diesem Pfad nicht zulässig
413 file_too_large Die hochgeladene Datei überschreitet das Limit
415 unsupported_media_type Dateiendung oder Dateiinhalt nicht zulässig
429 rate_limited Sie haben die 60 Anfragen pro Minute überschritten
500 server_error Unerwarteter Serverfehler

5. Verfügbare Endpoints

Konto

Methode Pfad Beschreibung
GET /me Daten des Schlüssels (schneller Auth-Test)
GET /account Unternehmen: Adresse, Kontakt, Limits, Nutzung und Abonnement
GET /subscription Abonnement: aktueller Zyklus, Zähler und nächste Zahlung
GET /invoices Rechnungen (Stripe), neueste zuerst

Geräte

Methode Pfad Beschreibung
GET /devices Liste der Geräte (ausgemusterte ausgenommen)
GET /devices/{id_o_codigo} Ein Gerät (akzeptiert ganzzahlige ID oder Code RDSxxx)
GET /devices?code=RDSF8B8 Liste nach exaktem Code filtern

Jedes Gerät liefert is_online, last_seen_at, playlist_id + playlist_name, workspace_id + workspace_name (+ übergeordneter Bereich bei einem Unterstandort), kiosk_mode, kiosk_whitelist, branch_*, Vertragsdaten und mehr.

Standorte (Workspaces)

Methode Pfad Beschreibung
GET /workspaces Liste (Standorte und Unterstandorte)
GET /workspaces/{id} Ein Standort mit Tags, Standardinhalt und Karte

Playlists

Methode Pfad Beschreibung
GET /playlists Liste der Playlists
GET /playlists/{id} Playlist mit Anzahl der Geräte / Bilder / Videos

Bilder

Methode Pfad Beschreibung
GET /images Liste
GET /images/{id} Ein Bild (enthält url zum Herunterladen der Binärdatei)
POST /images Hochladen (erfordert Scope write)

Videos

Methode Pfad Beschreibung
GET /videos Liste
GET /videos/{id} Ein Video (enthält url zum Herunterladen der Binärdatei)
POST /videos Hochladen (erfordert Scope write)

6. Inhalte hochladen

Die Endpoints POST /images und POST /videos akzeptieren multipart/form-data mit zwei Teilen: file (Binärdatei, erforderlich) und name (optionaler Text mit dem für den Kunden sichtbaren Titel).

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"

Einschränkungen für Bilder:

Einschränkungen für Videos:

Die Antwort auf ein erfolgreiches POST ist 201 Created mit der soeben erstellten Ressource (enthält id, filename, url und crc).

7. Interaktive Referenz

Um jeden Endpoint live auszuprobieren, die genauen Antwortschemata einzusehen und das OpenAPI-YAML herunterzuladen, öffnen Sie die Seite Referenz (Swagger).