REST-API

Mit der HTTP-API lesen Sie die Geräte Ihres Kontos aus Ihrem eigenen Programm. Die API sieht dieselben Geräte und hat dieselben Berechtigungen wie Ihr Konto in der App.

Grundlagen

Element	Wert
Basis-URL	https://api.hamsystems.eu
Anfrageformat	POST mit application/x-www-form-urlencoded, wenn der Abschnitt nichts anderes sagt
Antwortformat	JSON
Seriennummer	<family>:<number>, zum Beispiel e11:123. Der erste Teil ist die Gerätefamilie.

Die meisten Antworten haben ein Feld messages. Es ist eine Liste von Objekten {"text": "...", "type": "error"}. Der type ist error, success oder info.

Authentifizierung

Es gibt zwei Methoden:

Methode	Wie Sie sie erhalten	Lebensdauer
API-Schlüssel (api_key)	Von der Seite Konto der App	Er läuft nicht ab. Ein Schlüssel pro Konto.
Access-Token (access_token)	Von login.php oder login_api.php	60 Tage

Senden Sie den API-Schlüssel auf eine dieser Arten:

• Parameter api_key im POST-Body oder im Query-String.
• Header Authorization: Bearer-API YOUR_API_KEY.

Senden Sie den Access-Token auf eine dieser Arten:

• Parameter access_token im POST-Body oder im Query-String.
• Header Authorization: Bearer YOUR_ACCESS_TOKEN.

Wenn Sie beides senden, verwendet der Server den API-Schlüssel.

Achtung

Der API-Schlüssel gibt vollen Zugriff auf Ihr Konto. Legen Sie ihn nicht in Code, der in einem Browser läuft, oder in einem öffentlichen Repository ab.

Einen API-Schlüssel erstellen

1. Öffnen Sie das Menü und tippen Sie auf Konto.
2. Tippen Sie im Bereich API-Schlüssel auf API-Schlüssel generieren.
3. Bestätigen Sie die Meldung. Ein neuer Schlüssel macht den alten Schlüssel ungültig.
4. Tippen Sie auf den Schlüssel, um ihn zu kopieren. Die App zeigt Kopiert.

Computer

Telefon

Um einen Schlüssel ungültig zu machen, erstellen Sie einen neuen Schlüssel. Der alte Schlüssel funktioniert sofort nicht mehr.

Endpunkte

Einen Schlüssel prüfen: check_api_key.php

Prüft einen API-Schlüssel.

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

Antwort: user, messages. Wenn der Schlüssel nicht korrekt ist, hat messages den Fehler Api key not found.

Access-Token aus einem Schlüssel: login_api.php

Gibt einen Access-Token für den API-Schlüssel. Verwenden Sie ihn, wenn ein Werkzeug nur einen Access-Token akzeptiert.

Parameter	Wert
key	Der API-Schlüssel

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

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

Dieser Endpunkt hat ein Limit für Versuche. Nach vielen Fehlversuchen antwortet er Too many attempts, try again later.

Mit E-Mail anmelden: login.php

Parameter	Wert
email	Die E-Mail des Kontos
password	Das Passwort
timezone	Optional. Die Zeitzone, zum Beispiel Europe/Athens.

Antwort: access_token, user, messages. Wenn must_recaptcha den Wert true hat, verlangt der Server eine reCAPTCHA-Prüfung. Verwenden Sie dann einen API-Schlüssel.

Geräteliste: get_user_devices.php

Gibt die Geräte, Gruppen, Grundrisse und Szenen des Kontos zurück.

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

Felder der Antwort: devices, groups, floorplans, scenes, messages. Mit ?v=2&definitions=1 hat die Antwort auch ein Feld definitions für die Familien Ihrer Geräte.

Jedes Gerät hat diese Felder:

Feld	Inhalt
serialno	Die Seriennummer, zum Beispiel e11:123
name, icon	Der Name und das Symbol aus der App
mac	Die MAC-Adresse
device_server	Der Geräteserver des Geräts. Sie brauchen ihn für den Verlauf und für den WebSocket.
latitude, longitude	Der Standort, wenn er eingestellt ist
firmware_version	Die Firmware-Version
settings	Die Geräteeinstellungen
groups, floorplans	Die Gruppen und Grundrisse des Geräts
permissions	Ihre Berechtigung auf dem Gerät (siehe unten)

Werte von permissions:

Wert	Berechtigung
1	Lesen
2	Schreiben (Ausgänge steuern)
3	Admin
4	Eigentümer

Ein Gerät: get_device_info.php

Parameter	Wert
serialno	Die Seriennummer

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

Antwort: device (dieselben Felder wie in der Liste), messages. Der Endpunkt akzeptiert auch &definitions=1. Ohne serialno antwortet er mit HTTP 400. Ohne Zugriff auf das Gerät antwortet er mit HTTP 403.

Aktueller Zustand: get_device_state.php

Gibt die aktuellen Messwerte von einem oder mehreren Geräten zurück. Der Body ist 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"
  }
}

Für mehrere Geräte senden Sie eine Liste: {"serialno": ["e11:123", "e9:456"]}. Die Antwort ist {"devices": [...], "count": 2}. Wenn der Zustand nicht verfügbar ist, ist state gleich {"connected": false, "message": "Device state not available"}. Ohne Authentifizierung ist die Antwort HTTP 401 mit {"error": "Authentication required"}.

Hinweis

Die Werte in readings sind roh. Im Beispiel bedeutet T: 2082 20,82 °C. Die Familiendefinition sagt Ihnen, wie Sie jeden Wert umrechnen. Siehe die Familiendefinitionen unten.

Familiendefinitionen

Die Definitionen sagen Ihnen, welche Messwerte, Ausgänge und Einstellungen jede Familie hat. Sie brauchen keine Authentifizierung.

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

Die Antwort hat families und readings. Mit &include_readings=false hat die Antwort das Wörterbuch readings nicht. Ohne family_id hat die Antwort alle Familien.

Jede Familie hat:

Feld	Inhalt
readings	Die Messwertcodes in ihrer Reihenfolge, zum Beispiel ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Die Ausgänge in ihrer Reihenfolge
settings	Die Einstellungen der Familie
ping_period	Das Keep-alive-Intervall in Sekunden

Das Wörterbuch readings gibt für jeden Messwertcode die Bezeichnung, die Einheit und die Umrechnung. Zum Beispiel hat der Messwert T die Einheit °C und die Umrechnung divide_by_100. Die Liste der Messwerte sehen Sie auch auf der Seite Messwerte.

Der Wert 2147483648 bedeutet, dass der Messwert fehlt.

Zeitlimit

Stellen Sie für Ihre Anfragen ein Zeitlimit von etwa 30 Sekunden ein.

Siehe auch

• Historische Daten herunterladen
• Live-Daten (WebSocket)
• MCP für KI-Assistenten
• Virtuelle Geräte