REST API

Með HTTP API lestu tæki reikningsins þíns úr þínu eigin forriti. API sér sömu tæki og hefur sömu heimildir og reikningurinn þinn í appinu.

Grunnatriði

Atriði	Gildi
Grunn-URL	https://api.hamsystems.eu
Snið beiðna	POST með application/x-www-form-urlencoded, nema hlutinn segi annað
Snið svara	JSON
Raðnúmer	<family>:<number>, til dæmis e11:123. Fyrsti hlutinn er tækjafjölskyldan.

Flest svör hafa reitinn messages. Hann er listi af hlutum {"text": "...", "type": "error"}. Gildið type er error, success eða info.

Auðkenning

Það eru tvær aðferðir:

Aðferð	Hvernig þú færð hana	Gildistími
API-lykill (api_key)	Á síðunni Reikningur í appinu	Hann rennur ekki út. Einn lykill fyrir hvern reikning.
Aðgangstákn (access_token)	Frá login.php eða login_api.php	60 dagar

Sendu API-lykilinn á einn af þessum vegum:

• Færibreytan api_key í POST-meginmálinu eða í fyrirspurnarstrengnum.
• Hausinn Authorization: Bearer-API YOUR_API_KEY.

Sendu aðgangstáknið á einn af þessum vegum:

• Færibreytan access_token í POST-meginmálinu eða í fyrirspurnarstrengnum.
• Hausinn Authorization: Bearer YOUR_ACCESS_TOKEN.

Ef þú sendir bæði notar netþjónninn API-lykilinn.

Varúð

API-lykillinn gefur fullan aðgang að reikningnum þínum. Settu hann ekki í kóða sem keyrir í vafra eða í opinbera kóðageymslu.

Búa til API-lykil

1. Opnaðu Valmynd og ýttu á Reikningur.
2. Í hlutanum API-lykill ýtirðu á Búa til API-lykil.
3. Staðfestu skilaboðin. Nýr lykill ógildir gamla lykilinn.
4. Ýttu á lykilinn til að afrita hann. Appið sýnir Afritað.

Tölva

Sími

Til að ógilda lykil býrðu til nýjan lykil. Gamli lykillinn hættir strax að virka.

Endapunktar

Athuga lykil: check_api_key.php

Athugar API-lykil.

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

Svar: user, messages. Ef lykillinn er ekki réttur hefur messages villuna Api key not found.

Aðgangstákn frá lykli: login_api.php

Gefur aðgangstákn fyrir API-lykilinn. Notaðu það þegar verkfæri tekur aðeins við aðgangstákni.

Færibreyta	Gildi
key	API-lykillinn

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

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

Þessi endapunktur hefur takmörk á tilraunum. Eftir margar villur svarar hann Too many attempts, try again later.

Innskráning með tölvupósti: login.php

Færibreyta	Gildi
email	Netfang reikningsins
password	Lykilorðið
timezone	Valfrjálst. Tímabeltið, til dæmis Europe/Athens.

Svar: access_token, user, messages. Ef must_recaptcha er true biður netþjónninn um reCAPTCHA-athugun. Notaðu þá API-lykil.

Tækjalisti: get_user_devices.php

Skilar tækjum, hópum, grunnmyndum og sviðum reikningsins.

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

Reitir svarsins: devices, groups, floorplans, scenes, messages. Með ?v=2&definitions=1 hefur svarið líka reitinn definitions fyrir fjölskyldur tækjanna þinna.

Hvert tæki hefur þessa reiti:

Reitur	Innihald
serialno	Raðnúmerið, til dæmis e11:123
name, icon	Nafnið og táknið úr appinu
mac	MAC-vistfangið
device_server	Tækjaþjónn tækisins. Þú þarft hann fyrir söguna og fyrir WebSocket.
latitude, longitude	Staðsetningin, ef hún er stillt
firmware_version	Útgáfa fastbúnaðarins
settings	Stillingar tækisins
groups, floorplans	Hópar og grunnmyndir tækisins
permissions	Heimild þín á tækinu (sjá fyrir neðan)

Gildi permissions:

Gildi	Heimild
1	Lesa
2	Skrifa (stýra úttökum)
3	Stjórnandi
4	Eigandi

Eitt tæki: get_device_info.php

Færibreyta	Gildi
serialno	Raðnúmerið

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 (sömu reitir og í listanum), messages. Hann tekur líka við &definitions=1. Án serialno svarar hann með HTTP 400. Án aðgangs að tækinu svarar hann með HTTP 403.

Núverandi staða: get_device_state.php

Skilar núverandi mælingum eins eða fleiri tækja. Meginmálið 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"
  }
}

Fyrir fleiri tæki sendirðu lista: {"serialno": ["e11:123", "e9:456"]}. Svarið er {"devices": [...], "count": 2}. Ef staðan er ekki tiltæk er state {"connected": false, "message": "Device state not available"}. Án auðkenningar er svarið HTTP 401 með {"error": "Authentication required"}.

Athugasemd

Gildin í readings eru óunnin. Í dæminu merkir T: 2082 20,82 °C. Skilgreining fjölskyldunnar segir þér hvernig þú umreiknar hvert gildi. Sjá skilgreiningar fjölskyldnanna hér fyrir neðan.

Skilgreiningar fjölskyldna

Skilgreiningarnar segja þér hvaða mælingar, úttök og stillingar hver fjölskylda hefur. Þær þurfa ekki auðkenningu.

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

Svarið hefur families og readings. Með &include_readings=false hefur svarið ekki orðabókina readings. Án family_id hefur svarið allar fjölskyldur.

Hver fjölskylda hefur:

Reitur	Innihald
readings	Kóðar mælinganna í sinni röð, til dæmis ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Úttökin í sinni röð
settings	Stillingar fjölskyldunnar
ping_period	Millibil lífsmerkisins í sekúndum

Orðabókin readings gefur heiti, einingu og umreikning fyrir hvern kóða mælingar. Til dæmis hefur mælingin T eininguna °C og umreikninginn divide_by_100. Þú getur líka séð lista mælinganna á síðunni Orðabók mælinga.

Gildið 2147483648 merkir að mælinguna vantar.

Tímamörk

Stilltu tímamörk upp á um 30 sekúndur á beiðnirnar þínar.

Sjá líka

• Sækja söguleg gögn
• Gögn í rauntíma (WebSocket)
• MCP fyrir gervigreindaraðstoðarmenn
• Sýndartæki