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.

Вход с e-mail: login.php

Параметър	Стойност
email	E-mail адресът на акаунта
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	Интервалът на сигнала за активност в секунди

Речникът readings дава етикета, единицата и преобразуването за всеки код на измерване. Например измерването T има единица °C и преобразуване divide_by_100. Можете да видите списъка с измервания и на страницата Речник на измерванията.

Стойността 2147483648 означава, че измерването липсва.

Време за изчакване

Задайте време за изчакване от около 30 секунди за Вашите заявки.

Вижте също

• Изтегляне на исторически данни
• Данни на живо (WebSocket)
• MCP за AI асистенти
• Виртуални устройства