REST API

Su HTTP API skaitote savo paskyros įrenginius iš savo programos. API mato tuos pačius įrenginius ir turi tas pačias teises kaip Jūsų paskyra programėlėje.

Pagrindai

Elementas	Reikšmė
Bazinis URL	https://api.hamsystems.eu
Užklausos formatas	POST su application/x-www-form-urlencoded, jei skyriuje nenurodyta kitaip
Atsakymo formatas	JSON
Serijos numeris	<family>:<number>, pavyzdžiui, e11:123. Pirmoji dalis yra įrenginio šeima.

Dauguma atsakymų turi lauką messages. Tai objektų {"text": "...", "type": "error"} sąrašas. type yra error, success arba info.

Autentifikavimas

Yra du būdai:

Būdas	Kaip jį gaunate	Galiojimas
API raktas (api_key)	Programėlės puslapyje Paskyra	Jis nebaigia galioti. Vienas raktas paskyrai.
Prieigos žetonas (access_token)	Iš login.php arba login_api.php	60 dienų

API raktą siųskite vienu iš šių būdų:

• Parametras api_key POST turinyje arba užklausos eilutėje.
• Antraštė Authorization: Bearer-API YOUR_API_KEY.

Prieigos žetoną siųskite vienu iš šių būdų:

• Parametras access_token POST turinyje arba užklausos eilutėje.
• Antraštė Authorization: Bearer YOUR_ACCESS_TOKEN.

Jei siunčiate abu, serveris naudoja API raktą.

Atsargiai

API raktas suteikia visą prieigą prie Jūsų paskyros. Nedėkite jo į kodą, kuris veikia naršyklėje, arba į viešą saugyklą.

API rakto sukūrimas

1. Atidarykite Meniu ir bakstelėkite Paskyra.
2. Skyriuje API raktas bakstelėkite Sukurti API raktą.
3. Patvirtinkite pranešimą. Naujas raktas panaikina seną raktą.
4. Bakstelėkite raktą, kad jį nukopijuotumėte. Programėlė rodo Nukopijuota.

Kompiuteris

Telefonas

Kad panaikintumėte raktą, sukurkite naują raktą. Senas raktas iš karto nustoja veikti.

Galiniai taškai

Rakto tikrinimas: check_api_key.php

Patikrina API raktą.

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

Atsakymas: user, messages. Jei raktas neteisingas, messages turi klaidą Api key not found.

Prieigos žetonas iš rakto: login_api.php

Suteikia prieigos žetoną API raktui. Naudokite jį, kai įrankis priima tik prieigos žetoną.

Parametras	Reikšmė
key	API raktas

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

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

Šis galinis taškas turi bandymų ribą. Po daug nesėkmių jis atsako Too many attempts, try again later.

Prisijungimas su el. paštu: login.php

Parametras	Reikšmė
email	Paskyros el. pašto adresas
password	Slaptažodis
timezone	Neprivaloma. Laiko juosta, pavyzdžiui, Europe/Athens.

Atsakymas: access_token, user, messages. Jei must_recaptcha yra true, serveris prašo reCAPTCHA patikros. Tada naudokite API raktą.

Įrenginių sąrašas: get_user_devices.php

Grąžina paskyros įrenginius, grupes, planus ir scenarijus.

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

Atsakymo laukai: devices, groups, floorplans, scenes, messages. Su ?v=2&definitions=1 atsakymas taip pat turi lauką definitions Jūsų įrenginių šeimoms.

Kiekvienas įrenginys turi šiuos laukus:

Laukas	Turinys
serialno	Serijos numeris, pavyzdžiui, e11:123
name, icon	Pavadinimas ir piktograma iš programėlės
mac	MAC adresas
device_server	Įrenginio serveris. Jo reikia istorijai ir WebSocket.
latitude, longitude	Vieta, jei ji nustatyta
firmware_version	Programinės įrangos versija
settings	Įrenginio nustatymai
groups, floorplans	Įrenginio grupės ir planai
permissions	Jūsų teisė įrenginiui (žr. toliau)

permissions reikšmės:

Reikšmė	Teisė
1	Skaityti
2	Rašyti (valdyti išvestis)
3	Administratorius
4	Savininkas

Vienas įrenginys: get_device_info.php

Parametras	Reikšmė
serialno	Serijos numeris

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

Atsakymas: device (tie patys laukai kaip sąraše), messages. Jis taip pat priima &definitions=1. Be serialno jis atsako HTTP 400. Be prieigos prie įrenginio jis atsako HTTP 403.

Dabartinė būsena: get_device_state.php

Grąžina vieno arba daugiau įrenginių dabartinius rodmenis. Turinys yra 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"
  }
}

Daugiau įrenginių atveju siųskite sąrašą: {"serialno": ["e11:123", "e9:456"]}. Atsakymas yra {"devices": [...], "count": 2}. Jei būsena nepasiekiama, state yra {"connected": false, "message": "Device state not available"}. Be autentifikavimo atsakymas yra HTTP 401 su {"error": "Authentication required"}.

Pastaba

readings reikšmės yra neapdorotos. Pavyzdyje T: 2082 reiškia 20.82 °C. Šeimos apibrėžtis nurodo, kaip konvertuoti kiekvieną reikšmę. Žr. šeimų apibrėžtis toliau.

Šeimų apibrėžtys

Apibrėžtys nurodo, kokius rodmenis, išvestis ir nustatymus turi kiekviena šeima. Joms autentifikavimo nereikia.

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

Atsakymas turi families ir readings. Su &include_readings=false atsakymas neturi žodyno readings. Be family_id atsakymas turi visas šeimas.

Kiekviena šeima turi:

Laukas	Turinys
readings	Rodmenų kodai jų tvarka, pavyzdžiui, ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Išvestys jų tvarka
settings	Šeimos nustatymai
ping_period	Ryšio palaikymo intervalas sekundėmis

Žodynas readings nurodo kiekvieno rodmens kodo žymą, vienetą ir konvertavimą. Pavyzdžiui, rodmuo T turi vienetą °C ir konvertavimą divide_by_100. Rodmenų sąrašą taip pat galite matyti puslapyje Rodmenys.

Reikšmė 2147483648 reiškia, kad rodmens nėra.

Laukimo laikas

Savo užklausoms nustatykite maždaug 30 sekundžių laukimo laiką.

Taip pat žr.

• Istorinių duomenų atsisiuntimas
• Tiesioginiai duomenys (WebSocket)
• MCP AI asistentams
• Virtualūs įrenginiai