REST API

Bl-HTTP API taqraw l-apparati tal-kont tagħkom mill-programm tagħkom. L-API tara l-istess apparati u għandha l-istess permessi tal-kont tagħkom fl-app.

Bażi

Oġġett	Valur
URL bażi	https://api.hamsystems.eu
Format tat-talba	POST b’application/x-www-form-urlencoded, sakemm it-taqsima ma tgħidx mod ieħor
Format tat-tweġiba	JSON
Numru tas-serje	<family>:<number>, pereżempju e11:123. L-ewwel parti hija l-familja tal-apparat.

Ħafna mit-tweġibiet għandhom qasam messages. Huwa lista ta’ oġġetti {"text": "...", "type": "error"}. It-type huwa error, success jew info.

Awtentikazzjoni

Hemm żewġ metodi:

Metodu	Kif tiksbuh	Tul ta’ żmien
Ċavetta API (api_key)	Mill-paġna Kont tal-app	Ma tiskadix. Ċavetta waħda għal kull kont.
Access token (access_token)	Minn login.php jew login_api.php	60 jum

Ibagħtu ċ-ċavetta API b’wieħed minn dawn il-modi:

• Il-parametru api_key fil-body tal-POST jew fil-query string.
• Il-header Authorization: Bearer-API YOUR_API_KEY.

Ibagħtu l-access token b’wieħed minn dawn il-modi:

• Il-parametru access_token fil-body tal-POST jew fil-query string.
• Il-header Authorization: Bearer YOUR_ACCESS_TOKEN.

Jekk tibagħtu t-tnejn, is-server juża ċ-ċavetta API.

Attenzjoni

Iċ-ċavetta API tagħti aċċess sħiħ għall-kont tagħkom. Tpoġġuhiex f’kodiċi li jaħdem f’browser jew f’repository pubbliku.

Oħolqu ċavetta API

1. Iftħu l-Menu u agħfsu Kont.
2. Fit-taqsima Ċavetta API, agħfsu Iġġenera ċavetta API.
3. Ikkonfermaw il-messaġġ. Ċavetta ġdida tikkanċella ċ-ċavetta l-qadima.
4. Agħfsu ċ-ċavetta biex tikkupjawha. L-app turi Ikkupjat.

Kompjuter

Telefon

Biex tikkanċellaw ċavetta, oħolqu ċavetta ġdida. Iċ-ċavetta l-qadima tieqaf taħdem minnufih.

Endpoints

Iċċekkjaw ċavetta: check_api_key.php

Jiċċekkja ċavetta API.

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

Tweġiba: user, messages. Jekk iċ-ċavetta mhijiex korretta, messages għandu l-iżball Api key not found.

Access token minn ċavetta: login_api.php

Jagħti access token għaċ-ċavetta API. Użawh meta għodda taċċetta biss access token.

Parametru	Valur
key	Iċ-ċavetta API

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

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

Dan l-endpoint għandu limitu ta’ tentattivi. Wara ħafna fallimenti jwieġeb Too many attempts, try again later.

Idħlu bl-email: login.php

Parametru	Valur
email	L-email tal-kont
password	Il-password
timezone	Fakultattiv. Iż-żona tal-ħin, pereżempju Europe/Athens.

Tweġiba: access_token, user, messages. Jekk must_recaptcha huwa true, is-server jitlob kontroll reCAPTCHA. Imbagħad użaw ċavetta API.

Lista tal-apparati: get_user_devices.php

Jagħti l-apparati, il-gruppi, il-pjanti tal-pjan u x-xeni tal-kont.

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

L-oqsma tat-tweġiba: devices, groups, floorplans, scenes, messages. B’?v=2&definitions=1 it-tweġiba għandha wkoll qasam definitions għall-familji tal-apparati tagħkom.

Kull apparat għandu dawn l-oqsma:

Qasam	Kontenut
serialno	In-numru tas-serje, pereżempju e11:123
name, icon	L-isem u l-ikona mill-app
mac	L-indirizz MAC
device_server	Is-server tal-apparati tal-apparat. Għandkom bżonnu għall-istorja u għall-WebSocket.
latitude, longitude	Il-post, jekk huwa issettjat
firmware_version	Il-verżjoni tal-firmware
settings	Is-settings tal-apparat
groups, floorplans	Il-gruppi u l-pjanti tal-pjan tal-apparat
permissions	Il-permess tagħkom fuq l-apparat (araw hawn taħt)

Il-valuri ta’ permissions:

Valur	Permess
1	Qari
2	Kitba (kontroll tal-outputs)
3	Admin
4	Sid

Apparat wieħed: get_device_info.php

Parametru	Valur
serialno	In-numru tas-serje

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

Tweġiba: device (l-istess oqsma bħal fil-lista), messages. Jaċċetta wkoll &definitions=1. Mingħajr serialno iwieġeb b’HTTP 400. Mingħajr aċċess għall-apparat iwieġeb b’HTTP 403.

L-istat attwali: get_device_state.php

Jagħti l-qari attwali ta’ apparat wieħed jew aktar. Il-body huwa 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"
  }
}

Għal aktar apparati, ibagħtu lista: {"serialno": ["e11:123", "e9:456"]}. It-tweġiba hija {"devices": [...], "count": 2}. Jekk l-istat mhuwiex disponibbli, state huwa {"connected": false, "message": "Device state not available"}. Mingħajr awtentikazzjoni t-tweġiba hija HTTP 401 b’{"error": "Authentication required"}.

Nota

Il-valuri f’readings huma mhux ipproċessati. Fl-eżempju, T: 2082 ifisser 20.82 °C. Id-definizzjoni tal-familja tgħidilkom kif tikkonvertu kull valur. Araw id-definizzjonijiet tal-familji hawn taħt.

Id-definizzjonijiet tal-familji

Id-definizzjonijiet jgħidulkom liema qari, outputs u settings għandha kull familja. M’għandhomx bżonn awtentikazzjoni.

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

It-tweġiba għandha families u readings. B’&include_readings=false it-tweġiba m’għandhiex id-dizzjunarju readings. Mingħajr family_id it-tweġiba għandha l-familji kollha.

Kull familja għandha:

Qasam	Kontenut
readings	Il-kodiċijiet tal-qari fl-ordni tagħhom, pereżempju ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	L-outputs fl-ordni tagħhom
settings	Is-settings tal-familja
ping_period	L-intervall tal-keep-alive f’sekondi

Id-dizzjunarju readings jagħti t-tikketta, l-unità u l-konverżjoni għal kull kodiċi tal-qari. Pereżempju, il-qari T għandu l-unità °C u l-konverżjoni divide_by_100. Tistgħu taraw ukoll il-lista tal-qari fil-paġna Dizzjunarju tal-qari.

Il-valur 2147483648 ifisser li l-qari huwa nieqes.

Timeout

Issettjaw timeout ta’ madwar 30 sekonda fuq it-talbiet tagħkom.

Araw ukoll

• Niżżlu data storika
• Data live (WebSocket)
• MCP għall-assistenti AI
• Apparati virtwali