Skip to main content

​
Lendo Estados e Histórico

O Portal mantem o estado atual de cada entidade em memória/Postgres e o histórico de mudanças em uma serie temporal (InfluxDB).

​
Estado atual de uma entidade

curl https://portal.unicontrol.me/v1/states/light.sala \
  -H "Authorization: Bearer pat_seu_token"
Resposta: 
{
  "entity_id": "light.sala",
  "state": "on",
  "attributes": {
    "friendly_name": "Luz da Sala",
    "brightness": 200,
    "color_temp": 4000
  }
}

​
Estado de todas as entidades

curl https://portal.unicontrol.me/v1/states \
  -H "Authorization: Bearer pat_seu_token"

​
Lista enriquecida (entidades + estados)

/v1/entities/states retorna metadados completos (nome, domínio, plataforma) já combinados com o estado. E o endpoint mais útil para listar tudo num dashboard de terceiros: 
curl https://portal.unicontrol.me/v1/entities/states \
  -H "Authorization: Bearer pat_seu_token"

[
  {
    "entity_id": "light.sala",
    "state": "on",
    "attributes": {
      "friendly_name": "Luz da Sala",
      "brightness": 200
    }
  },
  {
    "entity_id": "sensor.temperatura_externa",
    "state": "24.5",
    "attributes": { "friendly_name": "Temperatura Externa", "unit_of_measurement": "°C" }
  }
]
Entidades sem estado publicado retornam state: null. Isso e normal logo após a descoberta inicial — espere até o edge publicar o primeiro estado.

​
Listar entidades (sem estado)

curl https://portal.unicontrol.me/v1/entities \
  -H "Authorization: Bearer pat_seu_token"
Retorna a definição das entidades (sem o estado em si). Útil para descobrir IDs e domínios disponíveis.

​
Histórico

GET /v1/history consulta o InfluxDB pelos pontos de estado dentro de um intervalo: 
curl "https://portal.unicontrol.me/v1/history?start=2026-05-27T00:00:00Z&end=2026-05-28T00:00:00Z&entity_id=light.sala,switch.aquecedor" \
  -H "Authorization: Bearer pat_seu_token"
Parâmetros (todos obrigatorios):
QueryFormatoDescrição
startISO 8601Início do intervalo
endISO 8601Fim do intervalo
entity_idCSVUm ou mais entity_id separados por virgula
Resposta agrupada por entidade: 
{
  "light.sala": [
    { "timestamp": "2026-05-27T18:32:01Z", "state": "on" },
    { "timestamp": "2026-05-27T22:15:43Z", "state": "off" }
  ],
  "switch.aquecedor": [
    { "timestamp": "2026-05-27T18:00:00Z", "state": "on" }
  ]
}

​
Listar dispositivos

Diferente de entidades, dispositivos (device_registry) representam o objeto físico (uma lâmpada smart pode ter varios entities — luz, switch, sensor). Use: 
curl https://portal.unicontrol.me/v1/devices \
  -H "Authorization: Bearer pat_seu_token"
Para ver as entidades de um dispositivo específico: 
curl https://portal.unicontrol.me/v1/devices/{device_id} \
  -H "Authorization: Bearer pat_seu_token"

​
Padroes úteis

  • Polling de estado: a cada N segundos chame /v1/entities/states e compare. Funciona, mas e custoso. Para tempo real, prefira WebSocket.
  • Snapshot diario: chame /v1/history uma vez por dia para gerar relatórios.
  • Alertas: combine WebSocket (gatilho) + /v1/history (contexto recente) para mandar notificação quando um sensor passar de um limite.