REST API

Leis an HTTP API, léann tú gléasanna do chuntais ó do ríomhchlár féin. Feiceann an API na gléasanna céanna agus tá na ceadanna céanna aige agus atá ag do chuntas san aip.

Bunphointí

Mír	Luach
URL bunúsach	`https://api.hamsystems.eu`
Formáid an iarratais	`POST` le `application/x-www-form-urlencoded`, mura ndeir an chuid rud eile
Formáid an fhreagra	JSON
Sraithuimhir	`<family>:<number>`, mar shampla `e11:123`. Is é an chéad chuid teaghlach an ghléis.

Tá réimse messages ag an gcuid is mó de na freagraí. Is liosta d’oibiachtaí {"text": "...", "type": "error"} é. Is é error, success nó info an type.

Fíordheimhniú

Tá dhá mhodh ann:

Modh	Conas a fhaigheann tú é	Ré
Eochair API (`api_key`)	Ón leathanach Cuntas san aip	Ní théann sí as feidhm. Eochair amháin do gach cuntas.
Comhartha rochtana (`access_token`)	Ó `login.php` nó `login_api.php`	60 lá

Seol an eochair API ar cheann de na bealaí seo:

An paraiméadar api_key i gcorp an POST nó sa teaghrán iarratais.
An ceanntásc Authorization: Bearer-API YOUR_API_KEY.

Seol an comhartha rochtana ar cheann de na bealaí seo:

An paraiméadar access_token i gcorp an POST nó sa teaghrán iarratais.
An ceanntásc Authorization: Bearer YOUR_ACCESS_TOKEN.

Má sheolann tú an dá cheann, úsáideann an freastalaí an eochair API.

Cruthaigh eochair API

Oscail an Roghchlár agus tapáil Cuntas.
Sa chuid Eochair API, tapáil Gin eochair API.
Deimhnigh an teachtaireacht. Cealaíonn eochair nua an seaneochair.
Tapáil an eochair chun í a chóipeáil. Taispeánann an aip Cóipeáilte.

An chuid Eochair API ar an leathanach Cuntas, leis an eochair i bhfolach — Ríomhaire

Chun eochair a chealú, cruthaigh eochair nua. Stopann an seaneochair ag obair láithreach.

Críochphointí

Seiceáil eochair: `check_api_key.php`

Seiceálann sé eochair API.

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

Freagra: user, messages. Mura bhfuil an eochair ceart, tá an earráid Api key not found i messages.

Comhartha rochtana ó eochair: `login_api.php`

Tugann sé comhartha rochtana don eochair API. Úsáid é nuair nach nglacann uirlis ach le comhartha rochtana.

Paraiméadar	Luach
`key`	An eochair 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": []
}

Tá teorainn iarrachtaí ag an gcríochphointe seo. Tar éis go leor teipeanna, freagraíonn sé Too many attempts, try again later.

Logáil isteach le ríomhphost: `login.php`

Paraiméadar	Luach
`email`	Ríomhphost an chuntais
`password`	An pasfhocal
`timezone`	Roghnach. An crios ama, mar shampla `Europe/Athens`.

Freagra: access_token, user, messages. Má tá must_recaptcha true, iarrann an freastalaí seiceáil reCAPTCHA. Ansin úsáid eochair API.

Liosta na ngléasanna: `get_user_devices.php`

Tugann sé gléasanna, grúpaí, pleananna urláir agus scéalta an chuntais.

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

Réimsí an fhreagra: devices, groups, floorplans, scenes, messages. Le ?v=2&definitions=1 tá réimse definitions sa fhreagra freisin do theaghlaigh do ghléasanna.

Tá na réimsí seo ag gach gléas:

Réimse	Ábhar
`serialno`	An tsraithuimhir, mar shampla `e11:123`
`name`, `icon`	An t-ainm agus an deilbhín ón aip
`mac`	An seoladh MAC
`device_server`	Freastalaí gléis an ghléis. Teastaíonn sé uait don stair agus don WebSocket.
`latitude`, `longitude`	An suíomh, má tá sé socraithe
`firmware_version`	Leagan na ndochtearraí
`settings`	Socruithe an ghléis
`groups`, `floorplans`	Grúpaí agus pleananna urláir an ghléis
`permissions`	Do chead ar an ngléas (féach thíos)

Luachanna permissions:

Luach	Cead
`1`	Léamh
`2`	Scríobh (rialú aschur)
`3`	Riarthóir
`4`	Úinéir

Gléas amháin: `get_device_info.php`

Paraiméadar	Luach
`serialno`	An tsraithuimhir

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

Freagra: device (na réimsí céanna agus atá sa liosta), messages. Glacann sé le &definitions=1 freisin. Gan serialno freagraíonn sé le HTTP 400. Gan rochtain ar an ngléas freagraíonn sé le HTTP 403.

An staid reatha: `get_device_state.php`

Tugann sé léamha reatha gléis amháin nó níos mó. Is JSON é an corp.

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"
  }
}

Le haghaidh níos mó gléasanna, seol liosta: {"serialno": ["e11:123", "e9:456"]}. Is é {"devices": [...], "count": 2} an freagra. Mura bhfuil an staid ar fáil, is é {"connected": false, "message": "Device state not available"} an state. Gan fíordheimhniú, is é HTTP 401 le {"error": "Authentication required"} an freagra.

Sainmhínithe na dteaghlach

Insíonn na sainmhínithe cé na léamha, aschuir agus socruithe atá ag gach teaghlach. Ní theastaíonn fíordheimhniú uathu.

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

Tá families agus readings sa fhreagra. Le &include_readings=false níl an foclóir readings sa fhreagra. Gan family_id tá na teaghlaigh go léir sa fhreagra.

Tá na nithe seo ag gach teaghlach:

Réimse	Ábhar
`readings`	Cóid na léamh ina n-ord, mar shampla `["T", "GI", "GIC", "GI2", "GI2C"]`
`output_names`	Na haschuir ina n-ord
`settings`	Socruithe an teaghlaigh
`ping_period`	An t-eatramh coinneála beo i soicindí

Tugann an foclóir readings an lipéad, an t-aonad agus an tiontú do gach cód léimh. Mar shampla, tá an t-aonad °C agus an tiontú divide_by_100 ag an léamh T. Is féidir leat liosta na léamh a fheiceáil ar an leathanach Foclóir na léamh freisin.

Ciallaíonn an luach 2147483648 go bhfuil an léamh in easnamh.

Teorainn ama

Socraigh teorainn ama de thart ar 30 soicind ar d’iarratais.

Féach freisin

Comhrá leis an tacaíocht