# SmartKey Konektor – dokumentace pro zákazníky

Konektor je jednotné API pro ovládání chytrých zámků **Zámky SmartKey** a **Tuya**
z vašich systémů. Nemusíte řešit OAuth tokeny, podepisování requestů ani rozdíly
mezi platformami – zavoláte náš konektor, my se postaráme o zbytek.

> Stav funkcí: ✅ = dostupné nyní · 🔜 = připravujeme

## 1. Přístupové údaje a autentizace

Od nás dostanete **client_id** a **client_secret**. Jedny údaje platí pro všechny
vaše zámky bez ohledu na platformu – konektor sám pozná, zda jde o Zámky SmartKey
nebo Tuya, a použije správné pověření vůči příslušnému cloudu.

Údaje posílejte v hlavičkách každého requestu:

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

Komunikace probíhá výhradně přes HTTPS. Client_secret nikdy nevkládejte do
mobilních či webových aplikací u koncových uživatelů – patří jen na váš server.

### Propojení s účtem zámků (nutné pro Zámky SmartKey)

Konektor komunikuje s cloudem zámků pod **vaším uživatelským účtem** (stejný
účet, jakým se přihlašujete v mobilní aplikaci). Potřebuje k tomu znát
**uživatelské jméno** a **heslo v podobě MD5 hashe**.

Údaje předáte jednoduše: **přiložíte je k prvnímu požadavku**, který na API
pošlete. Konektor si je při prvním volání uloží k vašemu client_id a od té
chvíle je už **nikdy posílat nemusíte** – všechna další volání probíhají jen
s hlavičkami `X-Client-Id` a `X-Client-Secret`.

Pravidla:

- `username` – uživatelské jméno účtu (telefon s předvolbou nebo e-mail,
  přesně jak je v aplikaci)
- `password` – **MD5 hash hesla**: 32 znaků, malá písmena, hexadecimálně.
  Posílá se výhradně hash, nikdy čisté heslo.
- Údaje se uloží **pouze při prvním požadavku** (dokud nejsou vyplněné).
  Opakované zaslání jiných hodnot uloženou konfiguraci nepřepíše – změnu
  vyřídí naše podpora.
- Výjimka: endpointy `user/*` (virtuální účty) mají vlastní `username`/`password`
  parametry a s uloženým účtem integrace nesouvisí.

Jak vytvořit MD5 hash hesla:

| Prostředí | Příkaz |
|---|---|
| Linux / macOS | `echo -n 'MojeHeslo123' \| md5sum` |
| PowerShell | `[BitConverter]::ToString([Security.Cryptography.MD5]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes('MojeHeslo123'))).Replace('-','').ToLower()` |
| PHP | `md5('MojeHeslo123')` |
| Python | `hashlib.md5(b'MojeHeslo123').hexdigest()` |

**Příklad prvního požadavku** (výpis zámků + předání účtu):

```bash
curl -X POST https://connect.smartkey.cz/api/v3/lock/list \
  -H "X-Client-Id: vase_client_id" \
  -H "X-Client-Secret: vas_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "+420123456789",
    "password": "482c811da5d5b4bc6d497ffa98491e38",
    "pageNo": 1,
    "pageSize": 20
  }'
```

Odpověď je stejná jako u běžného volání – účet se uložil na pozadí. **Každý
další požadavek** už posíláte bez účtu:

```bash
curl -X POST https://connect.smartkey.cz/api/v3/lock/list \
  -H "X-Client-Id: vase_client_id" \
  -H "X-Client-Secret: vas_client_secret" \
  -H "Content-Type: application/json" \
  -d '{"pageNo": 1, "pageSize": 20}'
```

Pokud účet ještě nebyl předán a požadavek ho neobsahuje, vrátí API chybu
`errcode 10007` (nelze se přihlásit k cloudu) – v tom případě zopakujte
první volání včetně `username` a `password`.

## 2. Základní principy

- Odpovědi jsou vždy JSON.
- Časy se předávají jako **Unix timestamp v milisekundách**.
- Seznamy jsou stránkované: `pageNo` (od 1) a `pageSize` (max 100), odpověď obsahuje `pages`.
- Chyby cloudu vracíme v těle odpovědi (pole `errcode`/`errmsg` u Zámků SmartKey,
  `code`/`msg` u Tuya) – kontrolujte je i při HTTP 200. Chyby konektoru
  (neplatné přihlášení, nedostupný cloud) mají HTTP status 401/403/502.

## 3. Co můžete dělat – Zámky SmartKey

### eKey – mobilní klíče ✅

Elektronický klíč do aplikace SmartKey v telefonu příjemce.

| akce | endpoint |
|---|---|
| Poslat eKey uživateli | `POST /ekey/send` |
| Seznam eKey účtu | `GET /ekey/list` |
| Seznam eKey zámku | `GET /ekey/list?lockId=…` |
| Smazat eKey | `POST /ekey/{keyId}/delete` |
| Zmrazit / odmrazit eKey | `POST /ekey/{keyId}/freeze` · `/unfreeze` |
| Změnit platnost | `POST /ekey/{keyId}/period` |

Příklad – poslat trvalý klíč (0/0 = neomezená platnost):

```bash
curl -X POST https://connect.smartkey.cz/ekey/send \
  -H "X-Client-Id: VAS_ID" -H "X-Client-Secret: VAS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"lockId": 163377, "receiverUsername": "+420777123456",
       "keyName": "Klic pro Honzu", "createUser": 1}'
```

Užitečné detaily:
- `createUser=1` – pokud příjemce (telefon/e-mail) ještě nemá účet SmartKey, cloud
  ho založí automaticky; výchozí heslo je posledních 6 znaků uživatelského jména.
- Uživatel může mít na jeden zámek jen jeden eKey – nové poslání starý klíč nahradí.
- `startDate`/`endDate` v ms omezí platnost klíče, `0` a `0` znamená trvalý klíč.

### Kompletní API ✅

Všechny funkce cloudu zámků voláte přes jednotné API konektoru – parametry
pošlete jako JSON, autentizaci doplníme my:

```
POST /api/v3/<cesta>     např. POST /api/v3/lock/list
```

**Podrobná referenční dokumentace všech 200+ endpointů: [api-reference.md](api-reference.md)**

Pokryté oblasti (výběr):

- **Zámky** – seznam, detail, nastavení (auto-lock, passage mode), skupiny ✅
- **Číselné kódy** – generované (fungují offline okamžitě), vlastní, změna, mazání ✅
- **Virtuální uživatelé + eKey** – registrace účtu přes API, poslání eKey,
  zmrazení, změna platnosti, autorizace, smazání ✅
- **Karty a biometrie** – IC/RFID karty, otisky, obličej: výpis ✅, zápis vyžaduje
  gateway nebo Bluetooth synchronizaci aplikací
- **Záznamy odemykání** – historie průchodů ✅
- **Gateway** – seznam, detail, správa ✅; vzdálené odemčení/zamčení a živý stav
  zámku vyžadují připojenou gateway
- **QR kódy, bezdrátové klávesnice, dálkové ovladače, WiFi zámky** ✅

### Číselné kódy (PINy) – závazná pravidla ⚠️

Z praxe (září 2026): rezervační systém odeslal do jednoho zámku přes 2 000 vlastních
kódů na 7 měsíců dopředu. V cloudu byly „platné", ale **zámek je neznal** a hosty
nepouštěl. Aby se to neopakovalo, platí tato pravidla:

**1. Dva druhy kódů – vyberte správný**

| | `keyboardPwd/get` (generovaný) | `keyboardPwd/add` (vlastní číslo) |
|---|---|---|
| Kdo určí číslo | cloud (náhodné) | vy |
| Zápis do zámku | **není potřeba** – kód počítá algoritmus zámku | musí se **fyzicky zapsat** do zámku |
| Potřebuje bránu | ne | ano (`addType: 2`) |
| Zabírá paměť zámku | **ne** | **ano – zámek pojme jen cca 250 vlastních kódů** |
| Platnost | na celé hodiny; poprvé použít do 24 h od začátku | na minutu |
| Nutno mazat po použití | ne | ano (uvolnit paměť) |

**Pro rezervace, hosty a jednorázové vstupy používejte `keyboardPwd/get` (typ 3 – období).**
Vlastní kódy (`add`) nechte na trvalé kódy personálu a případy, kdy číslo musí být předem známé.

**2. Pokud musíte použít `keyboardPwd/add`**

- **Vždy posílejte `addType: 2`** (zápis přes bránu). Výchozí `addType: 1` znamená, že kód zapíše
  až mobilní aplikace při Bluetooth připojení – bez ní kód v zámku nikdy nebude, i když ho cloud
  ukazuje jako platný.
- Kód odesílejte **nejdříve ~24 h před začátkem platnosti**, ne měsíce dopředu (paměť ~250 kódů).
- Zapisujte **sekvenčně** – další volání až po odpovědi na předchozí. Brána zvládne jeden zápis
  za 2–5 s a paralelní požadavky odmítá.
- **Kontrolujte `errcode`** v odpovědi. Konektor vrací HTTP 200 vždy; úspěch = `errcode` chybí
  nebo je 0 a odpověď obsahuje `keyboardPwdId`. Při chybě volání zopakujte s odstupem.
- Po skončení platnosti kód **smažte** (`keyboardPwd/delete`, `deleteType: 2`), jinak paměť
  zámku dojde a nové kódy se přestanou zapisovat.
- Nezasílejte stejné číslo dvakrát – zámek duplicitní kód odmítne.

**3. Jak poznat, že je kód „platný jen v cloudu"**

Cloud ho vede jako platný, ale zámek při zadání hlásí neplatný kód, v historii (`lockRecord/list`)
je neúspěšný pokus (`success: 0`) a kód nejde upravit s hláškou, že „ještě nebyl použit".
Příčina je vždy stejná: kód se do zámku nedostal (`addType: 1`, plná paměť, nebo brána offline).
Čas zámku s tím nesouvisí (ověříte přes `lock/queryDate`).

## 4. Co můžete dělat – zařízení Tuya ✅

Konektor ovládá i chytrá zařízení na platformě **Tuya** (zásuvky, žaluzie,
senzory, BLE zámky…) – stejnými přístupovými údaji, jen na jiných cestách:

| akce | endpoint |
|---|---|
| Seznam zařízení | `GET /tuya/devices` |
| Stav zařízení | `GET /tuya/devices/{id}/status` |
| Co zařízení umí | `GET /tuya/devices/{id}/specification` |
| Ovládání zařízení | `POST /tuya/devices/{id}/commands` |
| Jakýkoli Tuya endpoint | `POST /api/tuya/<cesta>` (generická proxy) |

Příklad – zapnutí zásuvky:

```bash
curl -X POST https://connect.smartkey.cz/tuya/devices/VASE_ID/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}]}'
```

**Podrobný návod včetně založení Tuya projektu, propojení mobilní aplikace
a datového modelu zařízení: [tuya-integrace.md](tuya-integrace.md).**

Pozn.: Aby konektor zařízení viděl, musíte mít vlastní projekt na Tuya
platformě a propojit v něm účet mobilní aplikace (QR kód). Access ID, Secret
a datové centrum projektu předáte nám – doplníme je k vaší integraci.

## 5. Limity a doporučení

- Nepoužívejte agresivní polling; pro záznamy odemykání připravujeme callback
  notifikace, které polling nahradí.
- Na jednoho klienta platí rate limit 10 requestů/s; při překročení dostanete HTTP 429.
- Tokeny vůči cloudům výrobců spravuje konektor – vaše systémy je nikdy nevidí.

## 6. Changelog

- **2026-09-25** – Nová sekce „Číselné kódy (PINy) – závazná pravidla“: `get` vs `add`, `addType: 2`, limit ~250 vlastních kódů, kontrola `errcode`, mazání prošlých kódů.
| datum | změna |
|---|---|
| 2026-08-17 | Podpora zařízení Tuya (`/tuya/*` a `/api/tuya/*`) – seznam, stav, specifikace, ovládání; návod v [tuya-integrace.md](tuya-integrace.md) |
| 2026-08-16 | Dokumentační portál `/docs/` na serveru: XLSX + MD reference s českými popisy, `llms-full.txt` pro AI asistenty, OpenAPI 3.0 specifikace |
| 2026-08-16 | Kompletní API reference (200+ endpointů), podpora virtuálních uživatelů (`/api/v3/user/*`), sjednocené názvosloví v odpovědích |
| 2026-08-12 | Autentizace přes client_id + client_secret (hlavičky X-Client-Id / X-Client-Secret) |
| 2026-08-12 | První verze: eKey pro Zámky SmartKey + generická proxy, dokumentace Tuya roadmapy |