# SmartKey Konektor – integrace Somfy (TaHoma)

Konektor umí ovládat zařízení **Somfy** (rolety, žaluzie, markýzy, brány) přes
**TaHoma Developer Mode** – lokální API boxu TaHoma. Voláte **stejný konektor
a stejné přístupové údaje** jako u ostatních zařízení; konektor komunikuje
s boxem za vás.

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

Oficiální podklady Somfy: <https://github.com/Somfy-Developer/Somfy-TaHoma-Developer-Mode>
(včetně OpenAPI: <https://somfy-developer.github.io/Somfy-TaHoma-Developer-Mode>).

## Co musíte připravit

1. V mobilní aplikaci **TaHoma by Somfy** otevřete
   **Konfigurace instalace → Parametry TaHoma boxu**.
2. **7× klepněte na PIN brány** (formát `2001-1234-5678`). Tím se aktivuje
   **Developer Mode** a zapne lokální API boxu.
3. V menu Developer Mode **vygenerujte lokální API token**.
   ⚠️ Token se zobrazí **jen jednou při vytvoření** – hned si ho zkopírujte.
4. Zjistěte **adresu boxu** v síti. Box má tvar `gateway-{PIN}.local:8443`
   (např. `gateway-1234-5678-9012.local:8443`), objevitelný i přes mDNS
   (služba `_kizboxdev._tcp`). Případně jeho IP adresu s portem **8443**.

Nám předáte **adresu boxu + token**. Zákazník je pak už při volání API neposílá –
konektor si je drží u vaší integrace.

> ⚠️ **Síťová dostupnost boxu (důležité).** Developer Mode je **lokální** API –
> běží jen v síti, kde je box TaHoma. Konektor běží na našem serveru, takže se
> k boxu musí síťově dostat. Prakticky to znamená jedno z:
> - box vystavit na **veřejnou IP / port 8443** (port-forward na routeru), nebo
> - propojit box a konektor přes **VPN** (doporučeno – bezpečnější), nebo
> - provozovat konektor v téže síti.
>
> Bez síťové dostupnosti boxu vrací volání HTTP 502 („box nedostupný"). Box má
> **self-signed certifikát** (Overkiz root CA
> `https://ca.overkiz.com/overkiz-root-ca-2048.crt`); konektor s tím počítá.

## Endpointy

| akce | endpoint |
|---|---|
| Konfigurace boxu (brány + zařízení) | `GET /somfy/setup` |
| Seznam zařízení | `GET /somfy/devices` |
| Stavy zařízení | `GET /somfy/device/states?deviceURL=…` |
| Poslat příkazy | `POST /somfy/exec` |
| Generický průchod na box | `GET/POST /api/somfy/<cesta>` |

Zařízení se adresují přes **deviceURL** (např. `io://1234-5678-9012/12345678`),
který najdete v `GET /somfy/devices`.

### Příklad – zavření rolety

```bash
curl -X POST https://connect.smartkey.cz/somfy/exec \
  -H "X-Client-Id: VAS_ID" -H "X-Client-Secret: VAS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
        "label": "Zavřít roletu",
        "actions": [{
          "deviceURL": "io://1234-5678-9012/12345678",
          "commands": [{"name": "close", "parameters": []}]
        }]
      }'
```

Typické příkazy: `open`, `close`, `stop`, `setClosure` (parametr = procenta zavření
0–100), `setPositionAndLinearSpeed` apod. Dostupné příkazy konkrétního zařízení
najdete v jeho definici (`definition.commands`) v odpovědi `GET /somfy/devices`.

### Sledování stavů (volitelné, pokročilé)

Kromě dotazu `GET /somfy/device/states` box podporuje i **události** (efektivnější
než opakované dotazování). Přes generický průchod `POST /api/somfy/events/register`
zaregistrujete posluchače a `POST /api/somfy/events/{listenerId}/fetch` (max. 1×
za sekundu) načítáte změny stavů.

## Chyby

Chyby konektoru mají HTTP status: **401** (špatné přihlášení ke konektoru),
**502** (box nedostupný, neplatný/expirovaný token, nebo integrace nemá přiřazený
box TaHoma). Ověření spojení s boxem najdete v administraci integrace
(tlačítko „Otestovat spojení").