> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Lendo Estados e Histórico

> Consulte o estado atual das entidades e o histórico de mudanças

# 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

```bash theme={null}
curl https://portal.unicontrol.me/v1/states/light.sala \
  -H "Authorization: Bearer pat_seu_token"
```

Resposta:

```json theme={null}
{
  "entity_id": "light.sala",
  "state": "on",
  "attributes": {
    "friendly_name": "Luz da Sala",
    "brightness": 200,
    "color_temp": 4000
  }
}
```

## Estado de todas as entidades

```bash theme={null}
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:

```bash theme={null}
curl https://portal.unicontrol.me/v1/entities/states \
  -H "Authorization: Bearer pat_seu_token"
```

```json theme={null}
[
  {
    "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" }
  }
]
```

<Info>
  Entidades sem estado publicado retornam `state: null`. Isso e normal logo após a descoberta inicial — espere até o edge publicar o primeiro estado.
</Info>

## Listar entidades (sem estado)

```bash theme={null}
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:

```bash theme={null}
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):

| Query       | Formato  | Descrição                                    |
| ----------- | -------- | -------------------------------------------- |
| `start`     | ISO 8601 | Início do intervalo                          |
| `end`       | ISO 8601 | Fim do intervalo                             |
| `entity_id` | CSV      | Um ou mais `entity_id` separados por virgula |

Resposta agrupada por entidade:

```json theme={null}
{
  "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:

```bash theme={null}
curl https://portal.unicontrol.me/v1/devices \
  -H "Authorization: Bearer pat_seu_token"
```

Para ver as entidades de um dispositivo específico:

```bash theme={null}
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](/integrador/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.