REST API

HTTP API-jem čitate uređaje svog računa iz vlastitog programa. API vidi iste uređaje i ima ista dopuštenja kao vaš račun u aplikaciji.

Osnove

Stavka	Vrijednost
Osnovni URL	https://api.hamsystems.eu
Format zahtjeva	POST s application/x-www-form-urlencoded, osim ako odjeljak navodi drugačije
Format odgovora	JSON
Serijski broj	<family>:<number>, na primjer e11:123. Prvi dio je obitelj uređaja.

Većina odgovora ima polje messages. To je popis objekata {"text": "...", "type": "error"}. type je error, success ili info.

Autentikacija

Postoje dvije metode:

Metoda	Kako je dobivate	Trajanje
API ključ (api_key)	Sa stranice Račun u aplikaciji	Ne istječe. Jedan ključ po računu.
Pristupni token (access_token)	Iz login.php ili login_api.php	60 dana

API ključ šaljite na jedan od ovih načina:

• Parametar api_key u POST tijelu ili u query stringu.
• Zaglavlje Authorization: Bearer-API YOUR_API_KEY.

Pristupni token šaljite na jedan od ovih načina:

• Parametar access_token u POST tijelu ili u query stringu.
• Zaglavlje Authorization: Bearer YOUR_ACCESS_TOKEN.

Ako pošaljete oba, poslužitelj koristi API ključ.

Προσοχή

API ključ daje potpuni pristup vašem računu. Ne stavljajte ga u kôd koji se izvršava u pregledniku ni u javni repozitorij.

Izrada API ključa

1. Otvorite Izbornik i dodirnite Račun.
2. U odjeljku API ključ dodirnite Generiraj API ključ.
3. Potvrdite poruku. Novi ključ poništava stari ključ.
4. Dodirnite ključ za kopiranje. Aplikacija prikazuje Kopirano.

Računalo

Telefon

Za poništavanje ključa izradite novi ključ. Stari ključ odmah prestaje raditi.

Endpointi

Provjera ključa: check_api_key.php

Provjerava API ključ.

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

Odgovor: user, messages. Ako ključ nije ispravan, messages sadrži grešku Api key not found.

Pristupni token iz ključa: login_api.php

Daje pristupni token za API ključ. Koristite ga kada alat prihvaća samo pristupni token.

Parametar	Vrijednost
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": []
}

Ovaj endpoint ima ograničenje broja pokušaja. Nakon mnogo neuspjeha odgovara Too many attempts, try again later.

Prijava e-poštom: login.php

Parametar	Vrijednost
email	E-pošta računa
password	Lozinka
timezone	Neobavezno. Vremenska zona, na primjer Europe/Athens.

Odgovor: access_token, user, messages. Ako je must_recaptcha true, poslužitelj traži reCAPTCHA provjeru. Tada koristite API ključ.

Popis uređaja: get_user_devices.php

Vraća uređaje, grupe, tlocrte i 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. S ?v=2&definitions=1 odgovor ima i polje definitions za obitelji vaših uređaja.

Svaki uređaj ima ova polja:

Polje	Sadržaj
serialno	Serijski broj, na primjer e11:123
name, icon	Naziv i ikona iz aplikacije
mac	MAC adresa
device_server	Poslužitelj uređaja. Treba vam za povijest i za WebSocket.
latitude, longitude	Lokacija, ako je postavljena
firmware_version	Verzija firmwarea
settings	Postavke uređaja
groups, floorplans	Grupe i tlocrti uređaja
permissions	Vaše dopuštenje na uređaju (pogledajte u nastavku)

Vrijednosti permissions:

Vrijednost	Dopuštenje
1	Čitanje
2	Pisanje (upravljanje izlazima)
3	Administrator
4	Vlasnik

Jedan uređaj: get_device_info.php

Parametar	Vrijednost
serialno	Serijski broj

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 kao na popisu), messages. Prihvaća i &definitions=1. Bez serialno odgovara s HTTP 400. Bez pristupa uređaju odgovara s HTTP 403.

Trenutačno stanje: get_device_state.php

Vraća trenutačna mjerenja jednog ili više uređaja. Tijelo 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 više uređaja pošaljite popis: {"serialno": ["e11:123", "e9:456"]}. Odgovor je {"devices": [...], "count": 2}. Ako stanje nije dostupno, state je {"connected": false, "message": "Device state not available"}. Bez autentikacije odgovor je HTTP 401 s {"error": "Authentication required"}.

Σημείωση

Vrijednosti u readings su sirove. U primjeru T: 2082 znači 20.82 °C. Definicija obitelji govori kako pretvoriti svaku vrijednost. Pogledajte definicije obitelji u nastavku.

Definicije obitelji

Definicije govore koja mjerenja, izlaze i postavke ima svaka obitelj. Ne trebaju autentikaciju.

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

Odgovor ima families i readings. S &include_readings=false odgovor nema rječnik readings. Bez family_id odgovor ima sve obitelji.

Svaka obitelj ima:

Polje	Sadržaj
readings	Kodovi mjerenja svojim redoslijedom, na primjer ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Izlazi svojim redoslijedom
settings	Postavke obitelji
ping_period	Interval održavanja veze u sekundama

Rječnik readings daje oznaku, jedinicu i pretvorbu za svaki kod mjerenja. Na primjer, mjerenje T ima jedinicu °C i pretvorbu divide_by_100. Popis mjerenja možete vidjeti i na stranici Mjerenja.

Vrijednost 2147483648 znači da mjerenje nedostaje.

Vremensko ograničenje

Postavite vremensko ograničenje od oko 30 sekundi na svoje zahtjeve.

Pogledajte i

• Preuzimanje povijesnih podataka
• Podaci uživo (WebSocket)
• MCP za AI asistente
• Virtualni uređaji