REST API

HTTP API abil loete oma konto seadmeid oma programmist. API näeb samu seadmeid ja sellel on samad õigused nagu teie kontol rakenduses.

Põhitõed

Üksus	Väärtus
Baas-URL	https://api.hamsystems.eu
Päringu vorming	POST koos application/x-www-form-urlencoded, kui jaotis ei ütle teisiti
Vastuse vorming	JSON
Seerianumber	<family>:<number>, näiteks e11:123. Esimene osa on seadmeperekond.

Enamikul vastustest on väli messages. See on objektide {"text": "...", "type": "error"} loend. Väärtus type on error, success või info.

Autentimine

Meetodeid on kaks:

Meetod	Kuidas selle saate	Kehtivus
API võti (api_key)	Rakenduse lehelt Konto	See ei aegu. Üks võti konto kohta.
Juurdepääsuluba (access_token)	Lõpp-punktist login.php või login_api.php	60 päeva

Saatke API võti ühel neist viisidest:

• Parameeter api_key POST-päringu kehas või päringustringis.
• Päis Authorization: Bearer-API YOUR_API_KEY.

Saatke juurdepääsuluba ühel neist viisidest:

• Parameeter access_token POST-päringu kehas või päringustringis.
• Päis Authorization: Bearer YOUR_ACCESS_TOKEN.

Kui saadate mõlemad, kasutab server API võtit.

Ettevaatust

API võti annab teie kontole täieliku juurdepääsu. Ärge pange seda koodi, mis töötab brauseris, ega avalikku hoidlasse.

API võtme loomine

1. Avage Menüü ja puudutage Konto.
2. Puudutage jaotises API võti nuppu Genereeri API võti.
3. Kinnitage teade. Uus võti tühistab vana võtme.
4. Puudutage võtit, et see kopeerida. Rakendus näitab teadet Kopeeritud.

Arvuti

Telefon

Võtme tühistamiseks looge uus võti. Vana võti lakkab kohe töötamast.

Lõpp-punktid

Võtme kontrollimine: check_api_key.php

Kontrollib API võtit.

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

Vastus: user, messages. Kui võti ei ole õige, on väljal messages viga Api key not found.

Juurdepääsuluba võtmest: login_api.php

Annab API võtme jaoks juurdepääsuloa. Kasutage seda, kui tööriist aktsepteerib ainult juurdepääsuluba.

Parameeter	Väärtus
key	API võti

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

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

Sellel lõpp-punktil on katsete piirang. Pärast paljusid ebaõnnestumisi vastab see Too many attempts, try again later.

Sisselogimine e-postiga: login.php

Parameeter	Väärtus
email	Konto e-posti aadress
password	Parool
timezone	Valikuline. Ajavöönd, näiteks Europe/Athens.

Vastus: access_token, user, messages. Kui must_recaptcha on true, küsib server reCAPTCHA kontrolli. Siis kasutage API võtit.

Seadmete loend: get_user_devices.php

Tagastab konto seadmed, grupid, korruseplaanid ja stseenid.

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

Vastuse väljad: devices, groups, floorplans, scenes, messages. Parameetritega ?v=2&definitions=1 on vastuses ka väli definitions teie seadmete perekondade jaoks.

Igal seadmel on need väljad:

Väli	Sisu
serialno	Seerianumber, näiteks e11:123
name, icon	Nimi ja ikoon rakendusest
mac	MAC-aadress
device_server	Seadme seadmeserver. Seda vajate ajaloo ja WebSocketi jaoks.
latitude, longitude	Asukoht, kui see on määratud
firmware_version	Püsivara versioon
settings	Seadme sätted
groups, floorplans	Seadme grupid ja korruseplaanid
permissions	Teie õigus seadmele (vaadake allpool)

Väärtused permissions:

Väärtus	Õigus
1	Lugemine
2	Kirjutamine (väljundite juhtimine)
3	Administraator
4	Omanik

Üks seade: get_device_info.php

Parameeter	Väärtus
serialno	Seerianumber

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

Vastus: device (samad väljad nagu loendis), messages. See aktsepteerib ka &definitions=1. Ilma serialno-ta vastab see HTTP 400-ga. Ilma seadmele juurdepääsuta vastab see HTTP 403-ga.

Praegune olek: get_device_state.php

Tagastab ühe või mitme seadme praegused näidud. Keha on 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"
  }
}

Mitme seadme jaoks saatke loend: {"serialno": ["e11:123", "e9:456"]}. Vastus on {"devices": [...], "count": 2}. Kui olek ei ole saadaval, on state väärtus {"connected": false, "message": "Device state not available"}. Ilma autentimiseta on vastus HTTP 401 koos {"error": "Authentication required"}.

Märkus

Väärtused väljal readings on töötlemata. Näites tähendab T: 2082 väärtust 20.82 °C. Perekonna definitsioon ütleb, kuidas iga väärtust teisendada. Vaadake allpool perekondade definitsioone.

Perekondade definitsioonid

Definitsioonid ütlevad, millised näidud, väljundid ja sätted igal perekonnal on. Need ei vaja autentimist.

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

Vastuses on families ja readings. Parameetriga &include_readings=false ei ole vastuses sõnastikku readings. Ilma family_id-ta on vastuses kõik perekonnad.

Igal perekonnal on:

Väli	Sisu
readings	Näitude koodid nende järjekorras, näiteks ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Väljundid nende järjekorras
settings	Perekonna sätted
ping_period	Ühenduse hoidmise intervall sekundites

Sõnastik readings annab iga näidu koodi jaoks sildi, ühiku ja teisenduse. Näiteks näidul T on ühik °C ja teisendus divide_by_100. Näitude loendit näete ka lehel Näitude sõnastik.

Väärtus 2147483648 tähendab, et näit puudub.

Ajalõpp

Määrake oma päringutele umbes 30-sekundiline ajalõpp.

Vaadake ka

• Ajalooliste andmete allalaadimine
• Reaalajas andmed (WebSocket)
• MCP tehisintellekti assistentidele
• Virtuaalsed seadmed