Referência da API

A API External do Efflux fornece acesso de leitura aos seus dados de digital signage. Todos os endpoints requerem autenticação via API key e retornam respostas JSON.

URL Base

https://api.efflux.media/api/external

Autenticação

Todas as requisições requerem o header X-API-Key:

curl -H "X-API-Key: efflux_live_..." https://api.efflux.media/api/external/content

Veja Autenticação para detalhes.

Endpoints Disponíveis

Conteúdos

Liste e recupere seus itens de conteúdo.

Escopo: content:read

Ver Documentação

Programações

Acesse suas programações de exibição.

Escopo: schedules:read

Ver Documentação

Players

Obtenha informações sobre dispositivos player.

Escopo: players:read

Ver Documentação

Analytics

Recupere analytics e métricas.

Escopo: analytics:read

Ver Documentação

Resumo dos Endpoints

Endpoint	Método	Escopo	Descrição
`/content`	GET	`content:read`	Listar itens de conteúdo
`/content/{id}`	GET	`content:read`	Obter conteúdo por ID
`/schedules`	GET	`schedules:read`	Listar programações
`/players`	GET	`players:read`	Listar players
`/analytics/summary`	GET	`analytics:read`	Obter resumo de analytics

Códigos de Resposta Comuns

Status	Descrição
`200 OK`	Requisição bem-sucedida
`400 Bad Request`	Parâmetros de requisição inválidos
`401 Unauthorized`	API key ausente ou inválida
`403 Forbidden`	Escopo insuficiente para o endpoint
`404 Not Found`	Recurso não encontrado
`500 Internal Server Error`	Erro no servidor

Formato de Resposta

Todas as respostas bem-sucedidas retornam JSON. Endpoints de lista retornam arrays, endpoints de detalhe retornam objetos.

Timestamps

Todos os timestamps estão no formato ISO 8601 com timezone:

{
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:45:30Z"
}

UUIDs

Todos os IDs de recursos são UUIDs:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Paginação

Endpoints de lista suportam paginação opcional via parâmetros de query:

Parâmetro	Tipo	Padrão	Máximo	Descrição
`limit`	inteiro	100	500	Máximo de itens a retornar

Rate Limiting

A API implementa rate limiting para garantir uso justo. Veja Limites de Requisição para detalhes.

Erros

Todas as respostas de erro incluem uma estrutura consistente:

{
  "error": "Mensagem de erro legível",
  "code": "CODIGO_ERRO"
}

Veja Tratamento de Erros para uma lista completa de códigos de erro.