# SmartKey Konektor – integrace zařízení Tuya

Konektor umí kromě zámků SmartKey ovládat i chytrá zařízení na platformě
**Tuya** (zásuvky, žaluzie, senzory, BLE zámky…). Používáte **stejný konektor
a stejné přístupové údaje** jako pro zámky SmartKey – jen voláte jiné cesty.
Konektor za vás řeší podepisování requestů i správu tokenu.

Adresa API: **https://connect.smartkey.cz**

## 1. Co musíte připravit (jednorázově)

Zařízení Tuya se ovládají přes váš vlastní projekt na Tuya platformě. Než začnete:

1. Zaregistrujte se na **[platform.tuya.com](https://platform.tuya.com)**.
2. **Cloud → Create Cloud Project**:
   - Industry: *Smart Home*
   - Development Method: *Smart Home*
   - Data Center: podle regionu vašeho účtu v mobilní aplikaci (ČR/EU = *Central Europe*).
3. V průvodci **Authorize API Services** ponechte předvybrané a přidejte:
   - **IoT Core** (token, výpis zařízení, stavy, příkazy)
   - Authorization Token Management
   - Smart Home Basic Service
   - volitelně **Smart Lock Open Service** (pro zámky Tuya)
4. **Overview → Authorization Key**: zkopírujte **Access ID (Client ID)** a
   **Access Secret (Client Secret)**.
5. **Devices → Link App Account → Add App Account** → zobrazí se QR kód →
   naskenujte ho v mobilní aplikaci **Smart Life** (*Já → ikona skenování*)
   a potvrďte. Tím se do projektu propojí všechna vaše zařízení.

**Access ID, Access Secret a datové centrum předejte nám** – doplníme je k vaší
integraci. Vy je pak už nikdy neposíláte; konektor jimi podepisuje komunikaci
s Tuya za vás.

> Bez kroku 5 (naskenování QR) vrací API prázdný seznam zařízení.

## 2. Autentizace

Stejná jako u zámků – hlavičky, které jste od nás dostali:

```
X-Client-Id: vase_client_id
X-Client-Secret: vas_client_secret
```

## 3. Pohodlné endpointy

Nad zařízeními Tuya nabízíme jednoduché zkratky (konektor sám vybere správnou
variantu API a normalizuje odpověď):

| akce | endpoint |
|---|---|
| Seznam zařízení projektu | `GET /tuya/devices` |
| Aktuální stav zařízení | `GET /tuya/devices/{id}/status` |
| Specifikace funkcí | `GET /tuya/devices/{id}/specification` |
| Detail zařízení | `GET /tuya/devices/{id}` |
| Odeslání příkazů | `POST /tuya/devices/{id}/commands` |

### Seznam zařízení

```bash
curl https://connect.smartkey.cz/tuya/devices \
  -H "X-Client-Id: VAS_ID" -H "X-Client-Secret: VAS_SECRET"
```

Odpověď (normalizovaná):

```json
{
  "devices": [
    {"id": "bf1234…", "name": "Zásuvka kuchyň", "product_name": "Smart Plug",
     "online": true, "category": "cz", "product_id": "aBcD…"}
  ]
}
```

`name` je název, jak jste si zařízení pojmenoval v aplikaci.

### Stav zařízení

```bash
curl https://connect.smartkey.cz/tuya/devices/bf1234.../status \
  -H "X-Client-Id: VAS_ID" -H "X-Client-Secret: VAS_SECRET"
```

Vrací aktuální hodnoty tzv. **DP kódů**:

```json
{"success": true, "result": [{"code": "switch_1", "value": true},
                             {"code": "cur_power", "value": 231}]}
```

### Odeslání příkazu (ovládání)

```bash
curl -X POST https://connect.smartkey.cz/tuya/devices/bf1234.../commands \
  -H "X-Client-Id: VAS_ID" -H "X-Client-Secret: VAS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"commands": [{"code": "switch_1", "value": true}]}'
```

Lze poslat víc příkazů najednou. U offline zařízení vrátí Tuya chybu
`device is offline`.

## 4. Jak zjistit, co zařízení umí (status vs. functions)

`GET /tuya/devices/{id}/specification` vrátí dvě sekce:

- **`functions`** – *zapisovatelné* funkce (co jde ovládat). Každá má `code`,
  `type` a `values`:
  - `Boolean` → přepínač (`true`/`false`)
  - `Enum` → jedna z hodnot ze seznamu `range`
  - `Integer` → číslo v rozsahu `min`…`max` s krokem `step`
    (pozor na `scale`: hodnota `2372` se `scale: 1` znamená **237,2**)
  - `String` / `Json` / `Raw` → text
- **`status`** – seznam všech čtených kódů (i těch, co nejde nastavit).

> ⚠️ Pole `values` je JSON zakódovaný do textového řetězce – po přečtení ho
> ještě jednou naparsujte jako JSON.

Z `functions` postavíte generické ovládací UI: Boolean → přepínač, Enum →
rozbalovací seznam, Integer → posuvník.

## 5. Generická proxy (pokročilé)

Pokud potřebujete jakýkoli endpoint Tuya Cloud OpenAPI, který není mezi
zkratkami výše, volejte přímo přes generickou proxy – konektor request
podepíše a doplní token:

```
<METODA> /api/tuya/<cesta Tuya API>
```

Příklad – stejné jako `POST /tuya/devices/{id}/commands`:

```bash
curl -X POST "https://connect.smartkey.cz/api/tuya/v1.0/iot-03/devices/bf1234.../commands" \
  -H "X-Client-Id: VAS_ID" -H "X-Client-Secret: VAS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"commands": [{"code": "switch_1", "value": true}]}'
```

U `GET` requestů se query parametry podepisují automaticky – posílejte je
normálně v URL.

## 6. Chybové stavy

Tuya odpovědi mají obálku `{"success": bool, "code": int, "msg": str, "result": …}`.
Kontrolujte `success` i při HTTP 200.

| situace | projev | řešení |
|---|---|---|
| špatné Access ID | `code 2009` | zkontrolovat Access ID |
| špatný Secret nebo čas | `sign invalid` (1004) | zkontrolovat Secret |
| špatné datové centrum | `code 1106` / `2007` | zvolit správný region |
| neautorizovaná služba | `code 28841002` | přidat službu v projektu |
| prázdný seznam zařízení | `result: []` | naskenovat QR (Link App Account) |
| zařízení offline | `device is offline` | zařízení není dostupné |

Chyby konektoru (nikoli Tuya) mají HTTP status: 401 (špatné přihlášení ke
konektoru), 403 (deaktivovaná integrace), 429 (rate limit), 502 (Tuya nedostupná
nebo integrace nemá přiřazené Tuya údaje).