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) |
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 }
}'
200:
{ "entity_id": "light.sala", "data": { "brightness": 200 } }
Exemplo: definir temperatura do ar condicionado
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
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.
Como descobrir o entity_id?
Liste suas entidades:
curl https://portal.unicontrol.me/v1/entities \
-H "Authorization: Bearer pat_seu_token"
curl https://portal.unicontrol.me/v1/entities/states \
-H "Authorization: Bearer pat_seu_token"
Você também ve o entity_id no painel em Dispositivos → Entidades, clicando na entidade.
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 |
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) ou assine o WebSocket. 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:
{
"error": "domain_restricted",
"message": "Seu plano permite apenas entidades dos dominios: cover"
}
403.