REST API

Pomocou HTTP API čítate zariadenia vášho účtu z vlastného programu. API vidí tie isté zariadenia a má tie isté oprávnenia ako váš účet v aplikácii.

Základy

Položka	Hodnota
Základná URL	https://api.hamsystems.eu
Formát požiadavky	POST s application/x-www-form-urlencoded, ak časť neuvádza inak
Formát odpovede	JSON
Sériové číslo	<family>:<number>, napríklad e11:123. Prvá časť je rodina zariadenia.

Väčšina odpovedí má pole messages. Je to zoznam objektov {"text": "...", "type": "error"}. Hodnota type je error, success alebo info.

Overenie

Sú dve metódy:

Metóda	Ako ju získate	Platnosť
API kľúč (api_key)	Zo stránky Účet v aplikácii	Nevyprší. Jeden kľúč na účet.
Prístupový token (access_token)	Z login.php alebo login_api.php	60 dní

API kľúč pošlite jedným z týchto spôsobov:

• Parameter api_key v tele POST alebo v query stringu.
• Hlavička Authorization: Bearer-API YOUR_API_KEY.

Prístupový token pošlite jedným z týchto spôsobov:

• Parameter access_token v tele POST alebo v query stringu.
• Hlavička Authorization: Bearer YOUR_ACCESS_TOKEN.

Ak pošlete oboje, server použije API kľúč.

Upozornenie

API kľúč dáva úplný prístup k vášmu účtu. Nedávajte ho do kódu, ktorý beží v prehliadači, ani do verejného repozitára.

Vytvorenie API kľúča

1. Otvorte Ponuka a ťuknite na Účet.
2. V časti API kľúč ťuknite na Generovať API kľúč.
3. Potvrďte správu. Nový kľúč zruší starý kľúč.
4. Ťuknite na kľúč. Aplikácia ho skopíruje a ukáže Skopírované.

Počítač

Telefón

Ak chcete kľúč zrušiť, vytvorte nový kľúč. Starý kľúč hneď prestane fungovať.

Endpointy

Kontrola kľúča: check_api_key.php

Skontroluje API kľúč.

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

Odpoveď: user, messages. Ak kľúč nie je správny, messages má chybu Api key not found.

Prístupový token z kľúča: login_api.php

Dá prístupový token pre API kľúč. Použite ho, keď nástroj prijíma iba prístupový token.

Parameter	Hodnota
key	API kľúč

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

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

Tento endpoint má limit pokusov. Po mnohých neúspechoch odpovie Too many attempts, try again later.

Prihlásenie e-mailom: login.php

Parameter	Hodnota
email	E-mail účtu
password	Heslo
timezone	Voliteľné. Časové pásmo, napríklad Europe/Athens.

Odpoveď: access_token, user, messages. Ak je must_recaptcha true, server požaduje kontrolu reCAPTCHA. Vtedy použite API kľúč.

Zoznam zariadení: get_user_devices.php

Vráti zariadenia, skupiny, pôdorysy a scény účtu.

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

Polia odpovede: devices, groups, floorplans, scenes, messages. S ?v=2&definitions=1 má odpoveď aj pole definitions pre rodiny vašich zariadení.

Každé zariadenie má tieto polia:

Pole	Obsah
serialno	Sériové číslo, napríklad e11:123
name, icon	Názov a ikona z aplikácie
mac	Adresa MAC
device_server	Server zariadenia. Potrebujete ho pre históriu a pre WebSocket.
latitude, longitude	Poloha, ak je nastavená
firmware_version	Verzia firmvéru
settings	Nastavenia zariadenia
groups, floorplans	Skupiny a pôdorysy zariadenia
permissions	Vaše oprávnenie k zariadeniu (pozrite nižšie)

Hodnoty permissions:

Hodnota	Oprávnenie
1	Čítanie
2	Zápis (ovládanie výstupov)
3	Administrátor
4	Vlastník

Jedno zariadenie: get_device_info.php

Parameter	Hodnota
serialno	Sériové číslo

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

Odpoveď: device (tie isté polia ako v zozname), messages. Prijíma aj &definitions=1. Bez serialno odpovie HTTP 400. Bez prístupu k zariadeniu odpovie HTTP 403.

Aktuálny stav: get_device_state.php

Vráti aktuálne merania jedného alebo viacerých zariadení. 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"
  }
}

Pre viac zariadení pošlite zoznam: {"serialno": ["e11:123", "e9:456"]}. Odpoveď je {"devices": [...], "count": 2}. Ak stav nie je dostupný, state je {"connected": false, "message": "Device state not available"}. Bez overenia je odpoveď HTTP 401 s {"error": "Authentication required"}.

Poznámka

Hodnoty v readings sú surové. V príklade T: 2082 znamená 20,82 °C. Definícia rodiny hovorí, ako previesť každú hodnotu. Pozrite definície rodín nižšie.

Definície rodín

Definície hovoria, ktoré merania, výstupy a nastavenia má každá rodina. Nepotrebujú overenie.

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

Odpoveď má families a readings. S &include_readings=false odpoveď nemá slovník readings. Bez family_id odpoveď obsahuje všetky rodiny.

Každá rodina má:

Pole	Obsah
readings	Kódy meraní v ich poradí, napríklad ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Výstupy v ich poradí
settings	Nastavenia rodiny
ping_period	Interval keep-alive v sekundách

Slovník readings dáva pre každý kód merania popis, jednotku a prevod. Napríklad meranie T má jednotku °C a prevod divide_by_100. Zoznam meraní vidíte aj na stránke Slovník meraní.

Hodnota 2147483648 znamená, že meranie chýba.

Časový limit

Pre svoje požiadavky nastavte časový limit približne 30 sekúnd.

Pozrite aj

• Stiahnutie historických údajov
• Živé údaje (WebSocket)
• MCP pre AI asistentov
• Virtuálne zariadenia