# SmartKey Konektor – integrace Home Assistant

Konektor umí ovládat i **Home Assistant** – zámky, spínače, světla, rolety a
jakoukoli další entitu vaší instance. Komunikuje přímo s vaším Home Assistantem,
ale vy voláte pořád **stejný konektor a stejné přístupové údaje** jako u ostatních
systémů; konektor se o přihlášení k Home Assistantu postará.

Adresa API: **https://connect.smartkey.cz** · autentizace hlavičkami
`X-Client-Id` / `X-Client-Secret`.

Oficiální dokumentace REST API: <https://developers.home-assistant.io/docs/api/rest/>

## Co musíte připravit

1. V Home Assistantu klikněte vlevo dole na svůj **profil → záložka Zabezpečení →
   Long-lived access tokens → Vytvořit token**. Pojmenujte ho např. „SmartKey
   konektor". ⚠️ Token se zobrazí **jen jednou** – hned si ho zkopírujte.
   Doporučujeme vytvořit pro integraci **samostatného uživatele** (bez práv
   administrátora), aby měl token jen potřebná oprávnění.
2. Home Assistant musí být pro konektor **síťově dostupný**. Konektor běží na
   našem serveru, takže potřebuje jedno z:
   - **Nabu Casa** (Home Assistant Cloud) – adresa `https://xxxx.ui.nabu.casa`
     (nejjednodušší, bez zásahu do sítě), nebo
   - **vlastní veřejnou adresu** s HTTPS (reverse proxy / DuckDNS + Let's Encrypt), nebo
   - **VPN** mezi vaší sítí a konektorem.

   Čistě lokální `http://192.168.x.x:8123` z internetu dostupné není.
3. Nám předáte: **adresu instance + token**. Zákazník je pak při volání API neposílá.

## Endpointy

| akce | endpoint |
|---|---|
| Info o instanci | `GET /ha/config` |
| Stavy všech entit (volitelně `?domain=lock`) | `GET /ha/states` |
| Stav jedné entity | `GET /ha/state/{entity_id}` |
| Zavolat službu | `POST /ha/service/{domain}/{service}` |
| Seznam služeb | `GET /ha/services` |
| Generický průchod na Home Assistant | `GET/POST /api/ha/{cesta}` |

Entity se adresují přes **entity_id** (např. `lock.vchod`, `switch.zasuvka_kancelar`,
`cover.zaluzie_obyvak`) – najdete je v `GET /ha/states`.

### Příklad – odemknout zámek

```bash
curl -X POST https://connect.smartkey.cz/ha/service/lock/unlock \
  -H "X-Client-Id: VAS_ID" -H "X-Client-Secret: VAS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "lock.vchod"}'
```

Odpověď je seznam entit, jejichž stav se změnil (nativní odpověď Home Assistantu).

### Příklad – přečíst stav

```bash
curl https://connect.smartkey.cz/ha/state/lock.vchod \
  -H "X-Client-Id: VAS_ID" -H "X-Client-Secret: VAS_SECRET"
```

```json
{"entity_id": "lock.vchod", "state": "locked", "attributes": {"friendly_name": "Vchod"}, ...}
```

### Typické služby

| doména | služby |
|---|---|
| `lock` | `lock`, `unlock`, `open` |
| `switch` | `turn_on`, `turn_off`, `toggle` |
| `light` | `turn_on` (i s `brightness`, `color_name`…), `turn_off`, `toggle` |
| `cover` (rolety/žaluzie) | `open_cover`, `close_cover`, `stop_cover`, `set_cover_position` (`position` 0–100) |
| `climate` | `set_temperature` (`temperature`), `set_hvac_mode` |
| `scene` / `script` / `automation` | `turn_on`, `trigger` |

Data služby posíláte v JSON těle; `entity_id` může být i seznam (více entit najednou).

## Chyby

Chyby konektoru mají HTTP status: **401** (špatné přihlášení ke konektoru),
**502** (Home Assistant nedostupný, neplatný token, nebo integrace nemá přiřazený
Home Assistant). Neexistující entita/služba vrací 502 s `code: 404`.