REST API

Přes HTTP API čtete zařízení svého účtu z vlastního programu. API vidí stejná zařízení a má stejná oprávnění jako váš účet v aplikaci.

Základní údaje

Položka	Hodnota
Základní URL	https://api.hamsystems.eu
Formát požadavku	POST s application/x-www-form-urlencoded, pokud sekce neuvádí jinak
Formát odpovědi	JSON
Sériové číslo	<rodina>:<číslo>, například e11:123. První část je rodina zařízení.

Většina odpovědí má pole messages. Je to seznam objektů {"text": "...", "type": "error"}. Hodnota type je error, success nebo info.

Ověření

Existují dvě metody:

Metoda	Jak ji získáte	Platnost
API klíč (api_key)	Ze stránky Účet v aplikaci	Nevyprší. Jeden klíč na účet.
Přístupový token (access_token)	Z login.php nebo login_api.php	60 dní

API klíč pošlete jedním z těchto způsobů:

• Parametr api_key v těle POST nebo v query stringu.
• Hlavička Authorization: Bearer-API YOUR_API_KEY.

Přístupový token pošlete jedním z těchto způsobů:

• Parametr access_token v těle POST nebo v query stringu.
• Hlavička Authorization: Bearer YOUR_ACCESS_TOKEN.

Pokud pošlete obojí, server použije API klíč.

Upozornění

API klíč dává plný přístup k vašemu účtu. Nevkládejte ho do kódu, který běží v prohlížeči, ani do veřejného repozitáře.

Vytvoření API klíče

1. Otevřete Nabídka a klepněte na Účet.
2. V sekci API klíč klepněte na Vygenerovat API klíč.
3. Potvrďte zprávu. Nový klíč zruší starý klíč.
4. Klepnutím na klíč ho zkopírujete. Aplikace ukáže Zkopírováno.

Počítač

Telefon

Chcete-li klíč zrušit, vytvořte nový klíč. Starý klíč okamžitě přestane fungovat.

Koncové body

Kontrola klíče: check_api_key.php

Zkontroluje API klíč.

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

Odpověď: user, messages. Pokud klíč není správný, messages obsahuje chybu Api key not found.

Přístupový token z klíče: login_api.php

Vydá přístupový token pro API klíč. Použijte ho, když nástroj přijímá jen přístupový token.

Parametr	Hodnota
key	API klíč

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 koncový bod má limit pokusů. Po mnoha neúspěšných pokusech odpoví Too many attempts, try again later.

Přihlášení e-mailem: login.php

Parametr	Hodnota
email	E-mail účtu
password	Heslo
timezone	Volitelné. Časové pásmo, například Europe/Athens.

Odpověď: access_token, user, messages. Pokud je must_recaptcha rovno true, server vyžaduje kontrolu reCAPTCHA. Pak použijte API klíč.

Seznam zařízení: get_user_devices.php

Vrátí zařízení, 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"

Pole odpovědi: devices, groups, floorplans, scenes, messages. S parametrem ?v=2&definitions=1 odpověď obsahuje také pole definitions pro rodiny vašich zařízení.

Každé zařízení má tato pole:

Pole	Obsah
serialno	Sériové číslo, například e11:123
name, icon	Název a ikona z aplikace
mac	Adresa MAC
device_server	Server zařízení. Potřebujete ho pro historii a pro WebSocket.
latitude, longitude	Poloha, pokud je nastavena
firmware_version	Verze firmwaru
settings	Nastavení zařízení
groups, floorplans	Skupiny a půdorysy zařízení
permissions	Vaše oprávnění k zařízení (viz níže)

Hodnoty permissions:

Hodnota	Oprávnění
1	Čtení
2	Zápis (ovládání výstupů)
3	Správce
4	Vlastník

Jedno zařízení: get_device_info.php

Parametr	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

Odpověď: device (stejná pole jako v seznamu), messages. Přijímá také &definitions=1. Bez serialno odpoví HTTP 400. Bez přístupu k zařízení odpoví HTTP 403.

Aktuální stav: get_device_state.php

Vrátí aktuální měření jednoho nebo více zařízení. Tělo 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"
  }
}

Pro více zařízení pošlete seznam: {"serialno": ["e11:123", "e9:456"]}. Odpověď je {"devices": [...], "count": 2}. Pokud stav není k dispozici, state je {"connected": false, "message": "Device state not available"}. Bez ověření je odpověď HTTP 401 s {"error": "Authentication required"}.

Poznámka

Hodnoty v readings jsou surové. V příkladu T: 2082 znamená 20.82 °C. Definice rodiny říká, jak každou hodnotu převést. Viz definice rodin níže.

Definice rodin

Definice říkají, jaká měření, výstupy a nastavení každá rodina má. Nevyžadují ověření.

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

Odpověď obsahuje families a readings. S parametrem &include_readings=false odpověď neobsahuje slovník readings. Bez family_id odpověď obsahuje všechny rodiny.

Každá rodina má:

Pole	Obsah
readings	Kódy měření v pořadí, například ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Výstupy v pořadí
settings	Nastavení rodiny
ping_period	Interval udržení spojení v sekundách

Slovník readings udává pro každý kód měření název, jednotku a převod. Například měření T má jednotku °C a převod divide_by_100. Seznam měření vidíte také na stránce Měření.

Hodnota 2147483648 znamená, že měření chybí.

Časový limit

Nastavte u požadavků časový limit asi 30 sekund.

Viz také

• Stažení historických dat
• Živá data (WebSocket)
• MCP pro asistenty AI
• Virtuální zařízení