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

# Exemplos Praticos

> Receitas prontas de integração com o Portal Unicontrol

# Exemplos Praticos

Receitas prontas combinando varios endpoints da API. Adapte ao seu stack.

## 1. Sincronizar dashboard externo

Mostre o estado de todas as entidades do usuário num painel próprio.

```python theme={null}
import os, requests

BASE = "https://portal.unicontrol.me/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PORTAL_TOKEN']}"}

# Snapshot inicial
states = requests.get(f"{BASE}/entities/states", headers=HEADERS).json()
for s in states:
    print(f"{s['entity_id']}: {s['state']}")

# Para atualizacoes em tempo real, conecte ao WebSocket (ver /integrador/websocket)
```

## 2. Acionar luz a partir de um sistema legado

Seu ERP detectou que o turno acabou — apague tudo na loja.

```bash theme={null}
#!/bin/bash
TOKEN="pat_..."
ORG="org_loja_centro"

for entity in light.salao light.deposito switch.aviso_neon; do
  domain="${entity%%.*}"
  curl -s -X POST "https://portal.unicontrol.me/v1/service/$domain/turn_off" \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Organization-Id: $ORG" \
    -H "Content-Type: application/json" \
    -d "{\"entity_id\": \"$entity\"}"
done
```

## 3. Disparar automação por webhook do GitHub

Configure um webhook do GitHub apontando para a URL de webhook de uma automação. Quando alguem abrir uma issue, a automação envia uma notificação no Aplicativo Móvel.

1. No Portal, crie automação com gatilho **Webhook** e copie a URL.
2. No GitHub, adicione webhook em **Settings → Webhooks** com `application/json`.
3. Pronto — o body do GitHub fica disponível em `{{ trigger.json }}` nas ações.

## 4. Relatório diario de consumo (histórico)

```python theme={null}
from datetime import datetime, timedelta
import requests, os

BASE = "https://portal.unicontrol.me/v1"
TOKEN = os.environ["PORTAL_TOKEN"]

end = datetime.utcnow()
start = end - timedelta(days=1)

resp = requests.get(
    f"{BASE}/history",
    params={
        "start": start.isoformat() + "Z",
        "end": end.isoformat() + "Z",
        "entity_id": "sensor.consumo_energia"
    },
    headers={"Authorization": f"Bearer {TOKEN}"}
)

pontos = resp.json().get("sensor.consumo_energia", [])
print(f"{len(pontos)} amostras nas ultimas 24h")
```

## 5. Bot do Telegram que liga a luz

```python theme={null}
# pip install python-telegram-bot requests
import os, requests
from telegram.ext import Application, CommandHandler

PORTAL = "https://portal.unicontrol.me/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PORTAL_TOKEN']}"}

async def luz_on(update, _):
    requests.post(
        f"{PORTAL}/service/light/turn_on",
        json={"entity_id": "light.sala"},
        headers=HEADERS,
    )
    await update.message.reply_text("Luz da sala ligada")

app = Application.builder().token(os.environ["TELEGRAM_TOKEN"]).build()
app.add_handler(CommandHandler("luz_on", luz_on))
app.run_polling()
```

## 6. n8n / Zapier / Make

Configure um nodo HTTP request com:

* **Method**: `POST`
* **URL**: `https://portal.unicontrol.me/v1/service/{domain}/{service}`
* **Headers**: `Authorization: Bearer pat_...`
* **Body** (JSON): `{ "entity_id": "...", "data": { ... } }`

Para receber eventos do Portal, exponha um endpoint no n8n/Zapier e configure uma automação com ação **Chamar URL** apontando para ele.

## 7. Multi-tenant SaaS sobre o Portal

Você esta construindo um SaaS que opera sobre varias contas Portal. Padrão recomendado:

1. Cada cliente final gera um PAT e cola na sua aplicação.
2. Cada cliente seleciona qual **organização** do Portal usar.
3. Sua aplicação armazena `{ user_id, portal_token, portal_org_id }`.
4. Cada chamada usa esses três valores nos headers.

```typescript theme={null}
function portalRequest(client: ClientCreds, path: string, init: RequestInit = {}) {
  return fetch(`https://portal.unicontrol.me/v1${path}`, {
    ...init,
    headers: {
      ...init.headers,
      "Authorization": `Bearer ${client.portal_token}`,
      "X-Organization-Id": client.portal_org_id,
    },
  });
}
```

<Tip>
  Eduque seus usuários a **revogar o token** no Portal quando descontratarem sua plataforma — isso garante que você perde o acesso imediatamente.
</Tip>