225 lines
14 KiB
Markdown
225 lines
14 KiB
Markdown
---
|
|
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/<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. Сценариев/реле там нет.
|
|
|
|
**Семантика:** для составного параметра можно передать **часть** внутренних полей — остальные
|
|
сохранят прежние значения. Ответ содержит **только изменённые** параметры и их новые значения.
|
|
|
|
```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/<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)
|