--- aliases: - ZONT API - zont-online API - ZONT cloud API - ZONT update_device created: '2026-09-17' namespace: family related: - '[[family/how-to/zont-config-compiler]]' - '[[family/tech/zont-scenario-logic-11109]]' - '[[family/tech/zont-config-object-types]]' - '[[family/how-to/home-automation]]' tags: - family - tech - zont - api - reference title: "\U0001F310 ZONT Cloud API — что умеет и чего в нём нет" type: reference updated: '2026-09-17' --- # 🌐 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 конвертация | ```bash 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/ Header: X-ZONT-Client: (обязательный) Auth: Basic ИЛИ X-ZONT-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. Сценариев/реле там нет. **Семантика:** для составного параметра можно передать **часть** внутренних полей — остальные сохранят прежние значения. Ответ содержит **только изменённые** параметры и их новые значения. ```json // запрос {"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` — история (только чтение) ```json 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, на который переписать | ### Рекомендация (доложена Alex, решения пока нет) - **Конвертер не выкидывать** — он единственный путь к сценариям. Доделывать §5c (`blocks/if/then`, см. [[family/how-to/zont-config-compiler]]) имеет смысл. - **API-обвязка — отдельная задача на потом:** мониторинг реле/датчиков, графики из `load_data`, правка режимов отопления. **Дополняет** конвертер, не заменяет. - **Открытый вопрос Alex'у:** нужен ли онлайн-мониторинг ZONT в HA. От ответа зависит, браться ли за API-часть вообще. --- ## 7. Питфоллы | # | Питфолл | Как обойти | |---|---|---| | 1 | 🔴 Вся дока — **одна страница**; `/api/docs/` → **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)