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 или в строке запроса.
• Заголовок Authorization: Bearer-API YOUR_API_KEY.

Отправьте токен доступа одним из этих способов:

• Параметр access_token в теле POST или в строке запроса.
• Заголовок 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	Интервал keep-alive в секундах

Словарь readings даёт метку, единицу и преобразование для каждого кода показания. Например, у показания T единица °C и преобразование divide_by_100. Список показаний также есть на странице Словарь показаний.

Значение 2147483648 означает, что показания нет.

Тайм-аут

Задайте для запросов тайм-аут около 30 секунд.

См. также

• Загрузка исторических данных
• Данные в реальном времени (WebSocket)
• MCP для ИИ-помощников
• Виртуальные устройства