REST API

Med HTTP API læser du enhederne på din konto fra dit eget program. API’et ser de samme enheder og har de samme tilladelser som din konto i app’en.

Grundlæggende

Element	Værdi
Basis-URL	https://api.hamsystems.eu
Format for anmodninger	POST med application/x-www-form-urlencoded, medmindre sektionen siger noget andet
Format for svar	JSON
Serienummer	<family>:<number>, for eksempel e11:123. Den første del er enhedsfamilien.

De fleste svar har et felt messages. Det er en liste over objekter {"text": "...", "type": "error"}. type er error, success eller info.

Godkendelse

Der er to metoder:

Metode	Hvordan du får den	Levetid
API-nøgle (api_key)	Fra siden Konto i app’en	Den udløber ikke. Én nøgle for hver konto.
Adgangstoken (access_token)	Fra login.php eller login_api.php	60 dage

Send API-nøglen på en af disse måder:

• Parameteren api_key i POST-indholdet eller i forespørgselsstrengen.
• Headeren Authorization: Bearer-API YOUR_API_KEY.

Send adgangstokenet på en af disse måder:

• Parameteren access_token i POST-indholdet eller i forespørgselsstrengen.
• Headeren Authorization: Bearer YOUR_ACCESS_TOKEN.

Hvis du sender begge, bruger serveren API-nøglen.

Bemærk

API-nøglen giver fuld adgang til din konto. Sæt den ikke i kode, der kører i en browser, eller i et offentligt repository.

Opret en API-nøgle

1. Åbn Menu, og tryk på Konto.
2. Tryk på Generér API-nøgle i sektionen API-nøgle.
3. Bekræft meddelelsen. En ny nøgle annullerer den gamle nøgle.
4. Tryk på nøglen for at kopiere den. App’en viser Kopieret.

Computer

Telefon

Opret en ny nøgle for at annullere en nøgle. Den gamle nøgle holder op med at virke med det samme.

Endpunkter

Kontrollér en nøgle: check_api_key.php

Kontrollerer en API-nøgle.

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

Svar: user, messages. Hvis nøglen ikke er korrekt, har messages fejlen Api key not found.

Adgangstoken fra en nøgle: login_api.php

Giver et adgangstoken for API-nøglen. Brug det, når et værktøj kun accepterer et adgangstoken.

Parameter	Værdi
key	API-nøglen

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

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

Dette endpunkt har en grænse for forsøg. Efter mange fejl svarer det Too many attempts, try again later.

Log ind med e-mail: login.php

Parameter	Værdi
email	Kontoens e-mail
password	Adgangskoden
timezone	Valgfri. Tidszonen, for eksempel Europe/Athens.

Svar: access_token, user, messages. Hvis must_recaptcha er true, beder serveren om en reCAPTCHA-kontrol. Brug så en API-nøgle.

Liste over enheder: get_user_devices.php

Returnerer kontoens enheder, grupper, plantegninger og scener.

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

Felter i svaret: devices, groups, floorplans, scenes, messages. Med ?v=2&definitions=1 har svaret også feltet definitions for dine enheders familier.

Hver enhed har disse felter:

Felt	Indhold
serialno	Serienummeret, for eksempel e11:123
name, icon	Navnet og ikonet fra app’en
mac	MAC-adressen
device_server	Enhedens enhedsserver. Du skal bruge den til historik og til WebSocket.
latitude, longitude	Placeringen, hvis den er indstillet
firmware_version	Firmwareversionen
settings	Enhedens indstillinger
groups, floorplans	Enhedens grupper og plantegninger
permissions	Din tilladelse til enheden (se nedenfor)

Værdier for permissions:

Værdi	Tilladelse
1	Læse
2	Skrive (styre udgange)
3	Administrator
4	Ejer

Én enhed: get_device_info.php

Parameter	Værdi
serialno	Serienummeret

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 (de samme felter som i listen), messages. Det accepterer også &definitions=1. Uden serialno svarer det med HTTP 400. Uden adgang til enheden svarer det med HTTP 403.

Aktuel tilstand: get_device_state.php

Returnerer de aktuelle målinger for én eller flere enheder. Indholdet er 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"
  }
}

Send en liste for flere enheder: {"serialno": ["e11:123", "e9:456"]}. Svaret er {"devices": [...], "count": 2}. Hvis tilstanden ikke er tilgængelig, er state lig med {"connected": false, "message": "Device state not available"}. Uden godkendelse er svaret HTTP 401 med {"error": "Authentication required"}.

Note

Værdierne i readings er rå. I eksemplet betyder T: 2082 20.82 °C. Familiens definition fortæller dig, hvordan du omregner hver værdi. Se familiernes definitioner nedenfor.

Familiernes definitioner

Definitionerne fortæller dig, hvilke målinger, udgange og indstillinger hver familie har. De kræver ikke godkendelse.

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

Svaret har families og readings. Med &include_readings=false har svaret ikke ordbogen readings. Uden family_id har svaret alle familier.

Hver familie har:

Felt	Indhold
readings	Koderne for målingerne i deres rækkefølge, for eksempel ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Udgangene i deres rækkefølge
settings	Familiens indstillinger
ping_period	Intervallet for keep-alive i sekunder

Ordbogen readings giver etiketten, enheden og omregningen for hver kode for en måling. For eksempel har målingen T enheden °C og omregningen divide_by_100. Du kan også se listen over målinger på siden Ordbog over målinger.

Værdien 2147483648 betyder, at målingen mangler.

Timeout

Indstil en timeout på cirka 30 sekunder på dine anmodninger.

Se også

• Download historiske data
• Aktuelle data (WebSocket)
• MCP til AI-assistenter
• Virtuelle enheder