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 для AI-асистентів
• Віртуальні пристрої