# SmartKey Konektor – kompletní kontext pro AI asistenty

Tento soubor obsahuje vše, co AI asistent potřebuje k práci se SmartKey
Konektorem (API pro ovládání chytrých zámků). Vlož ho celý do kontextu.

## Pravidla
- Base URL: https://connect.smartkey.cz
- Autentizace: každý request má hlavičky `X-Client-Id` a `X-Client-Secret`
  (přiděluje SmartKey; konektor je interně mapuje na účet u výrobce zámků)
- Všechny endpointy: `POST https://connect.smartkey.cz/api/v3/<cesta>` s JSON tělem
  (Content-Type: application/json); parametry lze poslat i jako query string
- NIKDY neposílej parametry clientId, accessToken, clientSecret, date
  – doplňuje je konektor automaticky
- Časy: Unix timestamp v milisekundách; startDate=0 a endDate=0 = trvalá platnost
- Stránkování: pageNo (od 1), pageSize (max ~100); odpověď má pages, total
- Úspěch: errcode chybí nebo 0. Business chyby: HTTP 200 + errcode/errmsg.
  Chyby konektoru: 401 špatné přihlášení, 403 deaktivace/nepovolená cesta,
  429 rate limit (10 req/s), 502 cloud zámků nedostupný
- Operace „vyžaduje gateway“ bez připojené gateway vrací errcode -2012
- Vlastní PIN (keyboardPwd/add, addType=1) se do zámku zapíše až při Bluetooth
  synchronizaci aplikací; generovaný PIN (keyboardPwd/get) funguje okamžitě
- Virtuální uživatel: user/register (heslo jako MD5 hash) → vrácený username
  použij jako receiverUsername v key/send

## Ukázka integrace (curl)
```bash
curl -X POST https://connect.smartkey.cz/api/v3/lock/list \
  -H "X-Client-Id: CLIENT_ID" -H "X-Client-Secret: CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"pageNo": 1, "pageSize": 100}'
```

## Ukázka integrace (Python)
```python
import requests

class SmartKeyKonektor:
    def __init__(self, base_url, client_id, client_secret):
        self.base = base_url.rstrip("/")
        self.headers = {"X-Client-Id": client_id, "X-Client-Secret": client_secret}

    def call(self, path, **params):
        r = requests.post(f"{self.base}/api/v3/{path}", headers=self.headers,
                          json=params, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data.get("errcode"):
            raise RuntimeError(f"Chyba {data['errcode']}: {data.get('errmsg')}")
        return data

k = SmartKeyKonektor("https://connect.smartkey.cz", "CLIENT_ID", "CLIENT_SECRET")
zamky = k.call("lock/list", pageNo=1, pageSize=100)["list"]
pin = k.call("keyboardPwd/get", lockId=zamky[0]["lockId"], keyboardPwdVersion=4,
             keyboardPwdType=3, startDate=0, endDate=0)
```

## Typické scénáře
- Seznam zámků: lock/list → pole `list`, každý zámek má lockId, lockAlias,
  electricQuantity (baterie %), hasGateway
- Okamžitý PIN pro návštěvu: keyboardPwd/get (funguje bez gateway)
- Vlastní PIN: keyboardPwd/add s addType=1 (zapíše se při BT synchronizaci)
- Mobilní klíč: user/register → key/send s receiverUsername z registrace
- Historie: lockRecord/list se startDate/endDate v ms
- Vzdálené odemčení: lock/unlock (jen se zámkem připojeným na gateway)

## Formát zápisu níže
`POST /api/v3/<cesta>` – popis
- REQ: parametr (typ, Y=povinný/N) popis
- RESP: pole (typ) popis



## User APIs

`POST /api/v3/user/register` – Založí virtuální uživatelský účet (heslo posílejte jako MD5). Vrácené uživatelské jméno použijte jako receiverUsername při poslání eKey.
- REQ: username (String, Y) username，only numbers and English letters allowed，this api will return a prefixed username, please GET Access Token with the prefixed username
- REQ: password (String, Y) Password(32 chars, low case, md5 encrypted )
- RESP: username (String) Prefixed username, please GET Access Token with this prefixed username

`POST /api/v3/user/resetPassword` – Resetuje heslo virtuálního uživatelského účtu.
- REQ: username (String, Y) The prefixed username return by cloud API: User register
- REQ: password (String, Y) New password(32 chars, low case, md5 encrypted )
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/user/list` – Vrátí seznam virtuálních účtů založených přes API.
- REQ: startDate (Long, N) query by register time，start time (timestamp in millisecond)
- REQ: endDate (Long, N) query by register time，end time (timestamp in millisecond)
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, max 200
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/user/delete` – Smaže virtuální uživatelský účet.
- REQ: username (String, Y) The prefixed username return by cloud API: User register
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message


## Lock APIs

`POST /api/v3/lock/initialize` – Inicializuje zámek do cloudu (páruje se přes SDK).
- REQ: lockData (String, Y) Lock Data，must be get from the callback function of Lock initialie method of APP SDK
- REQ: lockAlias (String, N) Lock alias
- REQ: groupId (Int, N) group ID，refer to cloud API: Add group
- REQ: nbInitSuccess (Int, N) Is NB-IoT lock inited Successfully? 1-yes, 0-no. Only NB-IoT lock need this parameter.
- RESP: lockId (Int) Lock ID
- RESP: keyId (Int) Admin ekey id

`POST /api/v3/lock/list` – Vrátí seznam všech zámků účtu (jen zámky, kde je účet hlavním správcem).
- REQ: lockAlias (String, N) Search by lock alias, fuzzy matching
- REQ: groupId (Int, N) Group ID，search by group, refer to: Add group for detail
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, default 20, max 1000
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, default 20, max 10000
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/lock/detail` – Vrátí detailní informace o zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: lockId (Int) Lock ID
- RESP: lockName (String) Lock name
- RESP: lockAlias (String) Lock alias
- RESP: lockMac (String) Lock MAC
- RESP: noKeyPwd (String) Super passcode, which only belongs to the admin ekey, can be entered on the keypad to unlock
- RESP: electricQuantity (Int) Lock battery
- RESP: featureValue (String) characteristic value . it is used to indicate what kinds of feature do a lock support.
- RESP: timezoneRawOffset (Long) The offset between your time zone and UTC, in millisecond
- RESP: modelNum (String) Product model (for firmware update)
- RESP: hardwareRevision (String) Hardware version (for firmware update)
- RESP: firmwareRevision (String) Firmware version (for firmware update)
- RESP: autoLockTime (Int) Auto lock time (in seconds), -1 for disable auto lock
- RESP: lockSound (Int) Lock sound: 0-unknow、1-on, 2-off
- RESP: soundVolume (Int) Sound Volume：1-5
- RESP: hasGateway (Int) Connected to a gateway：0-false、1-true
- RESP: privacyLock (Int) Privacy lock：0-unknow、1-on, 2-off
- RESP: tamperAlert (Int) Tamper alert：0-unknow、1-on, 2-off
- RESP: resetButton (Int) Reset button：0-unknow、1-on, 2-off
- RESP: openDirection (Int) Open direction：0-unknow、1-left open、2-right open
- RESP: passageMode (Int) Passage mode：1-enable、2-disable
- RESP: passageModeAutoUnlock (Int) Passagemode auto unlock:1-on, 2-off, set to 1 then the lock will auto unlock at the time the passage mode start
- RESP: date (Long) Lock init time (timestamp in millisecond)

`POST /api/v3/lock/delete` – Smaže zámek.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/updateLockData` – Resetuje data zámku – zneplatní všechny eKey a kódy (destruktivní!).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: lockData (String, Y) Lock data from APP SDK
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/rename` – Přejmenuje zámek.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: lockAlias (String, Y) New lock alias
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/changeAdminKeyboardPwd` – Změní hlavní (admin) číselný kód zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: password (String, Y) New super passcode
- REQ: changeType (Int, N) Method: 1-via phone bluetooth，must call APP SDK method first, 2-via gateway or WiFi lock , if it's a WiFi lock or it's connected to gateway, you can call this a
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/transfer` – Převede zámek na jiný účet (nevratné!).
- REQ: receiverUsername (String, Y) The receiver's username
- REQ: lockIdList (String, Y) Lock ID list, example:[1234,3332]
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/updateElectricQuantity` – Nahraje stav baterie naměřený přes SDK.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: electricQuantity (Int, Y) Lock battery
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/setAutoLockTime` – Nastaví čas automatického zamčení v sekundách.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: seconds (Int, Y) The lock will automatically locked after the specific seconds, this parameter set 0 or -1 mean close auto lock
- REQ: type (Int, Y) method: 1-via phone bluetooth，must call Set auto lock time method of APP SDK before you request this API 2-via gateway or WiFi lock , you can call this api dire
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/configurePassageMode` – Nastaví průchozí režim (zámek zůstává odemčený v daných časech).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: passageMode (Int, Y) Passage mode: 1-on, 2-off
- REQ: cyclicConfig (JsonArray, N) Converting a list of records from a JsonArray to a String, please refer to the example above. Cycle time setting， can only set a maximum of five time periods.
- REQ: autoUnlock (Int, N) Auto unlock:1-on, 2-off, set to 1 then the lock will auto unlock at the time the passage mode start
- REQ: type (Int, Y) Method: 1-via phone bluetooth，you should config via APP SDK before you request this API 2-via gateway or WiFi lock ，you can call this api directly if it's a WiF
- RESP: isAllDay (Int) All Hours: 1-YES, 2-NO, if is all hours, then startDate and endDate params is ignored.
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDays (JsonArray[Int]) Cycle valid days of the week:1-7, e.g. [1,2,3]

`POST /api/v3/lock/getPassageModeConfiguration` – Vrátí konfiguraci průchozího režimu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: passageMode (Int) Passage mode: 1-on, 2-off
- RESP: cyclicConfig (JsonArray) Cycle time setting
- RESP: autoUnlock (Int) Auto unlock:1-on, 2-off, set to 1 then the lock will auto unlock at the time the passage mode start

`POST /api/v3/lock/setHotelCardSector` – Nastaví sektor hotelových karet.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: sector (String, Y) Hotel card sector，for example：1,2,3,4,5,6,7,8,9,10 for sectors 1 to 10
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/updateSetting` – Zapíše nastavení zámku (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: type (Int, Y) The item to be set：2-Privacy lock、3-Tamper alert、4-Reset button、6-Lock sound、7-Open direction、8-Sound volume、10-Wifi lock's power saving、11-Door unclosed alarm 
- REQ: value (Int, Y) Value: 1-on、2-off; Open direction：1-left open、2-right open; Sound volume: 1 to 5 Door unclosed alarm time: In seconds, 0 mean off, need door sensor
- REQ: changeType (Int) Method: 1-via phone bluetooth, you should call APP SDK method first 2- via gateway or WiFi lock , you can call this api directly if it's a WiFi lock or it's con
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/querySetting` – Přečte nastavení zámku – parametr type určuje položku (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: type (Int, Y) The item to be queried: 2-Privacy lock、3-Tamper alert、4-Reset button、7-Open direction
- RESP: value (Int) Value: 1-on、2-off; Open direction：1-left open、2-right open;

`POST /api/v3/lock/getWorkingMode` – Vrátí nastavené provozní hodiny zámku.
- REQ: lockId (Int, Y) Lock ID
- RESP: workingMode (Int) Working status, 1: working all day, 2: not working all day, 3: custom
- RESP: cyclicConfig (String) Working hours

`POST /api/v3/lock/configWorkingMode` – Nastaví provozní hodiny zámku.
- REQ: lockId (Int, Y) Lock ID
- REQ: workingMode (String, Y) Working status, 1: working all day, 2: not working all day, 3: custom
- REQ: type (String, Y) Method: 1-via phone bluetooth，should call APP SDK method to add card first. 2-via gateway or WiFi lock ，you can call this api with type = 2 directly if it's a W
- REQ: cyclicConfig (String, N) Time period configuration
- RESP: isAllDay (Int) Whether it is always open all day: 1-Yes, 2-No
- RESP: startTime (Int) Start time in minutes, e.g. 480 means 8:00
- RESP: endTime (Int) End time in minutes, e.g. 1080 means 18:00
- RESP: weekDays (JsonArray[Int]) Cycle validity period: 1-7, such as [1,2,3]

`POST /api/v3/lock/getExtraSetting` – Vrátí zámek podle zadaných parametrů.
- REQ: lockId (Int, Y) Lock ID
- REQ: type (Int, Y) 0 - Retrieve information from the cloud 1 - Retrieve the latest unauthorized alarm information via gateway or Wi-Fi lock
- RESP: unauthorizedAttemptAlertFlag (Int) Unauthorized alarm, 1 - On, 0 - Off
- RESP: unauthorizedAttemptAlertCount (Int) Unauthorized alerts, number of failures, 0 indicates off.
- RESP: unauthorizedAttemptAlertLockTime (Int) Unauthorized alarm, lock time, unit - seconds
- RESP: unauthorizedAttemptAlertPwd (Int) Unauthorized alarm, password flag: 1 - on, 0 - off
- RESP: unauthorizedAttemptAlertCard (Int) Unauthorized alarm, IC card flag: 1 - On, 0 - Off
- RESP: unauthorizedAttemptAlertFingerprint (Int) Unauthorized access alarm, fingerprint indicator, 1 - open, 0 - closed

`POST /api/v3/lock/updateUnauthorizedAttemptAlert` – Upraví vlastnosti zámku.
- REQ: type (Int, Y) 1- Update via Bluetooth; 2- Update via gateway or Wi-Fi lock
- REQ: lockId (String, Y) Lock ID
- REQ: unauthorizedAttemptAlertFlag (Int, Y) Unauthorized alarm, 1 - On, 0 - Off
- REQ: unauthorizedAttemptAlertCount (Int, Y) Unauthorized alerts, number of failures, 0 indicates off.
- REQ: unauthorizedAttemptAlertLockTime (Int, Y) Unauthorized alarm, lock time, unit - seconds
- REQ: unauthorizedAttemptAlertPwd (Int, N) Unauthorized alarm, password flag: 1 - on, 0 - off
- REQ: unauthorizedAttemptAlertCard (Int, N) Unauthorized alarm, IC card flag: 1 - On, 0 - Off
- REQ: unauthorizedAttemptAlertFingerprint (Int, N) Unauthorized access alarm, fingerprint indicator, 1 - open, 0 - closed
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: description (String) Error Description


## Ekey APIs

`POST /api/v3/key/send` – Odešle eKey (mobilní klíč) uživateli. startDate=0 a endDate=0 znamená trvalý klíč; createUser=1 založí účet příjemce automaticky.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: receiverUsername (String, Y) The receiver's username
- REQ: keyName (String, Y) Key name
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond)
- REQ: remarks (String, N) Comment
- REQ: remoteEnable (Int, N) Is remote unlock enabled: 1-yes, 2-no
- REQ: keyRight (Int, N) Is an authorized ekey: 1-yes, 0-no，the default value is 0
- REQ: createUser (Int, N) Auto create SmartKey account if receiverUsername is not a registered SmartKey account: 1-yes, 2-no (default), this parameter take effect only when receiverUsern
- RESP: keyId (Int) Ekey ID

`POST /api/v3/key/list` – Vrátí seznam eKey, které účet obdržel.
- REQ: lockAlias (String, N) Search by lock alias, fuzzy matching
- REQ: groupId (Int, N) Search by group ID, refer to cloud API: Add group for details
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, max 1000
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 1000
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/key/get` – Vrátí eKey (mobilní klíč) podle zadaných parametrů.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: keyId (Int) Ekey ID
- RESP: lockData (String) Lock data, used to operate lock
- RESP: lockId (Int) Lock ID
- RESP: userType (String) Ekey type:110301-admin ekey, 110302-common user ekey
- RESP: keyStatus (String) Refer to: Ekey status
- RESP: lockName (String) Lock name
- RESP: lockAlias (String) Lock alias
- RESP: lockMac (String) Lock MAC
- RESP: noKeyPwd (String) Super passcode, which only belongs to the admin ekey, can be entered on the keypad to unlock
- RESP: electricQuantity (Int) Lock battery
- RESP: startDate (Long) The time when it becomes valid (timestamp in millisecond)
- RESP: endDate (Long) The time when it is expired (timestamp in millisecond)
- RESP: remarks (String) Comment
- RESP: keyRight (Int) Is ekey authorized: 0-NO, 1-yes
- RESP: featureValue (String) characteristic value . it is used to indicate what kinds of feature do a lock support.
- RESP: remoteEnable (Int) Is remote unlock enabled: 1-yes,2-no
- RESP: passageMode (Int) Passage mode：1-enable、2-disable
- RESP: timezoneRawOffset (Long) The offset between your time zone and UTC, in millisecond
- RESP: groupId (Int) Group ID
- RESP: groupName (String) Group name

`POST /api/v3/lock/listKey` – Vrátí seznam všech eKey vydaných k zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: searchStr (String, N) Search keywords, fuzzy search by key name
- REQ: keyRight (Int, N) Whether the ekey is authorized or not: 0 - No, 1 - Yes, used to filter authorized administrator electronic keys, return all ekeys without this parameter
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, max 200
- REQ: orderBy (Int, Y) Sort by: 0-by name, 1-reverse order by time, 2-reverse order by name
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/key/delete` – Smaže eKey (mobilní klíč).
- REQ: keyId (Int, Y) Ekey ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/key/freeze` – Dočasně zmrazí eKey (mobilní klíč) – přestane fungovat, lze odmrazit.
- REQ: keyId (Int, Y) Ekey ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/key/unfreeze` – Odmrazí dříve zmrazený eKey (mobilní klíč).
- REQ: keyId (Int, Y) Ekey ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/key/update` – Upraví vlastnosti eKey.
- REQ: keyId (Int, Y) Ekey ID
- REQ: keyName (string, N) Ekey name will be modifed
- REQ: remoteEnable (Int, N) Is remote unlock enabled: 1-yes, 2-no
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/key/changePeriod` – Změní časovou platnost eKey.
- REQ: keyId (Int, Y) Ekey ID
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond)
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/key/authorize` – Povýší eKey na autorizovaného správce zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: keyId (Int, Y) ekey ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/key/unauthorize` – Odebere eKey práva správce.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: keyId (Int, Y) Ekey ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/key/getUnlockLink` – Vytvoří webový odkaz pro odemčení bez aplikace.


## Passcode APIs

`POST /api/v3/keyboardPwd/get` – Vygeneruje náhodný číselný kód – funguje na klávesnici okamžitě i bez gateway (kód počítá algoritmus zámku).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: keyboardPwdType (Int, Y) Passcode type，refer to section 2.1
- REQ: keyboardPwdName (String, N) Passcode name
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, N) The time when it is expired (timestamp in millisecond)
- RESP: keyboardPwd (String) Passcode
- RESP: keyboardPwdId (Int) Passcode ID

`POST /api/v3/keyboardPwd/add` – Vytvoří vlastní číselný kód. addType=1 se zapíše při Bluetooth synchronizaci aplikací, addType=2 okamžitě přes gateway.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: keyboardPwd (Int, Y) Passcode
- REQ: keyboardPwdName (String, N) Passcode name
- REQ: keyboardPwdType (Int, N) Keyboard password type：2-permanent, 3-period, default value is 3
- REQ: startDate (Long, N) The time when it becomes valid (timestamp in millisecond), must be required if keyboard password type is 3-period
- REQ: endDate (Long, N) The time when it is expired (timestamp in millisecond), must be required if keyboard password type is 3-period
- REQ: addType (Int, Y) Method: 1-via phone bluetooth，should call APP SDK method to add passcode first. 2-via gateway or WiFi lock ，you can call this api directly if it's a WiFi lock o
- RESP: keyboardPwdId (Int) Passcode ID

`POST /api/v3/lock/listKeyboardPwd` – Vrátí seznam všech číselných kódů zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: searchStr (String, N) Search keywords, fuzzy search by passcode name or precise match by passcode
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, max 200
- REQ: orderBy (Int, Y) Sort by: 0-by name, 1-reverse order by time, 2-reverse order by name
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/keyboardPwd/delete` – Smaže číselný kód.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: keyboardPwdId (Int, Y) Passcode ID
- REQ: deleteType (Int, Y) Method: 1-delete with App via Bluetooth, you should delete via bluetooth first 2-delete via WiFi gateway , you can call this api directly if it's a WiFi lock or
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/keyboardPwd/change` – Změní číselný kód.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: keyboardPwdId (Int, Y) Passcode ID
- REQ: keyboardPwdName (String, N) New passcode name
- REQ: newKeyboardPwd (String, N) The new passcode
- REQ: startDate (Long, N) The start time of the new passcode (timestamp in millisecond)
- REQ: endDate (Long, N) The end time of the new passcode (timestamp in millisecond)
- REQ: changeType (Int, Y) Method: 1-via phone bluetooth, you should call APP SDK method first 2- via gateway or WiFi lock , you can call this api directly if it's a WiFi lock or it's con
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message


## Gateway APIs

`POST /api/v3/lock/unlock` – Vzdáleně odemkne zámek (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/lock` – Vzdáleně zamkne zámek (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/queryOpenState` – Zjistí, zda jsou dveře odemčené/zamčené (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: state (Int) Open state of lock:0-locked,1-unlocked,2-unknown

`POST /api/v3/lock/queryDate` – Přečte aktuální čas zámku (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: date (Long) Lock time (timestamp in millisecond)

`POST /api/v3/lock/updateDate` – Synchronizuje čas zámku (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: date (Long) The lock time after adjusting (timestamp in millisecond)

`POST /api/v3/lock/queryElectricQuantity` – Přečte aktuální stav baterie ze zámku (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: electricQuantity (Int) Lock battery

`POST /api/v3/gateway/list` – Vrátí seznam gateway účtu včetně stavu online/offline.
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, max 200
- REQ: orderBy (Int, Y) Sort by: 0-by name, 1-reverse order by time, 2-reverse order by name
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/gateway/delete` – Smaže gateway.
- REQ: gatewayId (Int, Y) Gateway ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/gateway/rename` – Přejmenuje gateway.
- REQ: gatewayId (Int, Y) gateway id
- REQ: gatewayName (String, Y) new gateway name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/gateway/transfer` – Převede gateway na jiný účet (nevratné!).
- REQ: receiverUsername (String, Y) The receiver's username, must be a registered account.
- REQ: gatewayIdList (String, Y) Gateway ID list, example:[1234,3332]
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/gateway/listByLock` – Vrátí seznam gateway přiřazených k zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: list (JSONArray) list of records

`POST /api/v3/gateway/listLock` – Vrátí seznam zámků připojených k gateway.
- REQ: gatewayId (Int, Y) Gateway ID
- RESP: list (JSONArray) list of records

`POST /api/v3/gateway/listDevice` – Vrátí seznam zařízení připojených ke gateway.
- REQ: gatewayId (Int, Y) Gateway ID
- RESP: list (JSONArray) record list

`POST /api/v3/gateway/detail` – Vrátí detailní informace o gateway.
- REQ: gatewayId (Int, Y) GatewayId, from init gateway API
- RESP: gatewayId (Int) Gateway ID
- RESP: gatewayMac (String) Gateway MAC
- RESP: gatewayName (String) Gateway name
- RESP: gatewayVersion (Int) The version of gateway, 1-G1，2-G2，3-G3(wired gateway)，4-G4（4G gateway）
- RESP: networkName (String) The network name gateway connected to.
- RESP: networkMac (String) Mac address of the network to which the gateway is connected
- RESP: lockNum (Int) The number of locks connected to the gateway.
- RESP: isOnline (Int) Is it online: 0-No, 1-Yes. The gateway will maintain a TCP connection with the gateway server, the cloud server consider it online if the connection is present,

`POST /api/v3/gateway/isInitSuccess` – Ověří podle MAC adresy, zda byla gateway úspěšně inicializována.
- REQ: gatewayNetMac (String, Y) The Mac which you will get when calling the APP SDK method to add a gateway
- RESP: gatewayId (Int) Gateway ID

`POST /api/v3/gateway/uploadDetail` – Upload detail info of gateway
- REQ: gatewayId (Int, Y) Gateway ID, returned by: Gateway init
- REQ: modelNum (String, Y) Product model
- REQ: hardwareRevision (String, Y) Hardware version
- REQ: firmwareRevision (String, Y) Firmware version
- REQ: networkName (String, Y) The network name gateway connected to
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/gateway/upgradeCheck` – Zkontroluje dostupnost aktualizace firmwaru.
- REQ: gatewayId (Int, Y) Gateway ID
- RESP: needUpgrade (Int) Is upgrading available: 0-No, 1-Yes, 2-Unknown
- RESP: firmwareInfo (String) Firmware info, will be used in APP SDK
- RESP: version (String) Latest firmware version

`POST /api/v3/gateway/setUpgradeMode` – Nastaví gateway.
- REQ: gatewayId (Int, Y) Gateway ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message


## IC Card APIs

`POST /api/v3/identityCard/add` – Přidá IC kartu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: cardNumber (String, Y) Card number (1) card number returned by by APP SDK； (2) read from card reader.
- REQ: cardName (String, N) Card name
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond), when startDate and endDate all set to 0 it will be permanent.
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond), when startDate and endDate all set to 0 it will be permanent.
- REQ: cardType (Int, N) Card type：1-noraml card、4-cyclic(default value is 1)
- REQ: cyclicConfig (JSONArray, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: addType (Int, Y) Method: 1-via phone bluetooth，should call APP SDK method to add card first. 2-via gateway or WiFi lock ，you can call this api directly if it's a WiFi lock or it
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/identityCard/list` – Vrátí stránkovaný seznam IC karty.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: searchStr (String, N) Search keywords, fuzzy search by IC card name
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page，max 200
- REQ: orderBy (Int, Y) Sort by: 0-by name, 1-reverse order by time, 2-reverse order by name
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/identityCard/delete` – Smaže IC kartu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: cardId (Int, Y) Card ID，get from Cloud API: Add card
- REQ: deleteType (Int, Y) Method: 1-delete with App via Bluetooth, you should delete via bluetooth first 2-delete via gateway or WiFi lock, you can call this api directly if it's a WiFi 
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/identityCard/changePeriod` – Změní časovou platnost IC karty.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: cardId (Int, Y) Card ID，get from Cloud API: Add card
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond), you can't change it to permanent
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond), you can't change it to permanent
- REQ: cyclicConfig (JSONArray, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: changeType (Int, Y) Method: 1-via phone bluetooth, you should call APP SDK method first 2- via gateway or WiFi lock , you can call this api directly if it's a WiFi lock or it's con
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/identityCard/clear` – Smaže všechny IC karty na zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/identityCard/rename` – Přejmenuje IC kartu.
- REQ: lockId (Int, Y) Lock ID
- REQ: cardId (Int, Y) Card ID，get from Cloud API: Add card
- REQ: cardName (String, Y) New card name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message


## Fingerprint APIs

`POST /api/v3/fingerprint/add` – Přidá otisk prstu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: fingerprintNumber (Int, Y) Fingerprint number, get from Adding a fingerprint via APP SDK
- REQ: fingerprintType (Int, Y) Fingerprint type: 1-normal, 4-recurring
- REQ: fingerprintName (String, N) Fingerprint name
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond), when startDate and endDate all set to 0 it will be permanent.
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond), when startDate and endDate all set to 0 it will be permanent.
- REQ: cyclicConfig (JSONArray, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/fingerprint/list` – Vrátí stránkovaný seznam otisku prstu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: searchStr (String, N) Search keywords, fuzzy search by fingerprint name
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page，max 200
- REQ: orderBy (Int, Y) Sort by: 0-by name, 1-reverse order by time, 2-reverse order by name
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/fingerprint/delete` – Smaže otisk prstu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: fingerprintId (Int, Y) Fingerprint ID，get from cloud API: Add fingerprint
- REQ: deleteType (Int, Y) Method: 1-delete with App via Bluetooth, you should delete via bluetooth first 2-delete via gateway or WiFi lock, you can call this api directly if it's a WiFi 
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/fingerprint/changePeriod` – Změní časovou platnost otisku prstu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: fingerprintId (Int, Y) Fingerprint ID, get from cloud API: Add fingerprint
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond), you can't change it to permanent
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond), you can't change it to permanent
- REQ: cyclicConfig (JSONArray, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: changeType (Int, Y) Method: 1-via phone bluetooth, you should call APP SDK method first 2- via gateway or WiFi lock , you can call this api directly if it's a WiFi lock or it's con
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/fingerprint/clear` – Smaže všechny otisku prstu na zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/fingerprint/rename` – Přejmenuje otisk prstu.
- REQ: lockId (Int, Y) Lock ID
- REQ: fingerprintId (Int, Y) fingerprint id
- REQ: fingerprintName (String, Y) new fingerprint name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message


## Face APIs

`POST /api/v3/face/getFeatureDataByPhoto` – Vrátí záznam obličeje podle zadaných parametrů.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: image (File/Image, Y) Face photo, size limit: 300KB～2MB, format: jpg、png、bmp
- RESP: featureData (String) Human face feature data, Hexadecimal string

`POST /api/v3/face/add` – Přidá záznam obličeje.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: name (String, N) Face name
- REQ: faceNumber (String, N) Face Number Face Number return by APP SDK； Don't need this parameter if add face via gateway or WiFi lock
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond), when startDate and endDate all set to 0 it will be permanent.
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond), when startDate and endDate all set to 0 it will be permanent.
- REQ: type (Int, N) 1-normal，4-cyclic(default value is 1)
- REQ: cyclicConfig (JsonArray, N) Cyclic operation time setting (need to pass only for cyclic type)
- REQ: featureData (String, N) Face feature data, Gained by Get feature data by photo API，this parameter will be used in remote add face
- REQ: addType (Int, Y) Method: 1-via phone bluetooth，should call APP SDK method to add face first. 2-via gateway or WiFi lock ，you can call this api directly if it's a WiFi lock or it
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/face/list` – Vrátí stránkovaný seznam záznamu obličeje.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: searchStr (String, N) Search string (name fuzzy matching)
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page，max 200
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/face/delete` – Smaže záznam obličeje.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: faceId (Int, Y) Face ID，generated from Add face API
- REQ: type (Int, Y) Method: 1-delete with App via Bluetooth, you should delete via bluetooth first 2-delete via gateway or WiFi lock, you can call this api directly if it's a WiFi 
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/face/changePeriod` – Změní časovou platnost záznamu obličeje.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: faceId (Int, Y) Face ID, generated from Add face API
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond), you can't change it to permanent
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond), you can't change it to permanent
- REQ: cyclicConfig (String, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: type (Int, Y) Method: 1-via phone bluetooth, you should call APP SDK method first 2- via gateway or WiFi lock , you can call this api directly if it's a WiFi lock or it's con
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/face/clear` – Smaže všechny záznamu obličeje na zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/face/rename` – Přejmenuje záznam obličeje.
- REQ: lockId (Int, Y) Lock ID
- REQ: faceId (Int, Y) Face ID，generated from Add face API
- REQ: name (String, Y) New face name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message


## Unlock record APIs

`POST /api/v3/lockRecord/list` – Vrátí historii odemykání zámku (kdo, kdy a čím odemkl) v zadaném časovém rozsahu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: startDate (Long, N) Start time, search by operate time(timestamp in millisecond)
- REQ: endDate (Long, N) End time, search by operate time (timestamp in millisecond)
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, max 200
- REQ: uid (Int, N) User ID，for searching the operation records of a certain user
- REQ: recordType (Int, N) Record type：-5-face、-4-QR code、4-keyboard password、7-IC card、8-fingerprint、55-remote，Default return all records
- REQ: searchStr (String, N) Search key string：face number、QR code number、password、IC card number、fingerprint number、remote Mac
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/lockRecord/upload` – Nahraje záznamy odemknutí načtené ze zámku přes SDK.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: records (String, Y) Lock records, please make sure it's read from lock by APP SDK.
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lockRecord/delete` – Smaže záznam odemknutí.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: recordIdList (Array, Y) Records Id list，from Lock record list API
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lockRecord/clear` – Smaže všechny záznamů odemykání na zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message


## Group APIs

`POST /api/v3/group/add` – Přidá skupinu zámků.
- REQ: name (String, Y) Group name
- RESP: groupId (Int) Group ID

`POST /api/v3/group/list` – Vrátí stránkovaný seznam skupiny zámků.
- REQ: orderBy (Int, Y) Sort by: 0-by name, 1-reverse order by time, 2-reverse order by name
- RESP: list (JSONArray) list of records

`POST /api/v3/lock/setGroup` – Přiřadí zámek do skupiny.
- REQ: lockId (String, Y) Lock ID, generated by Lock init
- REQ: groupId (String, Y) Group ID, from Get gruop list API, this parameter set 0 cancel grouping
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/group/delete` – Smaže skupinu zámků.
- REQ: groupId (String, Y) Group ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/group/update` – Upraví vlastnosti skupiny zámků.
- REQ: groupId (String, Y) Group ID
- REQ: name (String, Y) New group name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/group/setDeviceGroup` – Nastaví skupinu zámků.
- REQ: deviceType (String, Y) Equipment type 0: Lock. 1: Electricity meter. 2: Water meter.
- REQ: deviceId (String, Y) Device ID
- REQ: groupId (String, Y) Group ID, returned by the " Get Group List " interface; passing 0 cancels the group.
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: description (String) Error description


## Lock upgrade APIs

`POST /api/v3/lock/upgradeCheck` – Zkontroluje dostupnost aktualizace firmwaru.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: needUpgrade (Int) Is upgrading available: 0-No, 1-Yes, 2-Unknown
- RESP: firmwareInfo (String) Lock firmware info
- RESP: firmwarePackage (String) Firmware package
- RESP: version (String) Latest firmware version

`POST /api/v3/lock/upgradeRecheck` – Přepne zařízení do režimu aktualizace firmwaru.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: lockData (String, Y) Lock data, get from APP SDK
- RESP: needUpgrade (Int) Is upgrading available: 0-No, 1-Yes, 2-Unknown
- RESP: firmwareInfo (String) Firmware info
- RESP: firmwarePackage (String) Firmware package
- RESP: version (String) Latest firmware version


## Wireless Keyboard APIs

`POST /api/v3/wirelessKeypad/add` – Přidá bezdrátovou klávesnici.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: wirelessKeypadNumber (String, Y) Wireless keypad serial number
- REQ: wirelessKeypadName (String, Y) Wireless keypad name
- REQ: wirelessKeypadMac (String, Y) Wireless keypad MAC
- REQ: wirelessKeypadFeatureValue (String, Y) Feature value of wireless keypad
- REQ: electricQuantity (Int, N) Wireless keypad battery
- RESP: wirelessKeypadId (Int) Wireless keypad ID

`POST /api/v3/wirelessKeypad/listByLock` – Vrátí seznam bezdrátové klávesnice přiřazených k zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: list (JSONObject list of records) 

`POST /api/v3/wirelessKeypad/delete` – Smaže bezdrátovou klávesnici.
- REQ: wirelessKeypadId (Int, Y) Wireless keypad ID，generated by Add wireless keypad
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/wirelessKeypad/rename` – Přejmenuje bezdrátovou klávesnici.
- REQ: wirelessKeypadId (Int, Y) Wireless keypad ID，generated by Add wireless keypad
- REQ: wirelessKeypadName (String, Y) New wireless keypad name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/wirelessKeypad/upgradeCheck` – Zkontroluje dostupnost aktualizace firmwaru.
- REQ: wirelessKeypadId (Int, Y) wireless keypad ID
- REQ: slotNumber (Int, Y) slot number

`POST /api/v3/wirelessKeypad/upgradeSuccess` – Ověří, zda se aktualizace firmwaru povedla.
- REQ: wirelessKeypadId (Int, Y) wireless keypad ID
- REQ: slotNumber (Int, Y) slot number
- REQ: featureValue (String, N) feature value


## Remote APIs

`POST /api/v3/remote/add` – Přidá dálkový ovladač.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: number (String, Y) Remote serial number
- REQ: name (String, N) Name
- REQ: mac (String, Y) Mac
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, Y) The time when it becomes valid (timestamp in millisecond)
- REQ: type (Int, N) Type: 1-normal, 4-recurring
- REQ: cyclicConfig (JsonArray, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: electricQuantity (Int, Y) Battery
- REQ: firmwareInfo (JSONObject, Y) Fireware info
- RESP: remoteId (Int) Remote ID

`POST /api/v3/remote/listByLock` – Vrátí seznam dálkového ovladače přiřazených k zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: orderBy (Int, Y) Sort by: 0-by name, 1-reverse order by time, 2-reverse order by name
- RESP: list (JSONObject list of records) 

`POST /api/v3/remote/delete` – Smaže dálkový ovladač.
- REQ: remoteId (Int, Y) remote ID，generated by Add remote
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/remote/clear` – Smaže všechny dálkového ovladače na zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/remote/update` – Upraví vlastnosti dálkového ovladače.
- REQ: remoteId (Int, Y) remote ID，generated by Add remote
- REQ: name (String, Y) New remote name
- REQ: startDate (Long, N) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, N) The time when it becomes valid (timestamp in millisecond)
- REQ: cyclicConfig (JsonArray, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: changeType (Int, N) Method: 1-via phone bluetooth, you should call APP SDK method first 2- via gateway or WiFi lock , you can call this api directly if it's a WiFi lock or it's con
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/remote/upgradeCheck` – Zkontroluje dostupnost aktualizace firmwaru.
- REQ: remoteId (Int, Y) Remote ID
- REQ: modelNum (String, N) product model
- REQ: hardwareRevision (String, N) hardware version number
- REQ: firmwareRevision (String, N) firmware version number

`POST /api/v3/remote/upgradeSuccess` – Ověří, zda se aktualizace firmwaru povedla.
- REQ: remoteId (Int, Y) remote ID
- REQ: featureValue (String, N) feature value


## Standalone Door Sensor

`POST /api/v3/standaloneDoorSensor/add` – Přidá položku.
- REQ: name (String, Y) Name
- REQ: doorSensorData (String, Y) Independent door sensor data must be generated by the APP SDK initial interface.
- REQ: wifiName (String, Y) WIFI name
- RESP: doorSensorId (Int) Door sensor ID

`POST /api/v3/standaloneDoorSensor/list` – Vrátí stránkovaný seznam položky.
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 200
- REQ: searchStr (String, N) Search door sensor name
- RESP: list (JSONObject) list

`POST /api/v3/standaloneDoorSensor/configNetwork` – Nastaví konfiguraci položky.
- REQ: doorSensorId (Int, Y) Door sensor ID
- REQ: doorSensorData (String, Y) Independent door sensor data must be generated by configuring the network interface in the APP SDK.
- REQ: wifiName (String, Y) WIFI name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: errmsg (String) Error information

`POST /api/v3/standaloneDoorSensor/listRecord` – Vrátí historii záznamů položky.
- REQ: doorSensorId (Int, Y) Door sensor ID
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 200
- RESP: list (JSONObject) list

`POST /api/v3/standaloneDoorSensor/update` – Upraví vlastnosti položky.
- REQ: doorSensorId (Int, Y) Standalone door sensor ID
- REQ: name (String, Y) Name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: errmsg (String) Error information

`POST /api/v3/standaloneDoorSensor/delete` – Smaže položku.
- REQ: doorSensorId (Int, Y) Door sensor ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: errmsg (String) Error information

`POST /api/v3/standaloneDoorSensor/addDoorSensorUser` – Přidá položku.
- REQ: doorSensorId (Int, Y) Door sensor ID
- REQ: account (String, Y) Account
- REQ: username (String, Y) Username
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: errmsg (String) Error information

`POST /api/v3/standaloneDoorSensor/listDoorSensorUser` – Vrátí stránkovaný seznam položky.
- REQ: doorSensorId (Int, Y) door sensor ID
- REQ: searchStr (String, N) Query Username
- RESP: list (JSONObject) list

`POST /api/v3/standaloneDoorSensor/deleteDoorSensorUser` – Smaže položku.
- REQ: id (Int, Y) Share ID
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: errmsg (String) Error information

`POST /api/v3/standaloneDoorSensor/configAlertFlag` – Nastaví konfiguraci položky.
- REQ: doorSensorId (Int, Y) Door sensor ID
- REQ: notCloseAlertFlag (Int, Y) Door not closed reminder indicator: Value range 1 - Open, 2 - Closed
- REQ: notCloseAlertSecondNum (Int, N) Door not closed reminder time, unit: seconds, range: 1~900 seconds.
- REQ: longTimeNotOpenAlertFlag (Int, Y) Long-term inactivity reminder indicator: Value range 1 - On, 2 - Off
- REQ: longTimeNotOpenDayNum (Int, N) Long-term door inactivity reminder time, unit: days, range: 1-15 days.
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: errmsg (String) Error information

`POST /api/v3/standaloneDoorSensor/getAlertFlag` – Vrátí položku podle zadaných parametrů.
- REQ: doorSensorId (Int, Y) DS3 ID
- RESP: notCloseAlertFlag (Int) Door not closed reminder indicator: Value range 1 - Open, 2 - Closed
- RESP: notCloseAlertSecondNum (Int) Door not closed reminder time, unit: seconds, range: 1~900 seconds.
- RESP: longTimeNotOpenAlertFlag (Int) Long-term inactivity reminder indicator: Value range 1 - On, 2 - Off
- RESP: longTimeNotOpenDayNum (Int) Long-term door inactivity reminder time, unit: days, range: 1-15 days.

`POST /api/v3/doorSensor/add` – Přidá dveřní senzor.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: name (String, N) Door sensor name
- REQ: electricQuantity (Int, Y) Door sensor battery level
- REQ: firmwareInfo (JSONObject, Y) Door sensor firmware verion info
- REQ: mac (String, Y) Door sensor MAC
- REQ: number (String, Y) Door sensor number
- RESP: modelNum (String) Model number
- RESP: hardwareRevision (String) hardware revision
- RESP: firmwareRevision (String) firmware revision

`POST /api/v3/doorSensor/query` – Zjistí aktuální stav dveřního senzoru (vyžaduje gateway).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: doorSensorId (Int) Door sensor ID
- RESP: name (String) Door sensor name
- RESP: electricQuantity (Int) Door sensor battery level
- RESP: version (String) firmware version
- RESP: mac (String) Door sensor MAC
- RESP: number (String) Door sensor number
- RESP: doorNotClosedWarningTime (Int) Door unclosed alarm time setting, in seconds, 0 mean off

`POST /api/v3/doorSensor/delete` – Smaže dveřní senzor.
- REQ: doorSensorId (Int, Y) Door sensor ID, generated by Add door sensor
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/doorSensor/update` – Upraví vlastnosti dveřního senzoru.
- REQ: doorSensorId (Int, Y) Door sensor id, generated by Add door sensor
- REQ: name (String, N) New door sensor name
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/doorSensor/upgradeCheck` – Zkontroluje dostupnost aktualizace firmwaru.
- REQ: doorSensorId (Int, Y) door sensor ID
- REQ: modelNum (String, N) product model
- REQ: hardwareRevision (String, N) hardware version number
- REQ: firmwareRevision (String, N) firmware version number

`POST /api/v3/doorSensor/upgradeSuccess` – Ověří, zda se aktualizace firmwaru povedla.
- REQ: doorSensorId (Int, Y) door Sensor ID

`POST /api/v3/doorSensor/listRecord` – Vrátí historii záznamů dveřního senzoru.
- REQ: lockId (Int, Y) Lock ID，Generate by lock initialize
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page: 20 by default, 200 by maximum.
- RESP: list (JSONArray) Record list
- RESP: pageNo (Int) Page numbers start from 1
- RESP: pageSize (Int) Number of pages per page, maximum 200
- RESP: pages (Int) Total pages
- RESP: total (Int) Total number of items


## NB-IoT APIs

`POST /api/v3/lock/registerNb` – Zaregistruje nový virtuální zámek pro příjem eKey.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: nbNodeId (String, Y) NB-IoT node id
- REQ: nbCardNumber (String, Y) NB-IoT card number
- REQ: nbOperator (String, Y) NB-IoT operator：46011-China Telecom、46000-China mobile、21401-Vodafone、50212-Maxis
- REQ: nbRssi (Int, Y) NB RSSI, reference: >20 is strong, 10<i<20 is medium, <-10 is weak
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/lock/getNbDeviceInfo` – Vrátí zámek podle zadaných parametrů.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: nbNodeId (String) NB-IoT node id
- RESP: nbCardNumber (String) NB-IoT card number
- RESP: nbOperator (String) NB-IoT operator：46011-China Telecom、46000-China mobile、21401-Vodafone、50212-Maxis
- RESP: nbOperatorName (String) NB-IoT operator name
- RESP: nbRssi (Int) NB RSSI, reference: >20 is strong, 10<i<20 is medium, <-10 is weak
- RESP: updateDate (Long) NB RSSI last updated date (timestamp in millisecond)

`POST /api/v3/lock/getNbPlatformIpAndPort` – Vrátí zámek podle zadaných parametrů.
- RESP: list (JSONArray) list of records


## QR code APIs

`POST /api/v3/qrCode/add` – Vytvoří QR kód pro odemčení zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: name (String, N) Qr code name
- REQ: type (Int, Y) QR code type, 1-period, 2-permanent, 4-cyclic
- REQ: startDate (Long, N) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, N) The time when it is expired (timestamp in millisecond)
- REQ: refreshTime (Int, N) QR code refresh time, minutes per unit of time, default value is 10, maximum 1440
- REQ: cyclicConfig (JSONArray String, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: addType (Int, Y) Adding method for random QR code: 0- Cloud method. If left blank, the default is 0. A QR code is generated from the cloud. The QR code is generated by the cloud
- REQ: qrCodeNumber (String, N) This parameter is required when adding a custom QR code: Custom QR codes added via APP Bluetooth or gateway require a QR code field. The QR code cannot be large
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/qrCode/list` – Vrátí stránkovaný seznam QR kódu.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, max 200
- REQ: name (String, N) QRcode‘s name
- RESP: list (JSONArray) list of records
- RESP: pageNo (Int) Page no, start from 1
- RESP: pageSize (Int) Items per page, max 200
- RESP: pages (Int) Total number of pages
- RESP: total (Int) Total number of records

`POST /api/v3/qrCode/getData` – Vrátí QR kód podle zadaných parametrů.
- REQ: qrCodeId (Int, Y) QR code ID, generated by Add QR code
- RESP: lockAlias (String) Lock alias
- RESP: type (Int) QR code type, 1-period, 2-permanent, 4-cyclic
- RESP: qrCodeNumber (Int) QR code number: the unique number of QR code in a lock. It's will be contained in the unlocking records for identifing which code unlock the lock.
- RESP: qrCodeContent (String) QR code data for generating QR code image.
- RESP: name (String) Qr code name
- RESP: startDate (Long) The time when it becomes valid, timestamp in milliseconds
- RESP: endDate (Long) The time when it is expired, timestamp in milliseconds
- RESP: refreshTime (Int) QR code refresh time, time in minutes
- RESP: cyclicConfig (JSONArray) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- RESP: status (Int) Status: 1-normal, 2-invalid or expired, 3-pending

`POST /api/v3/qrCode/update` – Upraví vlastnosti QR kódu.
- REQ: qrCodeId (Int, Y) QR code id, generated by Add QR code
- REQ: name (String, N) Qr code name
- REQ: startDate (Long, N) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, N) The time when it is expired (timestamp in millisecond)
- REQ: refreshTime (Int, N) QR code refresh time, time in minutes
- REQ: cyclicConfig (JSONArray String, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: type (Int, Y) QR code types: 1-Time-limited, 2-Permanent, 4-Recurring
- REQ: changeType (Int, Y) Modification methods: 1- Modify via APP Bluetooth. You must modify via APP Bluetooth first before calling this interface. 2- Modify remotely via gateway or WiFi
- RESP: startTime (Int) Start time of cyclic, in minutes, for example 480 for 8:00
- RESP: endTime (Int) End time of cyclic, in minutes, for example 1080 for 18:00
- RESP: weekDay (Int) Week day, 1-7, 1 for monday and 7 for sunday.

`POST /api/v3/qrCode/delete` – Smaže QR kód.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: qrCodeId (Int, Y) QR code ID, generated by Add QR code
- REQ: deleteType (Int, Y) Deletion methods: 1- Delete via APP Bluetooth. You must delete via APP Bluetooth first before calling this interface. 2- Delete remotely via gateway or WiFi loc
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message
- RESP: description (String) Error description

`POST /api/v3/qrCode/clear` – Smaže všechny QR kódu na zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: type (Int, Y) Clearing methods: 1- Clear via APP Bluetooth. You must clear via APP Bluetooth first before calling this interface. 2- Clear remotely via gateway or WiFi lock. 
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message


## WiFi lock APIs

`POST /api/v3/wifiLock/updateNetwork` – Nahraje síťovou konfiguraci WiFi zámku.
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- REQ: networkName (String, N) The network name lock connected to
- REQ: wifiMac (String, N) Wifi Mac
- REQ: rssi (Int, N) Wifi RSSI
- REQ: useStaticIp (Boolean, N) Use static IP or not
- REQ: ip (String, N) Static IP address
- REQ: subnetMask (String, N) Subnet mask
- REQ: defaultGateway (String, N) Default gateway
- REQ: preferredDns (String, N) Preferred DNS
- REQ: alternateDns (String, N) Alternate DNS
- RESP: errcode (Int) Error code
- RESP: errmsg (String) Error message

`POST /api/v3/wifiLock/detail` – Vrátí síťové informace WiFi zámku (IP, síla signálu).
- REQ: lockId (Int, Y) Lock ID, generated by Lock init
- RESP: networkName (String) The network name lock connected to
- RESP: ip (String) Static IP address
- RESP: subnetMask (String) Subnet mask
- RESP: defaultGateway (String) Default gateway
- RESP: wifiMac (String) Wifi Mac
- RESP: rssiGrade (Int) WIFI RSSI grade：3-strong，2-midium，1-weak，0-unknown
- RESP: isOnline (Int) Online of offline：0-offline，1-online
- RESP: powerSavingMode (Int) Is in power saving mode：0-unknown、1-yes、2-no
- RESP: preferredDns (String) Preferred DNS
- RESP: alternateDns (String) Alternate DNS


## Palm Vein APIs

`POST /api/v3/palmVein/list` – Vrátí stránkovaný seznam záznamu dlaně.
- REQ: lockId (Int, Y) id of a lock
- REQ: searchStr (String, N) Search string (name fuzzy matching)
- REQ: pageNo (Int, Y) Page no, start from 1
- REQ: pageSize (Int, Y) Items per page, max 200
- RESP: id (Int) id of a palm vein
- RESP: name (String) name of a palm vein
- RESP: number (String) number of a palm vein
- RESP: status (String) Status: 1-normal, 2-invalid, 3-pending
- RESP: nickname (String) nickname of creator
- RESP: startDate (Long) The time when it becomes valid (timestamp in millisecond)
- RESP: endDate (Long) The time when it is expired (timestamp in millisecond)
- RESP: type (Int) Type：1-Normal、4-Recurring
- RESP: cyclicConfig (JsonArray) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- RESP: createDate (Long) Creation time

`POST /api/v3/palmVein/add` – Přidá záznam dlaně.
- REQ: lockId (Int, Y) the id of a lock
- REQ: name (String, N) name of this palm vein
- REQ: number (String, Y) number
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond)
- REQ: type (Int, N) 1、Normal、4-Recurring，type = 1 by default.
- REQ: cyclicConfig (JsonArray, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/palmVein/rename` – Přejmenuje záznam dlaně.
- REQ: id (Int, Y) id of a palm vein
- REQ: name (String, N) new name
- RESP: errcode (Int) error code
- RESP: errmsg (String) error message
- RESP: description (String) error message in Chinese

`POST /api/v3/palmVein/changePeriod` – Změní časovou platnost záznamu dlaně.
- REQ: id (Int, Y) id of a palm vein
- REQ: startDate (Long, Y) The time when it becomes valid (timestamp in millisecond)
- REQ: endDate (Long, Y) The time when it is expired (timestamp in millisecond)
- REQ: cyclicConfig (JsonArray, N) Recurring time period, the valid time period of each week day must be the same, for example: [{"weekDay":1, "startTime":480,"endTime":1080},{"weekDay":2, "start
- REQ: type (Int, N) Method: 1-APP, 2-remote synchronous delivery, 4-WiFi wake-up asynchronous delivery; if not transmitted, the default APP is deleted
- RESP: startTime (Int) The time when it becomes valid, in minute, for example 480 for 8:00
- RESP: endTime (Int) The time when it becomes validit is expired, in minute, for example 1080 for 18:00
- RESP: weekDay (Int) Week day：1-7, 1-Monday, 2-Tuesday...7-Sunday

`POST /api/v3/palmVein/delete` – Smaže záznam dlaně.
- REQ: id (Int, Y) id of a palm vein
- REQ: type (Int, N) Method: 1-APP, 2-remote synchronous delivery, 4-WiFi wake-up asynchronous delivery; do not transmit the default APP
- RESP: errcode (Int) error code
- RESP: errmsg (String) error message
- RESP: description (String) error message in Chinese

`POST /api/v3/palmVein/clear` – Smaže všechny záznamu dlaně na zámku.
- REQ: lockId (Int, Y) id of a lock
- RESP: errcode (Int) error code
- RESP: errmsg (String) error message
- RESP: description (String) error message in Chinese


## Admin APIs

`POST /api/v3/electricMeter/listGroup` – Vrátí stránkovaný seznam elektroměru.

`POST /api/v3/electricMeter/addGroup` – Přidá elektroměr.

`POST /api/v3/electricMeter/deleteGroup` – Smaže elektroměr.

`POST /api/v3/electricMeter/renameGroup` – Přejmenuje elektroměr.

`POST /api/v3/electricMeter/setGroup` – Přiřadí zámek do skupiny.

`POST /api/v3/electricMeter/list` – Vrátí stránkovaný seznam elektroměru.
- REQ: groupId (Int, N) Group ID
- REQ: searchStr (String, N) Search criteria include searching by meter name and a list of meter IDs.
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 1000

`POST /api/v3/electricMeter/add` – Přidá elektroměr.
- REQ: mac (String, Y) Electricity Meter MAC
- REQ: name (Int, Y) Electricity meter name

`POST /api/v3/electricMeter/detail` – Vrátí detailní informace o elektroměru.
- REQ: electricMeterId (Int, Y) Electricity meter ID

`POST /api/v3/electricMeter/syncState` – Meter reading
- REQ: electricMeterId (String, Y) Electricity meter ID

`POST /api/v3/electricMeter/recharge` – Administrator recharge
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: rechargeAmount (Double, Y) Recharge amount
- REQ: rechargeKwh (Double, Y) Recharge battery

`POST /api/v3/electricMeter/updatePrice` – Upraví vlastnosti elektroměru.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: price (Double, Y) Unit price

`POST /api/v3/electricMeter/controlOnOff` – Turn the power meter on/off
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: onOff (Int, Y) Power-on status: 0 - No 1 - Yes

`POST /api/v3/electricMeter/clear` – Smaže všechny elektroměru na zámku.
- REQ: electricMeterId (String, Y) Electricity meter ID

`POST /api/v3/electricMeter/rename` – Přejmenuje elektroměr.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: name (String, Y) Electricity meter name

`POST /api/v3/electricMeter/listOperationRecords` – Vrátí stránkovaný seznam elektroměru.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: recordType (String, N) Operation types: 1: Recharge, 2: Power off, 3: Power on, 4: Meter reading, 5: Unit price modification, 6: Reset
- REQ: searchStr (String, N) Search results
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 1000

`POST /api/v3/electricMeter/listRecords` – Vrátí historii záznamů elektroměru.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: dateType (Int, Y) Date type, 0: day, 1: month, 2: year
- REQ: dateStr (String, Y) dateType = 0 indicates a query by day, and dateStr must be accurate to the day: 2024-09-06; dateType = 1 indicates a query by month, and dateStr must be accurat

`POST /api/v3/electricMeter/updateMaxPower` – Upraví vlastnosti elektroměru.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: maxPower (Int, Y) Maximum power

`POST /api/v3/electricMeter/updatePayMode` – Upraví vlastnosti elektroměru.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: payMode (Int, Y) 0 - Energy Metering Mode 1 - Prepaid
- REQ: price (Double, N) Unit price, required under prepaid model

`POST /api/v3/electricMeter/upgradeCheck` – Zkontroluje dostupnost aktualizace firmwaru.
- REQ: electricMeterId (String, Y) Electricity meter ID

`POST /api/v3/electricMeter/upgradeSuccess` – Ověří, zda se aktualizace firmwaru povedla.
- REQ: electricMeterId (String, Y) Electricity meter ID

`POST /api/v3/electricMeter/syncSameAdmin` – 蓝牙广播抄表

`POST /api/v3/electricMeter/gatewayList` – Gateway associated with the electricity meter
- REQ: electricMeterId (String, Y) Electricity meter ID

`POST /api/v3/electricMeter/createExecuteToken` – Generate an executeToken that can be used for top-ups.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: rechargeKwh (Double, Y) Recharge amount
- REQ: rechargeAmount (String, Y) Recharge amount

`POST /api/v3/electricMeter/decodeBleAdvertising` – Bluetooth broadcast meter reading
- REQ: mac (String, Y) Electricity Meter MAC
- REQ: executeResponse (Int, Y) Broadcast data obtained from the SDK

`POST /api/v3/electricMeter/catOneDetail` – Obtain 4G meter network info
- REQ: electricMeterId (String, Y) Electricity meter ID

`POST /api/v3/electricMeter/configCatOneInfo` – Nastaví konfiguraci elektroměru.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: catOneNodeId (String, Y) Module number
- REQ: catOneCardNumber (String, Y) Card number
- REQ: catOneOperator (String, Y) Carriers: CHN-CT - China Telecom, CHINAMOBILE - China Mobile, CHINA MOBILE - China Mobile, CHN-UNICOM - China Unicom
- REQ: catOneImsi (String, Y) Phone number
- REQ: catOneRssi (Int, Y) Signal value
- REQ: catOneApn (String, N) APN

`POST /api/v3/waterMeter/listGroup` – Vrátí stránkovaný seznam vodoměru.

`POST /api/v3/waterMeter/addGroup` – Přidá vodoměr.

`POST /api/v3/waterMeter/deleteGroup` – Smaže vodoměr.

`POST /api/v3/waterMeter/renameGroup` – Přejmenuje vodoměr.

`POST /api/v3/waterMeter/setGroup` – Přiřadí zámek do skupiny.

`POST /api/v3/waterMeter/list` – Vrátí stránkovaný seznam vodoměru.
- REQ: groupId (Int, N) Water Meter ID
- REQ: searchStr (String, N) Search criteria include searching by meter name and meter number/water meter ID list.
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 1000

`POST /api/v3/waterMeter/add` – Přidá vodoměr.
- REQ: mac (String, Y) Water Meter MAC
- REQ: name (Int, Y) Water meter name

`POST /api/v3/waterMeter/detail` – Vrátí detailní informace o vodoměru.
- REQ: waterMeterId (Int, Y) Water Meter ID

`POST /api/v3/waterMeter/syncState` – Meter reading
- REQ: waterMeterId (String, Y) Water Meter ID

`POST /api/v3/waterMeter/recharge` – Administrator recharge
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: rechargeAmount (Double, Y) recharge money amount
- REQ: rechargeM3 (Double, Y) recharge water amount

`POST /api/v3/waterMeter/updatePrice` – Upraví vlastnosti vodoměru.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: price (Double, Y) Unit price

`POST /api/v3/waterMeter/controlOnOff` – Turn the water meter on/off
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: onOff (Int, Y) Water supply status: 0 - No 1 - Yes

`POST /api/v3/waterMeter/clear` – Smaže všechny vodoměru na zámku.
- REQ: waterMeterId (String, Y) Water Meter ID

`POST /api/v3/waterMeter/rename` – Přejmenuje vodoměr.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: name (String, Y) Water meter name

`POST /api/v3/waterMeter/listOperationRecords` – Vrátí stránkovaný seznam vodoměru.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: recordType (String, N) Operation types: 1: Recharge, 2: Water outage, 3: Water supply restored, 4: Meter reading, 5: Price modification, 6: Reset.
- REQ: searchStr (String, N) Search terms
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 1000

`POST /api/v3/waterMeter/listRecords` – Vrátí historii záznamů vodoměru.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: dateType (Int, Y) Date type, 0: day, 1: month, 2: year
- REQ: dateStr (String, Y) Search criteria: 2024-09-06, 2024-09, or 2024

`POST /api/v3/waterMeter/updateTotal` – Upraví vlastnosti vodoměru.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: totalM3 (Double, Y) Total water consumption

`POST /api/v3/waterMeter/updatePayMode` – Upraví vlastnosti vodoměru.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: payMode (Int, Y) 0 - Energy Metering 1 - Prepaid
- REQ: price (Double, N) Unit price, required under prepaid model

`POST /api/v3/waterMeter/upgradeCheck` – Zkontroluje dostupnost aktualizace firmwaru.
- REQ: waterMeterId (String, Y) Water Meter ID

`POST /api/v3/waterMeter/upgradeSuccess` – Ověří, zda se aktualizace firmwaru povedla.
- REQ: waterMeterId (String, Y) Water Meter ID

`POST /api/v3/waterMeter/syncSameAdmin` – 蓝牙广播抄表

`POST /api/v3/waterMeter/gatewayList` – Gateway associated with the water meter
- REQ: waterMeterId (String, Y) Water Meter ID

`POST /api/v3/waterMeter/createExecuteToken` – Generate an executeToken that can be used for top-ups.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: rechargeM3 (Double, Y) Recharge warter amount
- REQ: rechargeAmount (String, Y) Recharge money amount

`POST /api/v3/waterMeter/decodeBleAdvertising` – Bluetooth broadcast meter reading
- REQ: mac (String, Y) Water Meter MAC
- REQ: executeResponse (Int, Y) Broadcast data obtained from the SDK

`POST /api/v3/waterMeter/addTask` – Přidá vodoměr.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: taskType (Int, Y) Task types: 1-Set remaining water volume, 2-Reset, 3-Recharge, 4-Water cut-off, 5-Water restoration
- REQ: rechargeAmount (Double, N) Recharge amount
- REQ: rechargeM3 (Double, N) Water recharge
- REQ: remainderM3 (Double, N) Set remaining water volume

`POST /api/v3/waterMeter/cancelTask` – Cancel task
- REQ: waterMeterId (Int, Y) Water Meter ID
- REQ: id (Long, Y) Task ID

`POST /api/v3/waterMeter/finishTask` – Complete a task
- REQ: waterMeterId (Int, Y) Water Meter ID
- REQ: id (Long, Y) Task ID

`POST /api/v3/waterMeter/listTask` – Vrátí stránkovaný seznam vodoměru.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: usedFlag (Int, N) 1: Used, 0: Not used

`POST /api/v3/waterMeter/catOneDetail` – Obtain 4G meter network info
- REQ: waterMeterId (String, Y) Water Meter ID

`POST /api/v3/waterMeter/configCatOneInfo` – Nastaví konfiguraci vodoměru.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: catOneNodeId (String, Y) Module number
- REQ: catOneCardNumber (String, Y) card number
- REQ: catOneOperator (String, Y) Carriers: CHN-CT - China Telecom, CHINAMOBILE - China Mobile, CHINA MOBILE - China Mobile, CHN-UNICOM - China Unicom
- REQ: catOneImsi (String, Y) Phone number
- REQ: catOneRssi (Int, Y) signal value
- REQ: catOneApn (String, N) APN


## Tenant APIs

`POST /api/v3/electricMeterUser/listRecharge` – Vrátí stránkovaný seznam položky.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: recordType (String, N) Operation types: 1: Recharge, 2: Power off, 3: Power on, 4: Meter reading, 5: Unit price modification, 6: Reset
- REQ: searchStr (String, N) Search results
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 1000

`POST /api/v3/electricMeterUser/syncState` – Meter reading by tenant
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: type (Int, Y) 2- Through the gateway

`POST /api/v3/electricMeterUser/recharge` – Tenant recharge
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: type (Int, Y) 2- Through the gateway
- REQ: rechargeAmount (Double, Y) Recharge amount
- REQ: executeToken (String, Y) Token used by tenants when topping up

`POST /api/v3/electricMeterUser/listRecharge` – Vrátí stránkovaný seznam položky.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: recordType (String, N) Operation types: 1: Recharge, 2: Power off, 3: Power on, 4: Meter reading, 5: Unit price modification, 6: Reset
- REQ: searchStr (String, N) Search results
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 1000

`POST /api/v3/electricMeterUser/listRecords` – Vrátí historii záznamů položky.
- REQ: electricMeterId (String, Y) Electricity meter ID
- REQ: dateType (Int, Y) Date type, 0: day, 1: month, 2: year
- REQ: dateStr (String, Y) Search criteria: 2024-09-06, 2024-09, or 2024

`POST /api/v3/waterMeterUser/detail` – Vrátí detailní informace o položky.
- REQ: mac (String, Y) Water Meter MAC

`POST /api/v3/waterMeterUser/syncState` – Meter reading by tenant
- REQ: type (Int, Y) 2- Through the gateway
- REQ: waterMeterId (String, Y) Water Meter ID

`POST /api/v3/waterMeterUser/recharge` – Tenant top-up
- REQ: executeToken (String, Y) Token used by tenants when recharge
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: type (Int, Y) 2- Through the gateway
- REQ: rechargeAmount (Double, Y) Recharge amount

`POST /api/v3/waterMeterUser/listRecharge` – Vrátí stránkovaný seznam položky.
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: recordType (String, N) Operation types: 1: Top up, 2: Water cut off, 3: Water supply restored, 4: Meter reading, 5: Price modification, 6: Reset.
- REQ: searchStr (String, N) Search terms
- REQ: pageNo (Int, Y) Page numbers start from 1
- REQ: pageSize (Int, Y) Number of pages per page, maximum 1000

`POST /api/v3/waterMeterUser/listRecords` – Vrátí historii záznamů položky.
- REQ: dateStr (String, N) Search criteria: 2024-09-06, 2024-09, or 2024
- REQ: waterMeterId (String, Y) Water Meter ID
- REQ: dateType (Int, Y) Date type, 0: day, 1: month, 2: year


## Zařízení Tuya (zásuvky, žaluzie, senzory, BLE zámky)

Tuya se ovládá přes STEJNÝ konektor a stejné hlavičky (X-Client-Id/Secret),
jen na jiných cestách. Konektor sám podepisuje requesty a spravuje token.
Předpoklad: zákazník má vlastní Tuya projekt (platform.tuya.com), propojený
s mobilní aplikací přes QR (Link App Account); jeho Access ID/Secret + datové
centrum jsou uložené v konektoru.

Pohodlné endpointy:
`GET /tuya/devices` – seznam zařízení projektu
- RESP: devices[] (id, name, product_name, online, category, product_id); name = uživatelský název
`GET /tuya/devices/{id}/status` – aktuální hodnoty DP kódů: result[] {code, value}
`GET /tuya/devices/{id}/specification` – co zařízení umí: functions[] (zapisovatelné) + status[]
- functions: každá má code, type (Boolean/Integer/Enum/String/Json/Raw), values (JSON V TEXTU – naparsovat!)
- Integer má min/max/step/scale/unit (scale: hodnota 2372 se scale 1 = 237.2); Enum má range[]
`GET /tuya/devices/{id}` – detail zařízení
`POST /tuya/devices/{id}/commands` – ovládání
- REQ body: {"commands": [{"code": "switch_1", "value": true}]} – lze víc příkazů; offline zařízení vrací chybu

Generická proxy pro jakýkoli Tuya endpoint: `<METODA> /api/tuya/<cesta>`
- konektor request podepíše a doplní token; query u GET se podepisuje automaticky
- příklad: POST /api/tuya/v1.0/iot-03/devices/{id}/commands  (== /tuya/devices/{id}/commands)

Odpovědi Tuya mají obálku {success, code, msg, result} – kontrolovat success i při HTTP 200.

Ukázka (Python) – zapnout zásuvku:
```python
import requests
H = {"X-Client-Id": "CLIENT_ID", "X-Client-Secret": "CLIENT_SECRET"}
B = "https://connect.smartkey.cz"
devices = requests.get(f"{B}/tuya/devices", headers=H).json()["devices"]
dev = devices[0]["id"]
requests.post(f"{B}/tuya/devices/{dev}/commands", headers=H,
              json={"commands": [{"code": "switch_1", "value": True}]})
```

Chybové kódy Tuya:
- 2009: špatné Access ID
- 1004 (sign invalid): špatný Secret nebo špatný čas serveru
- 1106 / 2007: špatné datové centrum projektu, nebo neautorizovaná/nepodporovaná cesta
- 28841002: služba není autorizovaná v Tuya projektu
- 1010 / 1011: token invalid/expired (konektor řeší sám – zahodí a zopakuje)
- result: [] u /tuya/devices: zákazník nenaskenoval QR (Link App Account)


## Chybové kódy zámků SmartKey (errcode)

- 1: failed or means no
- 10000: client_id does not exist
- 10001: invalid client，wrong client_id or client_secret
- 10003: token does not exist
- 10004: token is invalide or revoked
- 10007: invalid account or invalid password
- 10011: invalid refresh_token
- 20002: not lock admin
- 30002: invalid username, only English character and digits is allowed
- 30003: existing registered users
- 30004: invalid userid to delete
- 30005: password must be md5 encrypted
- 30006: exceeds the restrictions of API call number
- 30008: Cross-site access to user data is prohibited. Please use domain names with the 'cn' prefix to request for Mainland Chinese users, for other region's users please use domain names with the 'eu' prefix to request API endpoints
- 80000: date must be current time, in 5 minutes
- 80002: invalid json format
- 90000: internal server error
- -3: Invalid Parameter
- -2018: Permission Denied, many interfaces only allow the lock's top administrator or authorised administrator to request them, some interfaces only require a valid regular key user, please use an access token obtained from a legitimate user's account number and password to request the interface.
- -4063: Please delete/transfer all yours locks first
- -1003: Lock does not exist
- -2025: Frozen lock. Can not operate on it now
- -3011: Cannot Transfer Lock(s) to Yourself
- -4043: The function is not supported for this lock
- -4056: Run out of memory
- -4067: NB Device is not registered
- -4082: Auto locking period invalid
- -1008: eKey does not exist
- -1016: An identical Name exists. Please choose a different Name.
- -1018: This Group does not exist
- -1027: Cant send eKey to this account which has been bound to another account
- -2019: You cannot send an eKey to Yourself
- -2020: You cannot send an eKey to the Admin
- -2023: Can't change the time period now
- -4064: Failed. The eKey can only be sent to a registered account
- -1007: No password data of this lock
- -2009: Invalid Password
- -3006: Invalid Passcode. Passcode should be between 6 - 9 Digits in length
- -3007: The same passcode already exists. Please use another one
- -3008: A Passcode that has never been used on the Lock cannot be changed
- -3009: There is NO SPACE to store Customized Passcodes. Please Delete Un-Used Customized Passcodes and try again
- -2012: The Lock is not connected to any Gateway.
- -3002: The gateway is offline. Please check and try again.
- -3003: The gateway is busy. Please try again later.
- -3016: Cannot Transfer Gateway(s) to Yourself.
- -3034: Network not configed. Please config the network and try again.
- -3035: Wifi lock is in power saving mode, please turn off power saving and try again.
- -3036: The lock is offline. Please check and try again.
- -3037: The lock is busy. Please try again later.
- -4037: No such Gateway exists.
- -1021: This IC Card does not exist
- -1023: This Fingerprint does not exist

---

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

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`).