REST API

Помоћу HTTP API-ја читате уређаје свог налога из свог програма. API види исте уређаје и има исте дозволе као ваш налог у апликацији.

Основе

Ставка	Вредност
Основни URL	https://api.hamsystems.eu
Формат захтева	POST са application/x-www-form-urlencoded, осим ако одељак каже другачије
Формат одговора	JSON
Серијски број	<family>:<number>, на пример e11:123. Први део је породица уређаја.

Већина одговора има поље messages. То је листа објеката {"text": "...", "type": "error"}. type је error, success или info.

Аутентификација

Постоје два начина:

Начин	Како га добијате	Трајање
API кључ (api_key)	Са странице Налог у апликацији	Не истиче. Један кључ по налогу.
Токен за приступ (access_token)	Из login.php или login_api.php	60 дана

Пошаљите API кључ на један од ових начина:

• Параметар api_key у телу POST захтева или у query string-у.
• Заглавље Authorization: Bearer-API YOUR_API_KEY.

Пошаљите токен за приступ на један од ових начина:

• Параметар access_token у телу POST захтева или у query string-у.
• Заглавље Authorization: Bearer YOUR_ACCESS_TOKEN.

Ако пошаљете оба, сервер користи API кључ.

Пажња

API кључ даје потпун приступ вашем налогу. Не стављајте га у код који ради у прегледачу или у јавно спремиште кода.

Креирање API кључа

1. Отворите Мени и додирните Налог.
2. У одељку API кључ додирните Генериши API кључ.
3. Потврдите поруку. Нови кључ поништава стари кључ.
4. Додирните кључ да га копирате. Апликација приказује Копирано.

Рачунар

Телефон

Да поништите кључ, направите нови кључ. Стари кључ одмах престаје да ради.

Крајње тачке

Провера кључа: check_api_key.php

Проверава API кључ.

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

Одговор: user, messages. Ако кључ није тачан, messages има грешку Api key not found.

Токен за приступ из кључа: login_api.php

Даје токен за приступ за API кључ. Користите га када алат прихвата само токен за приступ.

Параметар	Вредност
key	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": []
}

Ова крајња тачка има ограничење покушаја. После много неуспеха одговара Too many attempts, try again later.

Пријава имејлом: login.php

Параметар	Вредност
email	Имејл налога
password	Лозинка
timezone	Опционо. Временска зона, на пример Europe/Athens.

Одговор: access_token, user, messages. Ако је must_recaptcha једнако true, сервер тражи reCAPTCHA проверу. Тада користите API кључ.

Листа уређаја: get_user_devices.php

Враћа уређаје, групе, планове просторија и сцене налога.

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

Поља одговора: devices, groups, floorplans, scenes, messages. Са ?v=2&definitions=1 одговор има и поље definitions за породице ваших уређаја.

Сваки уређај има ова поља:

Поље	Садржај
serialno	Серијски број, на пример e11:123
name, icon	Име и иконица из апликације
mac	MAC адреса
device_server	Сервер уређаја. Потребан вам је за историју и за WebSocket.
latitude, longitude	Локација, ако је подешена
firmware_version	Верзија фирмвера
settings	Подешавања уређаја
groups, floorplans	Групе и планови просторија уређаја
permissions	Ваша дозвола на уређају (погледајте испод)

Вредности за permissions:

Вредност	Дозвола
1	Читање
2	Писање (управљање излазима)
3	Администратор
4	Власник

Један уређај: get_device_info.php

Параметар	Вредност
serialno	Серијски број

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

Одговор: device (иста поља као у листи), messages. Прихвата и &definitions=1. Без serialno одговара са HTTP 400. Без приступа уређају одговара са HTTP 403.

Тренутно стање: get_device_state.php

Враћа тренутна очитавања једног или више уређаја. Тело захтева је 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"
  }
}

За више уређаја пошаљите листу: {"serialno": ["e11:123", "e9:456"]}. Одговор је {"devices": [...], "count": 2}. Ако стање није доступно, state је {"connected": false, "message": "Device state not available"}. Без аутентификације одговор је HTTP 401 са {"error": "Authentication required"}.

Напомена

Вредности у readings су сирове. У примеру, T: 2082 значи 20.82 °C. Дефиниција породице каже како да конвертујете сваку вредност. Погледајте дефиниције породица испод.

Дефиниције породица

Дефиниције кажу која очитавања, излазе и подешавања има свака породица. Не захтевају аутентификацију.

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

Одговор има families и readings. Са &include_readings=false одговор нема речник readings. Без family_id одговор има све породице.

Свака породица има:

Поље	Садржај
readings	Кодови очитавања по редоследу, на пример ["T", "GI", "GIC", "GI2", "GI2C"]
output_names	Излази по редоследу
settings	Подешавања породице
ping_period	Интервал за keep-alive у секундама

Речник readings даје ознаку, јединицу и конверзију за сваки кôд очитавања. На пример, очитавање T има јединицу °C и конверзију divide_by_100. Листу очитавања видите и на страници Речник очитавања.

Вредност 2147483648 значи да очитавање недостаје.

Време чекања

Подесите време чекања (timeout) од око 30 секунди за своје захтеве.

Погледајте и

• Преузимање историјских података
• Подаци уживо (WebSocket)
• MCP за AI асистенте
• Виртуелни уређаји