REST API

Met de HTTP API leest u de apparaten van uw account vanuit uw eigen programma. De API ziet dezelfde apparaten en heeft dezelfde rechten als uw account in de app.

Basis

Item	Waarde
Basis-URL	`https://api.hamsystems.eu`
Verzoekindeling	`POST` met `application/x-www-form-urlencoded`, tenzij het gedeelte iets anders zegt
Antwoordindeling	JSON
Serienummer	`<family>:<number>`, bijvoorbeeld `e11:123`. Het eerste deel is de apparaatfamilie.

De meeste antwoorden hebben een veld messages. Het is een lijst met objecten {"text": "...", "type": "error"}. Het type is error, success of info.

Authenticatie

Er zijn twee methoden:

Methode	Hoe u het krijgt	Levensduur
API-sleutel (`api_key`)	Op de pagina Account van de app	Verloopt niet. Eén sleutel per account.
Toegangstoken (`access_token`)	Van `login.php` of `login_api.php`	60 dagen

Stuur de API-sleutel op een van deze manieren:

Parameter api_key in de POST-body of in de querystring.
Header Authorization: Bearer-API YOUR_API_KEY.

Stuur het toegangstoken op een van deze manieren:

Parameter access_token in de POST-body of in de querystring.
Header Authorization: Bearer YOUR_ACCESS_TOKEN.

Stuurt u beide, dan gebruikt de server de API-sleutel.

Een API-sleutel maken

Open het Menu en tik op Account.
Tik in het gedeelte API-sleutel op API-sleutel genereren.
Bevestig het bericht. Een nieuwe sleutel annuleert de oude sleutel.
Tik op de sleutel om hem te kopiëren. De app toont Gekopieerd.

Het gedeelte API-sleutel op de pagina Account, met de verborgen sleutel — Computer

Maak een nieuwe sleutel om een sleutel te annuleren. De oude sleutel werkt direct niet meer.

Endpoints

Een sleutel controleren: `check_api_key.php`

Controleert een API-sleutel.

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

Antwoord: user, messages. Is de sleutel niet juist, dan heeft messages de fout Api key not found.

Toegangstoken van een sleutel: `login_api.php`

Geeft een toegangstoken voor de API-sleutel. Gebruik het wanneer een tool alleen een toegangstoken accepteert.

Parameter	Waarde
`key`	De API-sleutel

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

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

Dit endpoint heeft een limiet voor pogingen. Na veel mislukte pogingen antwoordt het Too many attempts, try again later.

Aanmelden met e-mail: `login.php`

Parameter	Waarde
`email`	Het e-mailadres van het account
`password`	Het wachtwoord
`timezone`	Optioneel. De tijdzone, bijvoorbeeld `Europe/Athens`.

Antwoord: access_token, user, messages. Is must_recaptcha gelijk aan true, dan vraagt de server om een reCAPTCHA-controle. Gebruik dan een API-sleutel.

Apparatenlijst: `get_user_devices.php`

Geeft de apparaten, groepen, plattegronden en scènes van het account.

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

Velden van het antwoord: devices, groups, floorplans, scenes, messages. Met ?v=2&definitions=1 heeft het antwoord ook een veld definitions voor de families van uw apparaten.

Elk apparaat heeft deze velden:

Veld	Inhoud
`serialno`	Het serienummer, bijvoorbeeld `e11:123`
`name`, `icon`	De naam en het pictogram uit de app
`mac`	Het MAC-adres
`device_server`	De apparaatserver van het apparaat. U hebt hem nodig voor de geschiedenis en voor de WebSocket.
`latitude`, `longitude`	De locatie, als die is ingesteld
`firmware_version`	De firmwareversie
`settings`	De apparaatinstellingen
`groups`, `floorplans`	De groepen en plattegronden van het apparaat
`permissions`	Uw recht op het apparaat (zie hieronder)

Waarden van permissions:

Waarde	Recht
`1`	Lezen
`2`	Schrijven (uitgangen bedienen)
`3`	Beheerder
`4`	Eigenaar

Eén apparaat: `get_device_info.php`

Parameter	Waarde
`serialno`	Het serienummer

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

Antwoord: device (dezelfde velden als in de lijst), messages. Het accepteert ook &definitions=1. Zonder serialno antwoordt het met HTTP 400. Zonder toegang tot het apparaat antwoordt het met HTTP 403.

Huidige status: `get_device_state.php`

Geeft de huidige metingen van een of meer apparaten. De body is 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"
  }
}

Stuur voor meer apparaten een lijst: {"serialno": ["e11:123", "e9:456"]}. Het antwoord is {"devices": [...], "count": 2}. Is de status niet beschikbaar, dan is state gelijk aan {"connected": false, "message": "Device state not available"}. Zonder authenticatie is het antwoord HTTP 401 met {"error": "Authentication required"}.

Familiedefinities

De definities vertellen welke metingen, uitgangen en instellingen elke familie heeft. Ze hebben geen authenticatie nodig.

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

Het antwoord heeft families en readings. Met &include_readings=false heeft het antwoord het woordenboek readings niet. Zonder family_id heeft het antwoord alle families.

Elke familie heeft:

Veld	Inhoud
`readings`	De metingcodes in hun volgorde, bijvoorbeeld `["T", "GI", "GIC", "GI2", "GI2C"]`
`output_names`	De uitgangen in hun volgorde
`settings`	De instellingen van de familie
`ping_period`	Het keep-alive-interval in seconden

Het woordenboek readings geeft het label, de eenheid en de omzetting voor elke metingcode. Meting T heeft bijvoorbeeld de eenheid °C en de omzetting divide_by_100. U ziet de lijst met metingen ook op de pagina Metingen.

De waarde 2147483648 betekent dat de meting ontbreekt.

Time-out

Stel op uw verzoeken een time-out van ongeveer 30 seconden in.

Zie ook

Chat met support