Files

T

Alexey Martemyanov 0290cca4bd [2026-09-17] eagle: family/how-to/zont-config-compiler.md family/tech/zont-api.md family/tech/zont-config-object-types.md family/tech/zont-scenario-logic-11109.md

2026-09-17 13:15:36 +06:00

14 KiB

Raw Blame History

aliases, created, namespace, related, tags, title, type, updated

aliases

created

namespace

🌐 ZONT Cloud API — что умеет и чего в нём нет

Исследовано 2026-09-17 по запросу Alex: «У зонта есть api и вероятно свой какой-то формат включая все датчики и автоматику. Изучай подробно вопрос… что нам для комфортного управления контроллером на самом деле надо. Доделывать конвертер или переделать все с 0.»

Итог одной строкой: облачный API ZONT не работает с конфигом (сценарии, реле, шаги, условия). Конвертер .txt ⇄ .yml — по-прежнему единственный путь к правке сценариев. API годится только для мониторинга и узкого набора настроек (отопление).

1. Локальная копия доки (в проекте)

Доки скачаны в проект, не в /tmp (указание Alex: «качай доки в папку в проекте а не в темп»):

Файл	Размер	Что это
`/Users/admin/Automation/HA-ZONT-Modbus/zont_api_docs/zont_api_docs.html`	250 KB	полная дока как есть (одна страница)
`…/zont_api_docs.txt`	99 KB / 3381 строка	читаемый текст, таблицы → `\|`
`…/convert.py`	—	воспроизводимая HTML→text конвертация

cd /Users/admin/Automation/HA-ZONT-Modbus/zont_api_docs
curl -s -L 'https://zont-online.ru/api/docs/' -o zont_api_docs.html   # обновить
python3 convert.py                                                     # → zont_api_docs.txt

📌 Вся дока — ОДНА страница. Отдельных URL вида /api/docs/update_device нет (404). Ссылки #update_device — это внутренние якоря. Не пытаться качать методы по отдельности.

2. Полный список методов API (всего 11)

Метод	Назначение	Пишет конфиг?
`get_authtoken`	получить токен (Basic auth → `X-ZONT-Token`)	—
`devices`	список устройств + Настройки; `load_io: true` → ещё и Состояния	—
`update_device`	изменение Настроек устройства	⚠️ узкий набор, см. §4
`set_io_port`	управление Состоянием: `guard-state`, `siren`, `engine-block`, `webasto`	—
`send_custom_command`	послать пользовательскую команду по `command_id`	—
`load_data`	история данных за период (типы: `temperature`, `events`, `z3k_*`…)	—
`raw_events`	история событий (обёртка над `load_data`)	—
`temperature` / `thermostat_work` / `custom_controls` / `ztc_state`	история / состояние	—
`generate_archive` / `download_generated_archive`	выгрузка архива	—
`add_device` / `delete_device`	добавить / удалить устройство	—

Формат запроса

POST https://my.zont.online/api/<method>
Header: X-ZONT-Client: <email>            (обязательный)
Auth:   Basic <login:password>  ИЛИ  X-ZONT-Token: <token>
Body:   JSON (предпочтительно) / form-encoded / GET-параметры
Ответ:  JSON, всегда поле "ok": true|false; при ошибке "error" + "error_ui"

Рекомендованный поток аутентификации: get_authtoken (с логином/паролем) → дальше по токену, пароль не хранить. При 403 токен мог быть отозван — перезапросить.

3. 🔴 Главный вывод: конфига в API НЕТ

Проверено фактом по локальной копии доки:

Что искали	Найдено в доке
слово `scenario`	0 раз
слово `relay`	1 раз
`z3k_config` (конфиг контроллера)	2 раза — только как ссылка для ID
метод для чтения/записи `z3k_config`	нет

Наши объекты конфига — сценарии (11), реле (14), шаги (46), условия (49), задержки (45) — в API не представлены вообще. Ни чтения, ни записи.

z3k_config упоминается лишь как источник числовых ID: в z3k_temperature «ключом является ID объекта из z3k_config», в z3k_boiler_adapter — «ID адаптера из z3k_config (например 4097, 4098)». То есть API ссылается на конфиг, но работать с ним не даёт.

⚠️ Это не «ещё не нашли метод» — это перебор всех 11 методов из оглавления доки. send_custom_command — не то: он шлёт заранее заданную в настроечной утилите команду по command_id.

4. Что `update_device` реально умеет

Единственный метод, который меняет Настройки. Доступные области (по разделам доки):

Раздел	Ключи настроек
Общие	`name`, `serial`, `timezone`
Беспроводная сеть	`balance` (`ussd`/`warning`/`limit`), `trusted_phones`, `gsm_roaming`
Управление отоплением (ZONT H)	`thermostat_mode`, `thermostat_mode_temps`, `thermostat_ext_mode`, `thermostat_ext_modes_config`, `tempschedule`, `thermometers`, `ot_*` (OpenTherm)
Пользовательские команды (ZTC-7xx, Mega SX)	`custom_controls` — не наш случай (H-2000 PRO)
Авто (ZTC)	`auto-ignition`, двери/капот/багажник

🔴 Для H-2000 PRO через API доступно практически только отопление — режимы, целевые температуры, расписание, параметры OpenTherm. Сценариев/реле там нет.

Семантика: для составного параметра можно передать часть внутренних полей — остальные сохранят прежние значения. Ответ содержит только изменённые параметры и их новые значения.

// запрос
{"device_id": 1580, "thermostat_mode_temps": {"comfort": 21}}
// ответ — изменилось только comfort, остальные вернулись как есть
{"ok": true, "thermostat_mode_temps": {"comfort": 21, "econom": 16, "idle": 5, "full_off": false}}

5. `load_data` — история (только чтение)

POST https://my.zont.online/api/load_data
{"requests": [
  {"device_id": 1580, "data_types": ["temperature", "events"],
   "mintime": 1495011600, "maxtime": 1495022400}
]}

Ответ: responses[] в том же порядке, что requests, каждый с полями по имени типа данных. Времена — unix time (секунды, UTC). Вложенные параметры → только Content-Type: application/json.

Формат значений — Delta-time Array (DTA): массив пар [delta_секунд, значение], где первая метка абсолютная, последующие — отрицательные смещения назад во времени.

Типы данных (data_types), релевантные нашему контуру:

Тип	Для чего	Модели
`temperature`	показания температурных датчиков	—
`events`	события	—
`z3k_temperature`	история датчиков, ключ = ID объекта из `z3k_config`	H-2000+, H-2000 PRO, Climatic, H1V.02, SMART NEW
`z3k_radio_sensor`	радиодатчики	по аналогии
`z3k_heating_circuit`	контуры отопления	по аналогии
`z3k_web_element`	пользовательские кнопки	по аналогии
`z3k_boiler_adapter`	котёл по OpenTherm / EMS / BSB — шаг до 1 мин	H-2000+ / PRO / PRO.V2
`custom_controls`	пользовательские статусы (битовая маска)	Mega SX, H-1000, ZTC
`ztc_state`	питание, GSM, Wi-Fi	—

z3k_boiler_adapter даёт те же ряды, что графики в личном кабинете: s (флаги состояния ch/dhw/fl/cl/ch2/di/f), cs/cs2 (расчётная t теплоносителя), bt (фактическая), rwt (обратка), dt (ГВС), ot (улица), rml (модуляция горелки), wp (давление), ff (авария {c, f}), rp/rt/rors/db/b (уставки) и др.

custom_controls — битовая маска: значение — целое, каждый бит = состояние статуса с этим id.

[[1498710120, 0], [-86, 6], [-5, 2]]
→ все статусы выкл → через 86 с включились статусы 1 и 2 (6 = 110₂) → ещё через 5 с статус 2 выключился

6. Ответ на вопрос «доделывать или переделать с 0»

Переделать с 0 — не на что. API не предоставляет доступа к сценариям/реле, поэтому «переписать управление на API» технически невозможно. Переписать можно было бы только мониторинг, и это дополнение, а не замена.

Путь	Что даёт	Ограничение
1. Конвертер `.txt ⇄ .yml` (текущий)	правка сценариев, реле, датчиков, Modbus	загрузка в контроллер руками
2. API-обвязка (дополнение)	онлайн-состояния (`devices?load_io=true`), история (`load_data`), отопление (`update_device`), сирена/охрана (`set_io_port`)	сценарии недоступны
3. «Переделать с 0»	❌ не существует API, на который переписать

7. Питфоллы

#	Питфолл	Как обойти
1	🔴 Вся дока — одна страница; `/api/docs/<method>` → 404	Качать только `https://zont-online.ru/api/docs/` целиком
2	🔴 `send_custom_command` всегда возвращает `ok: true`, даже если связи нет или отправка не удалась	Не считать `ok` подтверждением доставки
3	`load_data` принимает вложенные параметры → только JSON, не form-encoded	`Content-Type: application/json` обязателен
4	`mintime`/`maxtime` — unix time в секундах, UTC	Не путать с миллисекундами
5	`custom_controls` — битовая маска, не массив состояний	Разбирать побитово; биты считаются с нуля от младшего
6	DTA — вторая и последующие метки отрицательные (смещения назад)	Не читать их как абсолютное время
7	`update_device` при `403` — токен мог быть отозван	Перезапросить `get_authtoken`
8	Дока обновляется, часть функций может отсутствовать	При нехватке метода — писать на `admin@zont.online`

8. Связанные заметки

family/how-to/zont-config-compiler — конвертеры .txt ⇄ .yml; §5c — план переработки YAML
family/tech/zont-scenario-logic-11109 — структура сценариев 11/46/49/45
family/tech/zont-config-object-types — таблица типов объектов конфига
family/how-to/home-automation — контур автоматизации, ZONT, Modbus (§6)

14 KiB Raw Blame History Unescape Escape