REST API

Med HTTP API-et leser du enhetene på kontoen din fra ditt eget program. API-et ser de samme enhetene og har de samme tillatelsene som kontoen din i appen.

Grunnleggende

Punkt	Verdi
Basis-URL	https://api.hamsystems.eu
Format på forespørselen	POST med application/x-www-form-urlencoded, hvis ikke delen sier noe annet
Format på svaret	JSON
Serienummer	<family>:<number>, for eksempel e11:123. Den første delen er enhetsfamilien.

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

Autentisering

Det finnes to metoder:

Metode	Hvordan du får den	Levetid
API-nøkkel (api_key)	Fra siden Konto i appen	Den utløper ikke. Én nøkkel per konto.
Tilgangstoken (access_token)	Fra login.php eller login_api.php	60 dager

Send API-nøkkelen på en av disse måtene:

• Parameteren api_key i POST-innholdet eller i spørrestrengen.
• Headeren Authorization: Bearer-API YOUR_API_KEY.

Send tilgangstokenet på en av disse måtene:

• Parameteren access_token i POST-innholdet eller i spørrestrengen.
• Headeren Authorization: Bearer YOUR_ACCESS_TOKEN.

Hvis du sender begge, bruker serveren API-nøkkelen.

Advarsel

API-nøkkelen gir full tilgang til kontoen din. Ikke sett den i kode som kjører i en nettleser, eller i et offentlig repository.

Lag en API-nøkkel

1. Åpne Meny og trykk på Konto.
2. I delen API-nøkkel, trykk på Generer API-nøkkel.
3. Bekreft meldingen. En ny nøkkel opphever den gamle nøkkelen.
4. Trykk på nøkkelen for å kopiere den. Appen viser Kopiert.

Datamaskin

Telefon

For å oppheve en nøkkel, lag en ny nøkkel. Den gamle nøkkelen slutter å virke med en gang.

Endepunkter

Kontroller en nøkkel: check_api_key.php

Kontrollerer en API-nøkkel.

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

Svar: user, messages. Hvis nøkkelen ikke er riktig, har messages feilen Api key not found.

Tilgangstoken fra en nøkkel: login_api.php

Gir et tilgangstoken for API-nøkkelen. Bruk det når et verktøy godtar bare et tilgangstoken.

Parameter	Verdi
key	API-nøkkelen

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 endepunktet har en grense for forsøk. Etter mange feil svarer det Too many attempts, try again later.

Logg inn med e-post: login.php

Parameter	Verdi
email	E-posten for kontoen
password	Passordet
timezone	Valgfritt. Tidssonen, for eksempel Europe/Athens.

Svar: access_token, user, messages. Hvis must_recaptcha er true, ber serveren om en kontroll med reCAPTCHA. Bruk da en API-nøkkel.

Liste over enheter: get_user_devices.php

Returnerer enhetene, gruppene, plantegningene og scenene på kontoen.

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

Felt i svaret: devices, groups, floorplans, scenes, messages. Med ?v=2&definitions=1 har svaret også et felt definitions for familiene til enhetene dine.

Hver enhet har disse feltene:

Felt	Innhold
serialno	Serienummeret, for eksempel e11:123
name, icon	Navnet og ikonet fra appen
mac	MAC-adressen
device_server	Enhetsserveren for enheten. Du trenger den for historikk og for WebSocket.
latitude, longitude	Posisjonen, hvis den er stilt inn
firmware_version	Versjonen av fastvaren
settings	Innstillingene for enheten
groups, floorplans	Gruppene og plantegningene for enheten
permissions	Tillatelsen din for enheten (se nedenfor)

Verdier for permissions:

Verdi	Tillatelse
1	Lese
2	Skrive (styre utganger)
3	Administrator
4	Eier

Én enhet: get_device_info.php

Parameter	Verdi
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 feltene som i listen), messages. Det godtar også &definitions=1. Uten serialno svarer det med HTTP 400. Uten tilgang til enheten svarer det med HTTP 403.

Aktuell tilstand: get_device_state.php

Returnerer de aktuelle avlesningene for én eller flere enheter. Innholdet 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"
  }
}

For flere enheter, send en liste: {"serialno": ["e11:123", "e9:456"]}. Svaret er {"devices": [...], "count": 2}. Hvis tilstanden ikke er tilgjengelig, er state lik {"connected": false, "message": "Device state not available"}. Uten autentisering er svaret HTTP 401 med {"error": "Authentication required"}.

Merknad

Verdiene i readings er rå. I eksempelet betyr T: 2082 20,82 °C. Definisjonen for familien sier hvordan du konverterer hver verdi. Se definisjonene for familier nedenfor.

Definisjoner for familier

Definisjonene sier hvilke avlesninger, utganger og innstillinger hver familie har. De krever ikke autentisering.

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

Svaret har families og readings. Med &include_readings=false har svaret ikke ordboken readings. Uten family_id har svaret alle familiene.

Hver familie har:

Felt	Innhold
readings	Kodene for avlesningene i rekkefølge, for eksempel ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Utgangene i rekkefølge
settings	Innstillingene for familien
ping_period	Intervallet for keep-alive i sekunder

Ordboken readings gir etiketten, måleenheten og konverteringen for hver kode. For eksempel har avlesningen T måleenheten °C og konverteringen divide_by_100. Du kan også se listen over avlesninger på siden Ordbok for avlesninger.

Verdien 2147483648 betyr at avlesningen mangler.

Tidsavbrudd

Still inn et tidsavbrudd på omtrent 30 sekunder for forespørslene dine.

Se også

• Last ned historiske data
• Data i sanntid (WebSocket)
• MCP for AI-assistenter
• Virtuelle enheter