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

# Automações e Scripts

> Liste, dispare e gerencie automações e scripts pela API

# Automações e Scripts

**Automações** são regras com gatilho + condições + ações. **Scripts** são sequências de ações reutilizáveis. Os dois podem ser disparados pela API.

## Listar automações

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

Resposta:

```json theme={null}
[
  {
    "id": 1,
    "name": "Ligar aquecedor ao anoitecer",
    "trigger": { "platform": "sun", "event": "sunset" },
    "conditions": [],
    "actions": [
      { "type": "call_service", "entity_id": "switch.aquecedor", "service": "turn_on" }
    ],
    "enabled": true
  }
]
```

## Disparar uma automação manualmente

```bash theme={null}
curl -X POST https://portal.unicontrol.me/v1/automations/{id}/trigger \
  -H "Authorization: Bearer pat_seu_token"
```

Isso executa as **ações** da automação ignorando o gatilho. Útil para botões "Executar agora" em integrações.

## Disparar via webhook

Automações podem ter o gatilho **Webhook**. Quando configuradas assim, recebem um `webhook_id` próprio:

```bash theme={null}
curl -X POST https://portal.unicontrol.me/v1/automations/webhook/{webhook_id} \
  -H "Content-Type: application/json" \
  -d '{ "valor": 42, "origem": "meu-sistema" }'
```

<Info>
  **Webhooks de automação não exigem autenticação** — o `webhook_id` em si e o segredo. Trate-o como uma chave secreta e não o exponha publicamente.
</Info>

O payload do body fica disponível para as ações da automação (templates `{{ trigger.json.valor }}`).

Veja mais em [Webhooks](/integrador/webhooks).

## Habilitar / desabilitar automação

```bash theme={null}
# Ativar
curl -X POST https://portal.unicontrol.me/v1/automations/{id}/enable \
  -H "Authorization: Bearer pat_seu_token"

# Desativar
curl -X POST https://portal.unicontrol.me/v1/automations/{id}/disable \
  -H "Authorization: Bearer pat_seu_token"
```

## Histórico de execuções

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

Retorna as últimas execuções com status, duração e (opcionalmente) o trace passo-a-passo.

## Scripts

Scripts seguem o mesmo padrão de listagem e disparo:

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

# Disparar
curl -X POST https://portal.unicontrol.me/v1/scripts/{id}/trigger \
  -H "Authorization: Bearer pat_seu_token"
```

Scripts também podem ser chamados como **serviço**, útil quando você já tem o `entity_id`:

```bash theme={null}
curl -X POST https://portal.unicontrol.me/v1/service/script/press \
  -H "Authorization: Bearer pat_seu_token" \
  -H "Content-Type: application/json" \
  -d '{ "entity_id": "script.script.123" }'
```

## Quando usar cada um?

| Cenário                                            | Recomendacao                                       |
| -------------------------------------------------- | -------------------------------------------------- |
| Acionar **uma** entidade                           | Chame `/v1/service/{domain}/{service}` diretamente |
| Sequência de ações reutilizável                    | Crie um **script** e dispare por API               |
| Reagir a evento externo (webhook)                  | Crie uma **automação** com gatilho Webhook         |
| Lógica condicional ("se temperatura > X então...") | Crie uma **automação** com condições               |

<Tip>
  Em integrações multi-usuário, evite criar/editar automações pela API sem autorização explicita do usuário — automações mudam comportamento do ambiente físico dele.
</Tip>