REST API

S HTTP API berete naprave svojega računa iz lastnega programa. API vidi iste naprave in ima ista dovoljenja kot vaš račun v aplikaciji.

Osnove

Element	Vrednost
Osnovni URL	https://api.hamsystems.eu
Oblika zahteve	POST z application/x-www-form-urlencoded, razen če razdelek navaja drugače
Oblika odgovora	JSON
Serijska številka	<family>:<number>, na primer e11:123. Prvi del je družina naprave.

Večina odgovorov ima polje messages. To je seznam objektov {"text": "...", "type": "error"}. type je error, success ali info.

Overitev

Obstajata dve metodi:

Metoda	Kako jo pridobite	Veljavnost
API ključ (api_key)	Na strani Račun v aplikaciji	Ne poteče. En ključ na račun.
Dostopni žeton (access_token)	Iz login.php ali login_api.php	60 dni

API ključ pošljite na enega od teh načinov:

• Parameter api_key v telesu POST ali v poizvedbenem nizu.
• Glava Authorization: Bearer-API YOUR_API_KEY.

Dostopni žeton pošljite na enega od teh načinov:

• Parameter access_token v telesu POST ali v poizvedbenem nizu.
• Glava Authorization: Bearer YOUR_ACCESS_TOKEN.

Če pošljete oba, strežnik uporabi API ključ.

Προσοχή

API ključ daje poln dostop do vašega računa. Ne vstavljajte ga v kodo, ki se izvaja v brskalniku, ali v javno skladišče.

Ustvarjanje API ključa

1. Odprite Meni in tapnite Račun.
2. V razdelku API ključ tapnite Ustvari API ključ.
3. Potrdite sporočilo. Nov ključ prekliče stari ključ.
4. Tapnite ključ, da ga kopirate. Aplikacija prikaže Kopirano.

Računalnik

Telefon

Za preklic ključa ustvarite nov ključ. Stari ključ takoj preneha delovati.

Končne točke

Preverjanje ključa: check_api_key.php

Preveri API ključ.

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

Odgovor: user, messages. Če ključ ni pravilen, messages vsebuje napako Api key not found.

Dostopni žeton iz ključa: login_api.php

Vrne dostopni žeton za API ključ. Uporabite ga, ko orodje sprejme samo dostopni žeton.

Parameter	Vrednost
key	API ključ

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

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

Ta končna točka ima omejitev poskusov. Po mnogih neuspehih odgovori Too many attempts, try again later.

Prijava z e-pošto: login.php

Parameter	Vrednost
email	E-pošta računa
password	Geslo
timezone	Neobvezno. Časovni pas, na primer Europe/Athens.

Odgovor: access_token, user, messages. Če je must_recaptcha enak true, strežnik zahteva preverjanje reCAPTCHA. Tedaj uporabite API ključ.

Seznam naprav: get_user_devices.php

Vrne naprave, skupine, tlorise in scene računa.

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

Polja odgovora: devices, groups, floorplans, scenes, messages. Z ?v=2&definitions=1 ima odgovor tudi polje definitions za družine vaših naprav.

Vsaka naprava ima ta polja:

Polje	Vsebina
serialno	Serijska številka, na primer e11:123
name, icon	Ime in ikona iz aplikacije
mac	Naslov MAC
device_server	Strežnik naprave. Potrebujete ga za zgodovino in za WebSocket.
latitude, longitude	Lokacija, če je nastavljena
firmware_version	Različica vdelane programske opreme
settings	Nastavitve naprave
groups, floorplans	Skupine in tlorisi naprave
permissions	Vaše dovoljenje za napravo (glejte spodaj)

Vrednosti permissions:

Vrednost	Dovoljenje
1	Branje
2	Pisanje (upravljanje izhodov)
3	Skrbnik
4	Lastnik

Ena naprava: get_device_info.php

Parameter	Vrednost
serialno	Serijska številka

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

Odgovor: device (ista polja kot v seznamu), messages. Sprejme tudi &definitions=1. Brez serialno odgovori s HTTP 400. Brez dostopa do naprave odgovori s HTTP 403.

Trenutno stanje: get_device_state.php

Vrne trenutne odčitke ene ali več naprav. Telo je 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"
  }
}

Za več naprav pošljite seznam: {"serialno": ["e11:123", "e9:456"]}. Odgovor je {"devices": [...], "count": 2}. Če stanje ni na voljo, je state enak {"connected": false, "message": "Device state not available"}. Brez overitve je odgovor HTTP 401 z {"error": "Authentication required"}.

Σημείωση

Vrednosti v readings so neobdelane. V primeru T: 2082 pomeni 20.82 °C. Definicija družine pove, kako pretvorite vsako vrednost. Glejte definicije družin spodaj.

Definicije družin

Definicije povedo, katere odčitke, izhode in nastavitve ima vsaka družina. Ne potrebujejo overitve.

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

Odgovor ima families in readings. Z &include_readings=false odgovor nima slovarja readings. Brez family_id odgovor vsebuje vse družine.

Vsaka družina ima:

Polje	Vsebina
readings	Kode odčitkov v njihovem vrstnem redu, na primer ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Izhodi v njihovem vrstnem redu
settings	Nastavitve družine
ping_period	Interval ohranjanja povezave v sekundah

Slovar readings za vsako kodo odčitka navaja oznako, enoto in pretvorbo. Na primer, odčitek T ima enoto °C in pretvorbo divide_by_100. Seznam odčitkov vidite tudi na strani Slovar odčitkov.

Vrednost 2147483648 pomeni, da odčitek manjka.

Časovna omejitev

Za svoje zahteve nastavite časovno omejitev približno 30 sekund.

Glejte tudi

• Prenos zgodovinskih podatkov
• Podatki v živo (WebSocket)
• MCP za pomočnike z umetno inteligenco
• Virtualne naprave