REST API

HTTP API:lla luet tilisi laitteita omasta ohjelmastasi. API näkee samat laitteet ja sillä on samat oikeudet kuin tililläsi sovelluksessa.

Perusteet

Kohde	Arvo
Perus-URL	https://api.hamsystems.eu
Pyynnön muoto	POST ja application/x-www-form-urlencoded, ellei osio kerro muuta
Vastauksen muoto	JSON
Sarjanumero	<family>:<number>, esimerkiksi e11:123. Ensimmäinen osa on laiteperhe.

Useimmissa vastauksissa on kenttä messages. Se on luettelo objekteja {"text": "...", "type": "error"}. type on error, success tai info.

Todennus

Menetelmiä on kaksi:

Menetelmä	Mistä saat sen	Voimassaolo
API-avain (api_key)	Sovelluksen sivulta Tili	Ei vanhene. Yksi avain tiliä kohti.
Pääsytunnus (access_token)	Päätepisteestä login.php tai login_api.php	60 päivää

Lähetä API-avain jollakin näistä tavoista:

• Parametri api_key POST-rungossa tai kyselymerkkijonossa.
• Otsake Authorization: Bearer-API YOUR_API_KEY.

Lähetä pääsytunnus jollakin näistä tavoista:

• Parametri access_token POST-rungossa tai kyselymerkkijonossa.
• Otsake Authorization: Bearer YOUR_ACCESS_TOKEN.

Jos lähetät molemmat, palvelin käyttää API-avainta.

Varoitus

API-avain antaa täyden pääsyn tiliisi. Älä laita sitä koodiin, joka toimii selaimessa, tai julkiseen tietovarastoon.

Luo API-avain

1. Avaa Valikko ja napauta Tili.
2. Napauta osiossa API-avain Luo API-avain.
3. Vahvista viesti. Uusi avain peruuttaa vanhan avaimen.
4. Kopioi avain napauttamalla sitä. Sovellus näyttää Kopioitu.

Tietokone

Puhelin

Kun haluat peruuttaa avaimen, luo uusi avain. Vanha avain lakkaa toimimasta heti.

Päätepisteet

Tarkista avain: check_api_key.php

Tarkistaa API-avaimen.

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

Vastaus: user, messages. Jos avain ei ole oikea, kentässä messages on virhe Api key not found.

Pääsytunnus avaimesta: login_api.php

Antaa pääsytunnuksen API-avaimelle. Käytä sitä, kun työkalu hyväksyy vain pääsytunnuksen.

Parametri	Arvo
key	API-avain

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

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

Tällä päätepisteellä on yritysraja. Monen epäonnistumisen jälkeen se vastaa Too many attempts, try again later.

Kirjautuminen sähköpostilla: login.php

Parametri	Arvo
email	Tilin sähköpostiosoite
password	Salasana
timezone	Valinnainen. Aikavyöhyke, esimerkiksi Europe/Athens.

Vastaus: access_token, user, messages. Jos must_recaptcha on true, palvelin pyytää reCAPTCHA-tarkistusta. Käytä silloin API-avainta.

Laiteluettelo: get_user_devices.php

Palauttaa tilin laitteet, ryhmät, pohjapiirrokset ja skenaariot.

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

Vastauksen kentät: devices, groups, floorplans, scenes, messages. Kun käytät ?v=2&definitions=1, vastauksessa on myös kenttä definitions laitteidesi perheille.

Jokaisella laitteella on nämä kentät:

Kenttä	Sisältö
serialno	Sarjanumero, esimerkiksi e11:123
name, icon	Sovelluksen nimi ja kuvake
mac	MAC-osoite
device_server	Laitteen laitepalvelin. Tarvitset sitä historiaan ja WebSocketiin.
latitude, longitude	Sijainti, jos se on asetettu
firmware_version	Laiteohjelmiston versio
settings	Laitteen asetukset
groups, floorplans	Laitteen ryhmät ja pohjapiirrokset
permissions	Oikeutesi laitteeseen (katso alla)

Kentän permissions arvot:

Arvo	Oikeus
1	Luku
2	Kirjoitus (lähtöjen ohjaus)
3	Ylläpitäjä
4	Omistaja

Yksi laite: get_device_info.php

Parametri	Arvo
serialno	Sarjanumero

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

Vastaus: device (samat kentät kuin luettelossa), messages. Se hyväksyy myös &definitions=1. Ilman parametria serialno se vastaa HTTP 400. Ilman laitteen käyttöoikeutta se vastaa HTTP 403.

Nykyinen tila: get_device_state.php

Palauttaa yhden tai useamman laitteen nykyiset mittaukset. Runko on 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"
  }
}

Useammalle laitteelle lähetä luettelo: {"serialno": ["e11:123", "e9:456"]}. Vastaus on {"devices": [...], "count": 2}. Jos tila ei ole saatavilla, state on {"connected": false, "message": "Device state not available"}. Ilman todennusta vastaus on HTTP 401 ja {"error": "Authentication required"}.

Huomio

Kentän readings arvot ovat raakoja. Esimerkissä T: 2082 tarkoittaa 20.82 °C. Perheen määritys kertoo, miten kukin arvo muunnetaan. Katso perheiden määritykset alla.

Perheiden määritykset

Määritykset kertovat, mitä mittauksia, lähtöjä ja asetuksia kullakin perheellä on. Ne eivät tarvitse todennusta.

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

Vastauksessa on families ja readings. Kun käytät &include_readings=false, vastauksessa ei ole readings-sanakirjaa. Ilman parametria family_id vastauksessa ovat kaikki perheet.

Jokaisella perheellä on:

Kenttä	Sisältö
readings	Mittauskoodit järjestyksessään, esimerkiksi ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Lähdöt järjestyksessään
settings	Perheen asetukset
ping_period	Ylläpitoväli sekunteina

readings-sanakirja antaa kunkin mittauskoodin nimen, yksikön ja muunnoksen. Esimerkiksi mittauksen T yksikkö on °C ja muunnos divide_by_100. Näet mittausten luettelon myös sivulla Mittaukset.

Arvo 2147483648 tarkoittaa, että mittaus puuttuu.

Aikakatkaisu

Aseta pyynnöillesi noin 30 sekunnin aikakatkaisu.

Katso myös

• Lataa historiatiedot
• Reaaliaikaiset tiedot (WebSocket)
• MCP tekoälyavustajille
• Virtuaalilaitteet