> ## 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.

# Controlando Entidades

> Como acionar luzes, interruptores, climatizadores e outros dispositivos via API

# Controlando Entidades

Toda ação sobre um dispositivo no Portal e modelada como **chamada de serviço** sobre uma entidade. O endpoint canônico e:

```
POST /v1/service/{domain}/{service}
```

## Estrutura da chamada

| Parâmetro   | Onde | Descrição                                                        |
| ----------- | ---- | ---------------------------------------------------------------- |
| `domain`    | URL  | Domínio da entidade (`light`, `switch`, `cover`, `climate`, ...) |
| `service`   | URL  | Ação (`turn_on`, `turn_off`, `set_temperature`, ...)             |
| `entity_id` | Body | ID alvo (ex: `light.sala`)                                       |
| `data`      | Body | Parâmetros adicionais (brilho, cor, posição, temperatura)        |

## Exemplo: ligar uma luz com brilho

```bash theme={null}
curl -X POST https://portal.unicontrol.me/v1/service/light/turn_on \
  -H "Authorization: Bearer pat_seu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "light.sala",
    "data": { "brightness": 200 }
  }'
```

Resposta `200`:

```json theme={null}
{ "entity_id": "light.sala", "data": { "brightness": 200 } }
```

## Exemplo: definir temperatura do ar condicionado

```bash theme={null}
curl -X POST https://portal.unicontrol.me/v1/service/climate/set_temperature \
  -H "Authorization: Bearer pat_seu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "climate.quarto",
    "data": { "temperature": 22 }
  }'
```

## Exemplo: posicionar uma cortina

```bash theme={null}
curl -X POST https://portal.unicontrol.me/v1/service/cover/set_position \
  -H "Authorization: Bearer pat_seu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "cover.sala",
    "data": { "position": 60 }
  }'
```

## Catalogo de serviços

A lista completa por domínio (light, switch, cover, climate, fan, media\_player, lock, select, button, script) esta em [Referência → Serviços](/referencia/servicos).

## Como descobrir o `entity_id`?

Liste suas entidades:

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

Ou com o estado atual já embutido:

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

<Tip>
  Você também ve o `entity_id` no painel em **Dispositivos → Entidades**, clicando na entidade.
</Tip>

## Erros tratados

| Status | Significado                                                                              |
| ------ | ---------------------------------------------------------------------------------------- |
| `200`  | Serviço executado (publicado no edge — a confirmação física chega via WebSocket)         |
| `400`  | Entidade não existe ou body inválido                                                     |
| `401`  | Token inválido                                                                           |
| `403`  | Sem permissão na entidade (org member sem `can_control`) ou domínio bloqueado pelo plano |
| `404`  | Recurso não encontrado                                                                   |
| `501`  | Serviço não implementado para a integração daquela entidade                              |

<Warning>
  O retorno `200` significa que o comando foi aceito e enviado ao edge — **não** que o dispositivo confirmou a execução. Para saber o estado real, leia o estado da entidade (veja [Lendo Estados](/integrador/lendo-estados)) ou assine o [WebSocket](/integrador/websocket).
</Warning>

## Restricoes por plano

Alguns planos limitam quais domínios você pode controlar (ex: plano Free libera apenas `cover`). Quando a chamada e bloqueada por isso, você recebe:

```json theme={null}
{
  "error": "domain_restricted",
  "message": "Seu plano permite apenas entidades dos dominios: cover"
}
```

Status: `403`.