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

Introdução à API

A API REST pública do Digital Signage RDS permite-te integrar terceiros com a tua conta, automatizar tarefas ou construir o teu próprio painel.

1. Começa em 3 passos

  1. Entra no teu Perfil e abre o separador API.
  2. Cria uma nova chave dando-lhe um nome (p. ex. Zapier), escolhendo a validade e as permissões (apenas leitura ou leitura + escrita).
  3. Copia o token (rds_live_…). Não voltará a ser mostrado. Se o perderes, terás de criar outro.

2. Autenticação

Passa o token no cabeçalho Authorization como Bearer token:

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

Um bom primeiro teste é GET /me: devolve a chave e a empresa associada.

Permissões (scopes)

Cada chave tem um conjunto de permissões:

Permissão O que permite
read Listar e ler recursos (GET)
write Carregar conteúdo e modificar recursos (POST)

As chaves apenas de leitura não podem carregar imagens/vídeos nem modificar nada. Devolverão 403 insufficient_scope.

Validade e revogação

As chaves podem expirar automaticamente (30 dias, 90 dias, 1 ano ou "Sem validade"). Também as podes revogar manualmente a partir do teu perfil. Uma chave expirada ou revogada devolve 401 Token has expired ou 401 Token has been revoked.

3. Limite de taxa

60 pedidos por minuto por token. Quando ultrapassares, recebes um 429 Too Many Requests com um cabeçalho Retry-After: <segundos> que indica quanto tempo esperar.

4. Respostas

Recurso único

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

Listas (paginação por cursor)

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

Para obter a próxima página, passa o next_cursor como starting_after:

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

Parâmetros aceites nas listas:

Parâmetro Valor Por defeito
limit 1–100 20
starting_after id inteiro 0 (primeiro resultado)

Erros

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

Tipos de erro frequentes:

Código Type Quando
401 unauthorized Token ausente, mal formado, desconhecido, revogado ou expirado
403 insufficient_scope A chave não tem a permissão necessária
403 quota_exceeded Atingiste a quota da empresa (devices, images, videos)
404 not_found O recurso não existe ou não é visível para a tua conta
405 method_not_allowed Método HTTP não permitido nessa rota
413 file_too_large Ficheiro carregado excede o limite
415 unsupported_media_type Extensão ou conteúdo não suportado
429 rate_limited Mais de 60 pedidos por minuto
500 server_error Erro inesperado do servidor

5. Endpoints disponíveis

Conta

Método Rota Descrição
GET /me Dados da chave (teste rápido de auth)
GET /account Empresa: morada, contacto, limites, uso e subscrição
GET /subscription Subscrição: ciclo atual, contadores e próximo pagamento
GET /invoices Faturas (Stripe), mais recentes primeiro

Dispositivos

Método Rota Descrição
GET /devices Lista de dispositivos (exclui os retirados)
GET /devices/{id_ou_codigo} Um dispositivo (aceita id inteiro ou código RDSxxx)
GET /devices?code=RDSF8B8 Filtrar lista por código exato

Cada dispositivo expõe is_online, last_seen_at, playlist_id + playlist_name, workspace_id + workspace_name (+ pai se for sub-sede), kiosk_mode, kiosk_whitelist, branch_*, datas de contrato e mais.

Sedes (workspaces)

Método Rota Descrição
GET /workspaces Lista (sedes e sub-sedes)
GET /workspaces/{id} Uma sede com etiquetas, conteúdo padrão e mapa

Playlists

Método Rota Descrição
GET /playlists Lista de playlists
GET /playlists/{id} Playlist com contagens de dispositivos / imagens / vídeos

Imagens

Método Rota Descrição
GET /images Lista
GET /images/{id} Uma imagem (inclui url para descarregar o binário)
POST /images Carregar (requer scope write)

Vídeos

Método Rota Descrição
GET /videos Lista
GET /videos/{id} Um vídeo (inclui url para descarregar o binário)
POST /videos Carregar (requer scope write)

6. Carregar conteúdo

Os endpoints POST /images e POST /videos aceitam multipart/form-data com duas partes: file (binário, obrigatório) e name (texto opcional com o título visível para o cliente).

curl -X POST https://rds.digitalsignagerds.com/api/v1/images \
  -H "Authorization: Bearer rds_live_xxxxx" \
  -F "name=Cartaz Natal" \
  -F "file=@/caminho/para/cartaz.png"

Restrições de imagens:

Restrições de vídeos:

A resposta de um POST com sucesso é 201 Created com o recurso recém- criado (inclui id, filename, url e crc).

7. Referência interativa

Para testar cada endpoint ao vivo, ver os esquemas exatos de resposta e descarregar o OpenAPI YAML, vai à página Referência (Swagger).