REST API

Przez API HTTP odczytujesz urządzenia swojego konta z własnego programu. API widzi te same urządzenia i ma te same uprawnienia co Twoje konto w aplikacji.

Podstawy

Element	Wartość
Bazowy URL	https://api.hamsystems.eu
Format żądania	POST z application/x-www-form-urlencoded, chyba że sekcja podaje inaczej
Format odpowiedzi	JSON
Numer seryjny	<rodzina>:<numer>, na przykład e11:123. Pierwsza część to rodzina urządzenia.

Większość odpowiedzi ma pole messages. To lista obiektów {"text": "...", "type": "error"}. type to error, success lub info.

Uwierzytelnianie

Są dwie metody:

Metoda	Jak ją uzyskać	Czas ważności
Klucz API (api_key)	Ze strony Konto w aplikacji	Nie wygasa. Jeden klucz na konto.
Token dostępu (access_token)	Z login.php lub login_api.php	60 dni

Klucz API wysyłaj w jeden z tych sposobów:

• Parametr api_key w treści POST lub w ciągu zapytania.
• Nagłówek Authorization: Bearer-API YOUR_API_KEY.

Token dostępu wysyłaj w jeden z tych sposobów:

• Parametr access_token w treści POST lub w ciągu zapytania.
• Nagłówek Authorization: Bearer YOUR_ACCESS_TOKEN.

Jeśli wyślesz oba, serwer używa klucza API.

Uwaga

Klucz API daje pełny dostęp do Twojego konta. Nie umieszczaj go w kodzie uruchamianym w przeglądarce ani w publicznym repozytorium.

Utworzenie klucza API

1. Otwórz Menu i dotknij Konto.
2. W sekcji Klucz API dotknij Wygeneruj klucz API.
3. Potwierdź komunikat. Nowy klucz unieważnia stary klucz.
4. Dotknij klucza, aby go skopiować. Aplikacja pokazuje Skopiowano.

Komputer

Telefon

Aby unieważnić klucz, utwórz nowy klucz. Stary klucz przestaje działać natychmiast.

Punkty końcowe

Sprawdzenie klucza: check_api_key.php

Sprawdza klucz API.

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

Odpowiedź: user, messages. Jeśli klucz jest niepoprawny, messages zawiera błąd Api key not found.

Token dostępu z klucza: login_api.php

Daje token dostępu dla klucza API. Użyj go, gdy narzędzie przyjmuje tylko token dostępu.

Parametr	Wartość
key	Klucz API

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

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

Ten punkt końcowy ma limit prób. Po wielu niepowodzeniach odpowiada Too many attempts, try again later.

Logowanie przez e-mail: login.php

Parametr	Wartość
email	E-mail konta
password	Hasło
timezone	Opcjonalny. Strefa czasowa, na przykład Europe/Athens.

Odpowiedź: access_token, user, messages. Jeśli must_recaptcha ma wartość true, serwer żąda weryfikacji reCAPTCHA. Wtedy użyj klucza API.

Lista urządzeń: get_user_devices.php

Zwraca urządzenia, grupy, plany pomieszczeń i sceny konta.

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

Pola odpowiedzi: devices, groups, floorplans, scenes, messages. Z ?v=2&definitions=1 odpowiedź ma też pole definitions dla rodzin Twoich urządzeń.

Każde urządzenie ma te pola:

Pole	Zawartość
serialno	Numer seryjny, na przykład e11:123
name, icon	Nazwa i ikona z aplikacji
mac	Adres MAC
device_server	Serwer urządzenia. Potrzebujesz go do historii i do WebSocket.
latitude, longitude	Lokalizacja, jeśli jest ustawiona
firmware_version	Wersja oprogramowania
settings	Ustawienia urządzenia
groups, floorplans	Grupy i plany pomieszczeń urządzenia
permissions	Twoje uprawnienie do urządzenia (zobacz niżej)

Wartości permissions:

Wartość	Uprawnienie
1	Odczyt
2	Zapis (sterowanie wyjściami)
3	Administrator
4	Właściciel

Jedno urządzenie: get_device_info.php

Parametr	Wartość
serialno	Numer seryjny

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

Odpowiedź: device (te same pola co na liście), messages. Przyjmuje też &definitions=1. Bez serialno odpowiada HTTP 400. Bez dostępu do urządzenia odpowiada HTTP 403.

Bieżący stan: get_device_state.php

Zwraca bieżące odczyty jednego lub wielu urządzeń. Treść to 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"
  }
}

Dla większej liczby urządzeń wyślij listę: {"serialno": ["e11:123", "e9:456"]}. Odpowiedź to {"devices": [...], "count": 2}. Jeśli stan jest niedostępny, state ma wartość {"connected": false, "message": "Device state not available"}. Bez uwierzytelnienia odpowiedź to HTTP 401 z {"error": "Authentication required"}.

Notatka

Wartości w readings są surowe. W przykładzie T: 2082 oznacza 20.82 °C. Definicja rodziny mówi, jak przeliczyć każdą wartość. Zobacz definicje rodzin niżej.

Definicje rodzin

Definicje mówią, jakie odczyty, wyjścia i ustawienia ma każda rodzina. Nie wymagają uwierzytelnienia.

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

Odpowiedź ma families i readings. Z &include_readings=false odpowiedź nie ma słownika readings. Bez family_id odpowiedź ma wszystkie rodziny.

Każda rodzina ma:

Pole	Zawartość
readings	Kody odczytów w kolejności, na przykład ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Wyjścia w kolejności
settings	Ustawienia rodziny
ping_period	Odstęp sygnału podtrzymania w sekundach

Słownik readings podaje etykietę, jednostkę i przeliczenie dla każdego kodu odczytu. Na przykład odczyt T ma jednostkę °C i przeliczenie divide_by_100. Listę odczytów zobaczysz też na stronie Odczyty.

Wartość 2147483648 oznacza, że odczyt jest brakujący.

Limit czasu

Ustaw w swoich żądaniach limit czasu około 30 sekund.

Zobacz też

• Pobieranie danych historycznych
• Dane na żywo (WebSocket)
• MCP dla asystentów AI
• Urządzenia wirtualne