REST API

A HTTP API-val a saját programjából olvassa a fiókja eszközeit. Az API ugyanazokat az eszközöket látja, és ugyanazokkal a jogosultságokkal rendelkezik, mint a fiókja az alkalmazásban.

Alapok

Elem	Érték
Alap URL	`https://api.hamsystems.eu`
Kérés formátuma	`POST` ezzel: `application/x-www-form-urlencoded`, hacsak a rész mást nem mond
Válasz formátuma	JSON
Sorozatszám	`<family>:<number>`, például `e11:123`. Az első rész az eszközcsalád.

A legtöbb válaszban van egy messages mező. Ez {"text": "...", "type": "error"} objektumok listája. A type értéke error, success vagy info.

Hitelesítés

Két módszer van:

Módszer	Honnan kapja	Érvényesség
API kulcs (`api_key`)	Az alkalmazás Fiók oldaláról	Nem jár le. Fiókonként egy kulcs.
Hozzáférési token (`access_token`)	A `login.php` vagy a `login_api.php` végponttól	60 nap

Az API kulcsot ezek egyikével küldje:

api_key paraméter a POST törzsben vagy a lekérdezési karakterláncban.
Authorization: Bearer-API YOUR_API_KEY fejléc.

A hozzáférési tokent ezek egyikével küldje:

access_token paraméter a POST törzsben vagy a lekérdezési karakterláncban.
Authorization: Bearer YOUR_ACCESS_TOKEN fejléc.

Ha mindkettőt küldi, a szerver az API kulcsot használja.

API kulcs létrehozása

Nyissa meg a Menü elemet, és koppintson a Fiók elemre.
Az API kulcs részben koppintson az API kulcs létrehozása gombra.
Erősítse meg az üzenetet. Az új kulcs érvényteleníti a régi kulcsot.
Koppintson a kulcsra a másoláshoz. Az alkalmazás ezt mutatja: Másolva.

Az API kulcs rész a Fiók oldalon, rejtett kulccsal — Számítógép

Egy kulcs érvénytelenítéséhez hozzon létre új kulcsot. A régi kulcs azonnal leáll.

Végpontok

Kulcs ellenőrzése: `check_api_key.php`

Ellenőriz egy API kulcsot.

curl -X POST https://api.hamsystems.eu/check_api_key.php \
  -d api_key=YOUR_API_KEY

Válasz: user, messages. Ha a kulcs nem helyes, a messages ezt a hibát tartalmazza: Api key not found.

Hozzáférési token kulcsból: `login_api.php`

Hozzáférési tokent ad az API kulcshoz. Akkor használja, ha egy eszköz csak hozzáférési tokent fogad el.

Paraméter	Érték
`key`	Az API kulcs

curl -X POST https://api.hamsystems.eu/login_api.php \
  -d key=YOUR_API_KEY

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "user": { "id": 1234 },
  "messages": []
}

Ennek a végpontnak próbálkozási korlátja van. Sok sikertelen próbálkozás után ezt válaszolja: Too many attempts, try again later.

Bejelentkezés e-mail címmel: `login.php`

Paraméter	Érték
`email`	A fiók e-mail címe
`password`	A jelszó
`timezone`	Nem kötelező. Az időzóna, például `Europe/Athens`.

Válasz: access_token, user, messages. Ha a must_recaptcha értéke true, a szerver reCAPTCHA ellenőrzést kér. Ilyenkor használjon API kulcsot.

Eszközlista: `get_user_devices.php`

Visszaadja a fiók eszközeit, csoportjait, alaprajzait és jeleneteit.

curl -X POST "https://api.hamsystems.eu/get_user_devices.php?v=2" \
  -H "Authorization: Bearer-API YOUR_API_KEY"

A válasz mezői: devices, groups, floorplans, scenes, messages. A ?v=2&definitions=1 paraméterrel a válaszban egy definitions mező is van az eszközei családjaihoz.

Minden eszköznek ezek a mezői vannak:

Mező	Tartalom
`serialno`	A sorozatszám, például `e11:123`
`name`, `icon`	A név és az ikon az alkalmazásból
`mac`	A MAC-cím
`device_server`	Az eszköz eszközszervere. Az előzményekhez és a WebSockethez kell.
`latitude`, `longitude`	A hely, ha be van állítva
`firmware_version`	A firmware verziója
`settings`	Az eszköz beállításai
`groups`, `floorplans`	Az eszköz csoportjai és alaprajzai
`permissions`	Az Ön jogosultsága az eszközön (lásd lent)

A permissions értékei:

Érték	Jogosultság
`1`	Olvasás
`2`	Írás (kimenetek vezérlése)
`3`	Rendszergazda
`4`	Tulajdonos

Egy eszköz: `get_device_info.php`

Paraméter	Érték
`serialno`	A sorozatszám

curl -X POST "https://api.hamsystems.eu/get_device_info.php?v=2" \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -d serialno=e11:123

Válasz: device (ugyanazok a mezők, mint a listában), messages. Elfogadja a &definitions=1 paramétert is. A serialno nélkül HTTP 400 választ ad. Az eszközhöz való hozzáférés nélkül HTTP 403 választ ad.

Aktuális állapot: `get_device_state.php`

Visszaadja egy vagy több eszköz aktuális méréseit. A törzs JSON.

curl -X POST https://api.hamsystems.eu/get_device_state.php \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serialno": "e11:123"}'

{
  "serialno": "e11:123",
  "name": "Fridge 1",
  "state": {
    "connected": true,
    "timestamp": 1791936198,
    "readings": { "T": 2082, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
    "rssi": -55,
    "device_name": "Fridge 1"
  }
}

Több eszközhöz küldjön listát: {"serialno": ["e11:123", "e9:456"]}. A válasz: {"devices": [...], "count": 2}. Ha az állapot nem érhető el, a state értéke {"connected": false, "message": "Device state not available"}. Hitelesítés nélkül a válasz HTTP 401 ezzel: {"error": "Authentication required"}.

Családdefiníciók

A definíciók megmondják, milyen mérései, kimenetei és beállításai vannak az egyes családoknak. Nem kell hozzájuk hitelesítés.

curl "https://api.hamsystems.eu/get_device_definitions.php?family_id=e11"

A válaszban families és readings van. A &include_readings=false paraméterrel a válaszban nincs readings szótár. A family_id nélkül a válasz minden családot tartalmaz.

Minden családnak ezek vannak:

Mező	Tartalom
`readings`	A mérési kódok a sorrendjükben, például `["T", "GI", "GIC", "GI2", "GI2C"]`
`output_names`	A kimenetek a sorrendjükben
`settings`	A család beállításai
`ping_period`	A kapcsolatfenntartási időköz másodpercben

A readings szótár megadja minden mérési kód címkéjét, mértékegységét és átváltását. Például a T mérés mértékegysége °C, az átváltása divide_by_100. A mérések listáját a Mérési szótár oldalon is megtekintheti.

A 2147483648 érték azt jelenti, hogy a mérés hiányzik.

Időtúllépés

Állítson be kb. 30 másodperces időtúllépést a kéréseihez.

Lásd még

Csevegés az ügyfélszolgálattal