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

# Manual do Integrador

> Integre sistemas externos ao Portal Unicontrol pela API REST

# Manual do Integrador

Este manual e destinado a desenvolvedores que querem integrar sistemas externos (CRMs, ERPs, scripts, hubs caseiros, dashboards de terceiros, automações industriais) ao **Portal Unicontrol** através da nossa API pública.

<Info>
  A base da API e `https://portal.unicontrol.me/v1`. Toda especificação OpenAPI está disponível em [API Reference](/api-reference) e em `https://portal.unicontrol.me/v1/openapi`.
</Info>

## O que você pode fazer pela API

<CardGroup cols={2}>
  <Card title="Controlar dispositivos" icon="lightbulb" href="/integrador/controlando-entidades">
    Ligar, desligar, ajustar brilho, temperatura, posição de cortinas, etc.
  </Card>

  <Card title="Ler estados" icon="eye" href="/integrador/lendo-estados">
    Consultar o estado atual de qualquer entidade e histórico de mudanças.
  </Card>

  <Card title="Disparar automações" icon="bolt" href="/integrador/automacoes-e-scripts">
    Acionar automações e scripts a partir de eventos externos.
  </Card>

  <Card title="Receber eventos" icon="satellite-dish" href="/integrador/websocket">
    Assinar atualizações de estado em tempo real via WebSocket.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integrador/webhooks">
    Aceitar gatilhos vindos do Portal para o seu sistema (ou o contrario).
  </Card>

  <Card title="Organizações" icon="building" href="/integrador/organizacoes">
    Operar em nome de uma organização compartilhada.
  </Card>
</CardGroup>

## Antes de começar

1. **Crie uma conta** em [portal.unicontrol.me](https://portal.unicontrol.me).
2. **Configure uma integração** e descubra alguns dispositivos — sem entidades, não ha o que controlar.
3. **Gere um Token de Acesso Pessoal (PAT)** em **Perfil → Segurança**. Veja [Autenticação](/integrador/autenticacao).
4. **Anote os `entity_id`** das entidades que pretende controlar (em **Dispositivos → Entidades**).

## Convencoes deste manual

* Todos os exemplos usam `curl` com o token no header `Authorization: Bearer ...`.
* Todas as respostas são **JSON**.
* Datas seguem **ISO 8601** com timezone (`2026-05-28T14:00:00-03:00`).
* IDs de entidades seguem o padrão `dominio.objeto` (ex: `light.sala`, `switch.aquecedor`).

## Limites e SLAs

Cada plano tem limites diferentes para número de automações, scripts, entidades expostas, requisições por minuto e domínios permitidos. Veja [Limites e Erros](/integrador/limites-e-erros) e [Limites por Plano](/referencia/limites-por-plano).

<Tip>
  Para integrações que rodam em servidor (backend para backend), use um PAT **sem expiração** dedicado aquela integração. Para integrações do lado do cliente (browser, mobile de terceiros), prefira tokens de curta validade.
</Tip>