REST API

Med HTTP API läser du enheterna i ditt konto från ditt eget program. API ser samma enheter och har samma behörigheter som ditt konto i appen.

Grunder

Objekt	Värde
Bas-URL	https://api.hamsystems.eu
Format för begäran	POST med application/x-www-form-urlencoded, om avsnittet inte säger något annat
Format för svar	JSON
Serienummer	<family>:<number>, till exempel e11:123. Den första delen är enhetsfamiljen.

De flesta svar har fältet messages. Det är en lista med objekt {"text": "...", "type": "error"}. type är error, success eller info.

Autentisering

Det finns två metoder:

Metod	Hur du får den	Livslängd
API-nyckel (api_key)	Från sidan Konto i appen	Den upphör inte att gälla. En nyckel per konto.
Åtkomsttoken (access_token)	Från login.php eller login_api.php	60 dagar

Skicka API-nyckeln på ett av dessa sätt:

• Parametern api_key i POST-innehållet eller i frågesträngen.
• Huvudet Authorization: Bearer-API YOUR_API_KEY.

Skicka åtkomsttoken på ett av dessa sätt:

• Parametern access_token i POST-innehållet eller i frågesträngen.
• Huvudet Authorization: Bearer YOUR_ACCESS_TOKEN.

Om du skickar båda använder servern API-nyckeln.

Caution

API-nyckeln ger full åtkomst till ditt konto. Lägg den inte i kod som körs i en webbläsare eller i ett offentligt repository.

Skapa en API-nyckel

1. Öppna Meny och tryck på Konto.
2. I avsnittet API-nyckel, tryck på Skapa API-nyckel.
3. Bekräfta meddelandet. En ny nyckel annullerar den gamla nyckeln.
4. Tryck på nyckeln för att kopiera den. Appen visar Kopierat.

Dator

Telefon

För att annullera en nyckel, skapa en ny nyckel. Den gamla nyckeln slutar att fungera direkt.

Slutpunkter

Kontrollera en nyckel: check_api_key.php

Kontrollerar en API-nyckel.

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

Svar: user, messages. Om nyckeln inte är korrekt har messages felet Api key not found.

Åtkomsttoken från en nyckel: login_api.php

Ger en åtkomsttoken för API-nyckeln. Använd den när ett verktyg bara accepterar en åtkomsttoken.

Parameter	Värde
key	API-nyckeln

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

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

Den här slutpunkten har en gräns för försök. Efter många misslyckanden svarar den Too many attempts, try again later.

Logga in med e-post: login.php

Parameter	Värde
email	Kontots e-postadress
password	Lösenordet
timezone	Valfri. Tidszonen, till exempel Europe/Athens.

Svar: access_token, user, messages. Om must_recaptcha är true begär servern en kontroll med reCAPTCHA. Använd då en API-nyckel.

Lista över enheter: get_user_devices.php

Returnerar kontots enheter, grupper, planritningar och scener.

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

Fält i svaret: devices, groups, floorplans, scenes, messages. Med ?v=2&definitions=1 har svaret också fältet definitions för familjerna för dina enheter.

Varje enhet har dessa fält:

Fält	Innehåll
serialno	Serienumret, till exempel e11:123
name, icon	Namnet och ikonen från appen
mac	MAC-adressen
device_server	Enhetens enhetsserver. Du behöver den för historiken och för WebSocket.
latitude, longitude	Platsen, om den är inställd
firmware_version	Firmwareversionen
settings	Enhetens inställningar
groups, floorplans	Enhetens grupper och planritningar
permissions	Din behörighet på enheten (se nedan)

Värden för permissions:

Värde	Behörighet
1	Läsa
2	Skriva (styra utgångar)
3	Admin
4	Ägare

En enhet: get_device_info.php

Parameter	Värde
serialno	Serienumret

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

Svar: device (samma fält som i listan), messages. Den accepterar också &definitions=1. Utan serialno svarar den med HTTP 400. Utan åtkomst till enheten svarar den med HTTP 403.

Aktuellt tillstånd: get_device_state.php

Returnerar de aktuella avläsningarna för en eller flera enheter. Innehållet är 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 fler enheter, skicka en lista: {"serialno": ["e11:123", "e9:456"]}. Svaret är {"devices": [...], "count": 2}. Om tillståndet inte är tillgängligt är state lika med {"connected": false, "message": "Device state not available"}. Utan autentisering är svaret HTTP 401 med {"error": "Authentication required"}.

Note

Värdena i readings är råvärden. I exemplet betyder T: 2082 20.82 °C. Familjedefinitionen säger hur du konverterar varje värde. Se familjedefinitionerna nedan.

Familjedefinitioner

Definitionerna säger vilka avläsningar, utgångar och inställningar varje familj har. De behöver ingen autentisering.

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

Svaret har families och readings. Med &include_readings=false har svaret inte ordlistan readings. Utan family_id har svaret alla familjer.

Varje familj har:

Fält	Innehåll
readings	Avläsningarnas koder i ordning, till exempel ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Utgångarna i ordning
settings	Familjens inställningar
ping_period	Intervallet för keep-alive i sekunder

Ordlistan readings ger etiketten, enheten och konverteringen för varje avläsningskod. Avläsningen T har till exempel enheten °C och konverteringen divide_by_100. Du kan också se listan över avläsningar på sidan Ordlista för avläsningar.

Värdet 2147483648 betyder att avläsningen saknas.

Tidsgräns

Ställ in en tidsgräns på ungefär 30 sekunder för dina begäranden.

Se också

• Ladda ner historiska data
• Data i realtid (WebSocket)
• MCP för AI-assistenter
• Virtuella enheter