API REST

Cu API-ul HTTP citiți dispozitivele contului dumneavoastră din propriul program. API-ul vede aceleași dispozitive și are aceleași permisiuni ca și contul dumneavoastră din aplicație.

Noțiuni de bază

Element	Valoare
URL de bază	`https://api.hamsystems.eu`
Formatul cererii	`POST` cu `application/x-www-form-urlencoded`, dacă secțiunea nu spune altceva
Formatul răspunsului	JSON
Număr de serie	`<family>:<number>`, de exemplu `e11:123`. Prima parte este familia dispozitivului.

Majoritatea răspunsurilor au un câmp messages. Este o listă de obiecte {"text": "...", "type": "error"}. type este error, success sau info.

Autentificare

Există două metode:

Metodă	Cum o obțineți	Durată de viață
Cheie API (`api_key`)	Din pagina Cont a aplicației	Nu expiră. O cheie pe cont.
Token de acces (`access_token`)	Din `login.php` sau `login_api.php`	60 de zile

Trimiteți cheia API într-unul dintre aceste moduri:

Parametrul api_key în corpul POST sau în query string.
Antetul Authorization: Bearer-API YOUR_API_KEY.

Trimiteți tokenul de acces într-unul dintre aceste moduri:

Parametrul access_token în corpul POST sau în query string.
Antetul Authorization: Bearer YOUR_ACCESS_TOKEN.

Dacă trimiteți ambele, serverul folosește cheia API.

Creați o cheie API

Deschideți Meniu și atingeți Cont.
În secțiunea Cheie API, atingeți Generare cheie API.
Confirmați mesajul. O cheie nouă anulează cheia veche.
Atingeți cheia pentru a o copia. Aplicația afișează Copiat.

Secțiunea Cheie API din pagina Cont, cu cheia ascunsă — Calculator

Pentru a anula o cheie, creați o cheie nouă. Cheia veche nu mai funcționează imediat.

Endpoint-uri

Verificați o cheie: `check_api_key.php`

Verifică o cheie API.

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

Răspuns: user, messages. Dacă cheia nu este corectă, messages conține eroarea Api key not found.

Token de acces dintr-o cheie: `login_api.php`

Dă un token de acces pentru cheia API. Folosiți-l când un instrument acceptă numai un token de acces.

Parametru	Valoare
`key`	Cheia 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": []
}

Acest endpoint are o limită de încercări. După multe eșecuri răspunde Too many attempts, try again later.

Autentificare cu e-mail: `login.php`

Parametru	Valoare
`email`	E-mailul contului
`password`	Parola
`timezone`	Opțional. Fusul orar, de exemplu `Europe/Athens`.

Răspuns: access_token, user, messages. Dacă must_recaptcha este true, serverul cere o verificare reCAPTCHA. Atunci folosiți o cheie API.

Lista de dispozitive: `get_user_devices.php`

Returnează dispozitivele, grupurile, planurile de etaj și scenariile contului.

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

Câmpuri în răspuns: devices, groups, floorplans, scenes, messages. Cu ?v=2&definitions=1 răspunsul are și un câmp definitions pentru familiile dispozitivelor dumneavoastră.

Fiecare dispozitiv are aceste câmpuri:

Câmp	Conținut
`serialno`	Numărul de serie, de exemplu `e11:123`
`name`, `icon`	Numele și pictograma din aplicație
`mac`	Adresa MAC
`device_server`	Serverul de dispozitive al dispozitivului. Aveți nevoie de el pentru istoric și pentru WebSocket.
`latitude`, `longitude`	Locația, dacă este setată
`firmware_version`	Versiunea firmware
`settings`	Setările dispozitivului
`groups`, `floorplans`	Grupurile și planurile de etaj ale dispozitivului
`permissions`	Permisiunea dumneavoastră pe dispozitiv (vedeți mai jos)

Valorile permissions:

Valoare	Permisiune
`1`	Citire
`2`	Scriere (controlul ieșirilor)
`3`	Administrator
`4`	Proprietar

Un dispozitiv: `get_device_info.php`

Parametru	Valoare
`serialno`	Numărul de serie

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

Răspuns: device (aceleași câmpuri ca în listă), messages. Acceptă și &definitions=1. Fără serialno răspunde cu HTTP 400. Fără acces la dispozitiv răspunde cu HTTP 403.

Starea curentă: `get_device_state.php`

Returnează măsurătorile curente ale unuia sau mai multor dispozitive. Corpul este 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"
  }
}

Pentru mai multe dispozitive, trimiteți o listă: {"serialno": ["e11:123", "e9:456"]}. Răspunsul este {"devices": [...], "count": 2}. Dacă starea nu este disponibilă, state este {"connected": false, "message": "Device state not available"}. Fără autentificare, răspunsul este HTTP 401 cu {"error": "Authentication required"}.

Definițiile familiilor

Definițiile vă spun ce măsurători, ieșiri și setări are fiecare familie. Nu necesită autentificare.

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

Răspunsul are families și readings. Cu &include_readings=false răspunsul nu are dicționarul readings. Fără family_id răspunsul are toate familiile.

Fiecare familie are:

Câmp	Conținut
`readings`	Codurile măsurătorilor în ordinea lor, de exemplu `["T", "GI", "GIC", "GI2", "GI2C"]`
`output_names`	Ieșirile în ordinea lor
`settings`	Setările familiei
`ping_period`	Intervalul keep-alive în secunde

Dicționarul readings dă eticheta, unitatea și conversia pentru fiecare cod de măsurătoare. De exemplu, măsurătoarea T are unitatea °C și conversia divide_by_100. Puteți vedea lista măsurătorilor și în pagina Dicționar de măsurători.

Valoarea 2147483648 înseamnă că măsurătoarea lipsește.

Timeout

Setați un timeout de aproximativ 30 de secunde la cererile dumneavoastră.

Consultați și

Chat cu suportul