REST API

Ar HTTP API jūs lasāt sava konta ierīces no savas programmas. API redz tās pašas ierīces un tam ir tās pašas atļaujas kā jūsu kontam lietotnē.

Pamati

Elements	Vērtība
Bāzes URL	https://api.hamsystems.eu
Pieprasījuma formāts	POST ar application/x-www-form-urlencoded, ja vien sadaļa nenorāda citādi
Atbildes formāts	JSON
Sērijas numurs	<family>:<number>, piemēram, e11:123. Pirmā daļa ir ierīču saime.

Lielākajai daļai atbilžu ir lauks messages. Tas ir objektu saraksts {"text": "...", "type": "error"}. type ir error, success vai info.

Autentifikācija

Ir divas metodes:

Metode	Kā jūs to iegūstat	Derīguma laiks
API atslēga (api_key)	No lietotnes lapas Konts	Tās derīgums nebeidzas. Viena atslēga kontam.
Piekļuves marķieris (access_token)	No login.php vai login_api.php	60 dienas

Sūtiet API atslēgu vienā no šiem veidiem:

• Parametrs api_key POST pamattekstā vai vaicājuma virknē.
• Galvene Authorization: Bearer-API YOUR_API_KEY.

Sūtiet piekļuves marķieri vienā no šiem veidiem:

• Parametrs access_token POST pamattekstā vai vaicājuma virknē.
• Galvene Authorization: Bearer YOUR_ACCESS_TOKEN.

Ja jūs sūtāt abus, serveris izmanto API atslēgu.

Uzmanību

API atslēga dod pilnu piekļuvi jūsu kontam. Nelieciet to kodā, kas darbojas pārlūkā, vai publiskā repozitorijā.

Izveidojiet API atslēgu

1. Atveriet Izvēlne un pieskarieties Konts.
2. Sadaļā API atslēga pieskarieties Ģenerēt API atslēgu.
3. Apstipriniet ziņojumu. Jauna atslēga atceļ veco atslēgu.
4. Pieskarieties atslēgai, lai to nokopētu. Lietotne rāda Nokopēts.

Dators

Tālrunis

Lai atceltu atslēgu, izveidojiet jaunu atslēgu. Vecā atslēga uzreiz pārstāj darboties.

Galapunkti

Pārbaudīt atslēgu: check_api_key.php

Pārbauda API atslēgu.

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

Atbilde: user, messages. Ja atslēga nav pareiza, messages satur kļūdu Api key not found.

Piekļuves marķieris no atslēgas: login_api.php

Dod piekļuves marķieri API atslēgai. Izmantojiet to, kad rīks pieņem tikai piekļuves marķieri.

Parametrs	Vērtība
key	API atslēga

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

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

Šim galapunktam ir mēģinājumu limits. Pēc daudzām kļūmēm tas atbild Too many attempts, try again later.

Pieteikties ar e-pastu: login.php

Parametrs	Vērtība
email	Konta e-pasts
password	Parole
timezone	Neobligāts. Laika josla, piemēram, Europe/Athens.

Atbilde: access_token, user, messages. Ja must_recaptcha ir true, serveris prasa reCAPTCHA pārbaudi. Tad izmantojiet API atslēgu.

Ierīču saraksts: get_user_devices.php

Atgriež konta ierīces, grupas, stāvu plānus un ainas.

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

Atbildes lauki: devices, groups, floorplans, scenes, messages. Ar ?v=2&definitions=1 atbildē ir arī lauks definitions jūsu ierīču saimēm.

Katrai ierīcei ir šie lauki:

Lauks	Saturs
serialno	Sērijas numurs, piemēram, e11:123
name, icon	Nosaukums un ikona no lietotnes
mac	MAC adrese
device_server	Ierīces serveris. Tas jums vajadzīgs vēsturei un WebSocket.
latitude, longitude	Atrašanās vieta, ja tā ir iestatīta
firmware_version	Programmaparatūras versija
settings	Ierīces iestatījumi
groups, floorplans	Ierīces grupas un stāvu plāni
permissions	Jūsu atļauja ierīcei (skatiet tālāk)

permissions vērtības:

Vērtība	Atļauja
1	Lasīt
2	Rakstīt (vadīt izejas)
3	Administrators
4	Īpašnieks

Viena ierīce: get_device_info.php

Parametrs	Vērtība
serialno	Sērijas numurs

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

Atbilde: device (tie paši lauki kā sarakstā), messages. Tas pieņem arī &definitions=1. Bez serialno tas atbild ar HTTP 400. Bez piekļuves ierīcei tas atbild ar HTTP 403.

Pašreizējais stāvoklis: get_device_state.php

Atgriež vienas vai vairāku ierīču pašreizējos mērījumus. Pamatteksts ir 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"
  }
}

Vairākām ierīcēm sūtiet sarakstu: {"serialno": ["e11:123", "e9:456"]}. Atbilde ir {"devices": [...], "count": 2}. Ja stāvoklis nav pieejams, state ir {"connected": false, "message": "Device state not available"}. Bez autentifikācijas atbilde ir HTTP 401 ar {"error": "Authentication required"}.

Piezīme

Vērtības laukā readings ir neapstrādātas. Piemērā T: 2082 nozīmē 20.82 °C. Saimes definīcija norāda, kā pārvērst katru vērtību. Skatiet saimju definīcijas tālāk.

Saimju definīcijas

Definīcijas norāda, kādi mērījumi, izejas un iestatījumi ir katrai saimei. Tām nav vajadzīga autentifikācija.

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

Atbildē ir families un readings. Ar &include_readings=false atbildē nav vārdnīcas readings. Bez family_id atbildē ir visas saimes.

Katrai saimei ir:

Lauks	Saturs
readings	Mērījumu kodi to secībā, piemēram, ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Izejas to secībā
settings	Saimes iestatījumi
ping_period	Uzturēšanas signāla intervāls sekundēs

Vārdnīca readings dod katra mērījuma koda nosaukumu, mērvienību un pārveidošanu. Piemēram, mērījumam T ir mērvienība °C un pārveidošana divide_by_100. Mērījumu sarakstu varat redzēt arī lapā Mērījumu vārdnīca.

Vērtība 2147483648 nozīmē, ka mērījuma nav.

Noildze

Saviem pieprasījumiem iestatiet noildzi apmēram 30 sekundes.

Skatiet arī

• Vēsturisko datu lejupielāde
• Tiešsaistes dati (WebSocket)
• MCP AI asistentiem
• Virtuālās ierīces