RESTful документация

Thermozone AB4 — руководство по интеграции через REST API

Руководство для разработчиков внешних систем (BMS, шлюзы, мобильные приложения, системы диспетчеризации), которые подключаются к контроллеру отопления Thermozone AB4 по локальной сети.

Содержание

1. Назначение и область применения
2. Совместимость и версионирование
3. Подготовка контроллера
4. Подключение к контроллеру
5. Авторизация
6. Протокол обмена
7. Объектная модель
8. Чтение состояния
9. Справочник данных
10. Управление
11. Ошибки и статусы
12. Сценарии интеграции
13. Ограничения и требования
14. Чек-лист приёмки интеграции
15. Приложение A. Быстрый старт
16. Приложение B. Совместимый интерфейс /apijson

1. Назначение и область применения

Контроллер предоставляет локальный HTTP/JSON-интерфейс, позволяющий внешней системе:

• получать состояние отопления: температуры помещений и полов, уставки, текущую мощность нагрева, режимы работы;
• получать данные датчиков: температуры, влажность, состояние выходов;
• получать данные котла при управлении по OpenTherm: температуры, модуляцию, давление, ошибки, уставки;
• задавать уставки и режимы отдельных устройств (зон) и групп (помещений);
• переключать системные режимы: летний, охлаждение, вентиляция;
• управлять свободными выходами контроллера;
• управлять котлом через OpenTherm.

Интерфейс предназначен для работы внутри локальной сети. Доступ через интернет напрямую не предусмотрен: для удалённого подключения используйте VPN или обратный прокси.

Настройка контроллера (создание устройств, привязка датчиков, конфигурация котла) выполняется монтажником через веб-интерфейс устройства. Внешняя система работает с уже настроенным контроллером: читает конфигурацию и управляет ею в пределах, разрешённых настройками.

Сводка интерфейсов

2. Совместимость и версионирование

• Поле "v" в корне каждого ответа — версия контракта. Текущая версия — 2. Несовместимые изменения сопровождаются увеличением этого поля.
• Набор полей может дополняться без смены v. Внешняя система обязана игнорировать неизвестные поля и объекты и не должна падать при их появлении.
• Поля, описанные в этом документе, считаются стабильными. Поля, которых нет в документе, стабильными не являются: их наличие, имена и смысл могут меняться без предупреждения.
• Версия прошивки контроллера доступна в st.sys.fw (строка формата "2.0131"). Используйте её для журналирования и для выбора ветки поведения при необходимости.

3. Подготовка контроллера

Перед подключением внешней системы контроллер должен быть введён в эксплуатацию:

1. Контроллер подключён к сети и имеет постоянный адрес (статический IP или резервирование по DHCP), а также, при поддержке сети, имя вида имя-устройства.local.
2. Созданы и настроены устройства (зоны): назначены датчики, выходы, режимы работы.
3. Созданы группы (помещения) и при необходимости включено «управление группой».
4. Задан ключ API на странице основных настроек контроллера (см. раздел 5).
5. При использовании OpenTherm модуль включён и связь с котлом установлена.

Особенности, влияющие на интеграцию:

• Устройства в режиме «Отключено» присутствуют в конфигурации, но отсутствуют в состоянии.
• Устройство может быть ведомым (SLAVE): оно исполняет запрос других зон и не имеет собственной уставки.
• Устройство может находиться под управлением группы: прямые команды такому устройству отклоняются, управление выполняется на уровне группы.

4. Подключение к контроллеру

Примеры базовых адресов:

http://192.168.1.50
http://iohouse-kitchen.local

Поддерживается Connection: keep-alive: одну сессию можно переиспользовать для серии запросов. Если клиент не поддерживает постоянные соединения, каждый запрос выполняется отдельно — это допустимо, но менее эффективно.

5. Авторизация

Ключ доступа задаётся на странице основных настроек контроллера в поле «API» и передаётся в каждом запросе параметром apikey_rest. Допустимая длина ключа — до 63 символов; рекомендуется не менее 16 символов, буквы и цифры.

Требования:

• Если поле ключа на контроллере пустое, защита команд не действует. Перед подключением контроллера к общей сети ключ должен быть задан.
• Чтение через /api_climate ключом не защищено и рассчитано на доверенный сегмент сети. Не публикуйте контроллер в интернет и не размещайте его в гостевом сегменте.
• Ключ передаётся в строке запроса, поэтому попадает в журналы прокси и серверов. Не журналируйте полные URL с ключом и не передавайте их во внешние сервисы.

6. Протокол обмена

6.1. Методы и параметры

Команды принимаются методами GET и POST (равнозначно). Параметры передаются в строке запроса либо телом application/x-www-form-urlencoded. Для управляющих запросов рекомендуется POST с телом — так ключ и значения не попадают в журналы доступа.

6.2. Формат ответа

Ответ приходит целиком: заголовки с Content-Length, затем JSON-тело. Ответ всегда является корректным JSON, включая ответы с ошибками.

6.3. Кросс-доменные запросы

Заголовки CORS не отдаются. Запрос из браузера со стороннего домена не будет принят. Интеграция должна выполняться на стороне сервера, шлюза или мобильного приложения.

6.4. Типы значений

• Флаги могут приходить как JSON-булевы true/false или как числа 0/1. Трактуйте true и 1 как «включено», false и 0 — как «выключено»; не сравнивайте флаги строго с числом.
• Температуры зон — °C с точностью 0.1.
• Температуры датчиков — °C с точностью 0.01.
• Влажность — % с точностью 0.01.
• Мощность и проценты — 0…100 с точностью 0.1.
• Время работы контроллера: st.sys.upm — целые минуты с момента запуска на отдельном 64-битном таймере (переполнение счётчика st.ts его не сбрасывает); st.sys.up — совместимое поле в миллисекундах, всегда кратно 60 000. st.ts — миллисекунды с момента запуска, только как метка снимка (см. 9.2).
• Строки — UTF-8; имена задаёт пользователь, они могут быть пустыми.

6.5. Отсутствие значения

Если измерение недостоверно (датчик не отвечает, значение ещё не получено), соответствующее поле отсутствует в ответе. Не подставляйте вместо него 0 и не считайте нулём температуру: это приведёт к ложным решениям.

6.6. Частота опроса

Контроллер обслуживает запросы одним потоком. Рекомендуемый интервал опроса состояния — 5 секунд и более; период внутреннего регулирования также равен 5 секундам, поэтому более частый опрос не даёт новой информации. Одновременная работа более двух опрашивающих клиентов замедляет ответы всем.

7. Объектная модель

Контроллер описывает систему как группы (помещения) и входящие в них устройства (зоны).

Ёмкости контроллера:

Все команды адресуются по unit_id или group_id. Числовых индексов зон в интерфейсе нет — не используйте порядок элементов массива как идентификатор.

7.1. Конфигурация и состояние

Ответ разделён на две части:

• cfg — конфигурация: группы, устройства, режимы, названия, выходы, датчики. Меняется редко (при настройке контроллера);
• st — состояние: температуры, уставки, мощность, режимы, показания датчиков, котёл. Меняется постоянно.

cfg_hash — 16 hex-символов, контрольная сумма конфигурации. Внешняя система хранит последнее полученное значение и передаёт его при опросе, чтобы не получать конфигурацию каждый раз.

7.2. Цикл синхронизации

1. Первый запрос — получить cfg и st, запомнить cfg_hash.
2. Далее опрашивать только состояние, передавая cfg_hash.
3. Если в ответе cfg_changed = 1, конфигурация изменилась: перечитать её и заново построить карту устройств и групп.

cfg_changed = 1 возвращается только при переданном cfg_hash, который не совпал с текущим. Если cfg_hash не передан, cfg_changed всегда 0.

8. Чтение состояния

8.1. Основной запрос

GET /api_climate?scope=state&cfg_hash=<известный хеш>

Это рекомендуемый способ чтения. Ключ не требуется.

Фильтр по устройствам: если передан хотя бы один параметр, имя которого совпадает с unit_id и значение равно 1, в ответ попадут только эти устройства. Если фильтра нет — все работающие устройства.

Примеры:

GET /api_climate
GET /api_climate?scope=config
GET /api_climate?scope=state&cfg_hash=1a2b3c4d5e6f7081
GET /api_climate?scope=state&cfg_hash=1a2b3c4d5e6f7081&u_slot_0=1&u_slot_3=1

8.2. Особенности ответа

• Ответ может содержать дополнительные поля, не описанные в этом руководстве. Игнорируйте их и не используйте в логике (см. раздел 2).
• В st.sys присутствуют fw (версия прошивки), upd (доступно обновление), uv (версия обновления при upd) и o — массив состояний выходов out1…out10.
• Блок st.ot присутствует в любом ответе, содержащем st: при выключенном OpenTherm он равен {"a": false}. В ответе scope=config блока st нет вовсе.

8.3. Общий вид ответа

{
  "v": 2,
  "cfg_hash": "1a2b3c4d5e6f7081",
  "cfg_changed": 0,
  "cfg": { },
  "st": { }
}

9. Справочник данных

9.1. cfg — конфигурация

cfg.cc — автоматика климата

cfg.vent — вентиляция по CO₂

9.1.1. cfg.groups[] — группы

9.1.2. Маска gcap

9.1.3. Идентификаторы датчиков в конфигурации

Ссылки на датчики в полях cc.out, cc.home, groups[].os, groups[].co2 имеют вид <источник>:<слот>:

"out": "ds:0"     // первый проводной датчик
"co2": "mqtt:1"   // второй MQTT-датчик

Нумерация слотов начинается с нуля. Это не то же самое, что идентификаторы ds1…ds8 в cfg.sens и st.sens, где нумерация начинается с единицы.

9.1.4. cfg.groups[].d[] — устройство

9.1.5. Режимы устройства (m)

Режим влияет на набор доступных команд:

• режим 1 — устройство отсутствует в состоянии, команды не применяются;
• режим 2 — уставка не действует, мощность задаётся командой mpwm;
• ведомые устройства (признак sl, например режимы 17, 18, 21) не имеют собственной уставки: команды tt, aw, ec, nt к ним не применяются.

9.1.6. cfg.out[] — выходы

9.1.7. cfg.sens — датчики

В конфигурацию попадают только назначенные датчики.

9.2. st — состояние

st — снимок состояния на момент ответа. Даты, времени суток и часового пояса в контракте нет: контроллер ведёт только счёт от своего запуска.

Все счётчики работы сбрасываются при перезапуске контроллера. Питание пропало — отсчёт начинается заново; сохранять отметку запуска нужно на стороне интеграции.

st.ts — метка снимка

Миллисекунды с момента запуска контроллера. Счётчик 32-битный: он обнуляется при перезапуске и переполняется примерно через 49.7 суток. Это не время суток и не надёжная мера длительности.

Как использовать:

• сравнивайте st.ts только внутри одного запуска — как признак того, что ответы относятся к одному и тому же сеансу работы;
• не вычисляйте длительности как разность st.ts двух ответов: после перезапуска или переполнения разность станет отрицательной или огромной;
• для вопроса «сколько работает контроллер» берите st.sys.upm;
• метку реального времени ставьте на своей стороне в момент приёма ответа.

st.sys — общесистемные сведения

upm и up — одно и то же значение в разных единицах, они передаются вместе и меняются раз в минуту. Внутри минуты оба поля не изменяются, поэтому по ним нельзя отслеживать короткие интервалы: для этого используйте собственные часы клиента.

В прошивках, где поля upm ещё нет, присутствует только up в миллисекундах — читайте его и не полагайтесь на отсутствующие поля.

9.2.1. st.groups[] — группа в состоянии

Объекты c, f, h присутствуют только при наличии в группе соответствующего участника. Группы, в которых нет ни одного работающего устройства, в st.groups не попадают — их описание остаётся в cfg.

Объект v (вентиляция по CO₂):

Поля объектов группы:

Смысл полей совпадает с полями устройства (tp, t, tt, pwm, br, hx, aw, ec, nt, p, hc). Особенности:

• в объекте f поле tt — допустимая (предельная) температура пола, ov — перегрев пола, hx всегда 1;
• в объекте h значения t и tt — проценты влажности, act — влажность регулируется в текущий момент.

9.2.2. st.groups[].d[] — устройство в состоянии

Различие p и tp:

• tp — требование работы, то есть то, что задано пользователем или группой;
• p — фактическая работа в данный момент.

Требование может быть включено, а фактическая работа отсутствовать: например, при достигнутой температуре, при защите по перегреву пола, при открытом окне или при блокировке датчика.

Различие br и hx:

• br — нагреватель физически активен;
• hx — вид работы, если он определён.

pwm — текущая мощность в процентах и не заменяет br: знак мощности не определяет направление, а нулевая мощность не доказывает, что нагреватель выключен (инерция, задержки).

9.2.3. st.out.d[] — выходы

9.2.4. st.sens — датчики

Если t или h отсутствует — значение недостоверно. Значение e = 1 означает ошибку чтения конкретного датчика.

9.3. st.ot — данные котла (OpenTherm)

Блок присутствует в любом ответе, содержащем st. Если модуль выключен, блок равен {"a": false}. В ответе scope=config блока st нет, поэтому нет и st.ot.

9.3.1. Режим и разрешения

9.3.2. Уставки и запросы

Для отображения пользователю используйте etgt и edhwtgt: при автоматическом управлении tgt и dhwtgt — лишь исходные значения настроек.

9.3.3. Состояние котла

9.3.4. Измерения и их достоверность

Значение достоверно только при соответствующем флаге; иначе не используйте его.

Никогда не подставляйте ноль вместо недостоверного измерения.

9.3.5. Пределы и характеристики

Перед записью уставки через API проверяйте cbv/cbmin/cbmax и dhwbv/dhwbmin/dhwbmax.

9.3.6. Расширенная телеметрия

st.ot.ts — массив дополнительных измерений котла:

[
  { "id": 25, "valid": true, "v": 1.85 },
  { "id": 116, "valid": true, "hi": 12, "lo": 240 },
  { "id": 77, "valid": false }
]

Невалидная запись не содержит v или hi/lo. Это не системная метка времени st.ts.

10. Управление

Все команды выполняются через один адрес:

POST /apiaction?apikey_rest=<ключ>

Параметры передаются в строке запроса или телом формы. Ключ обязателен.

Общие правила:

• одна команда устройства адресуется по uid (можно указать несколько раз) или uids=<id1>,<id2>,...;
• одна команда группы адресуется по gid и gk;
• команды разных типов можно объединять в одном запросе, кроме команд OpenTherm: они завершают обработку запроса;
• значения проверяются; если команда отклонена, в ответе будет ok: 0 и код в err;
• после команды всегда читайте фактическое состояние из st в ответе.

10.1. Устройство (зона)

Режимы нагревателя БКН (bhm):

Примеры:

POST /apiaction?apikey_rest=SECRET&uid=u_slot_0&tt=23.5
POST /apiaction?apikey_rest=SECRET&uid=u_slot_0&p=0
POST /apiaction?apikey_rest=SECRET&uid=u_slot_0&uid=u_slot_3&p=0
POST /apiaction?apikey_rest=SECRET&uids=u_slot_0,u_slot_3&nt=1
POST /apiaction?apikey_rest=SECRET&uid=u_slot_0&bhe=1&bhm=6

Что означает «команда не применена»:

Уставка tt автоматически ограничивается допустимым диапазоном, заданным при настройке устройства. Фактическое принятое значение читайте в st.groups[].d[].tt.

Примечания к нагревателю БКН:

• bhe/bhm применимы только к БКН, который не является ведомым;
• bhe=0 дополнительно переводит режим нагревателя в «не используется» (1);
• параметры сохраняются в настройках устройства и действуют после перезагрузки.

10.2. Группа (помещение)

Смысл tt зависит от сущности:

POST /apiaction?apikey_rest=SECRET&gid=g_1A2B3C&gk=c&tt=23.0
POST /apiaction?apikey_rest=SECRET&gid=g_1A2B3C&gk=c&p=0
POST /apiaction?apikey_rest=SECRET&gid=g_1A2B3C&gk=c&aw=1
POST /apiaction?apikey_rest=SECRET&gid=g_1A2B3C&gk=f&tt=32
POST /apiaction?apikey_rest=SECRET&gid=g_1A2B3C&gk=h&p=1&tt=55

Требования:

• у группы включено «управление группой» (cfg.groups[].gc = 1);
• в маске gcap установлен бит нужной сущности.

Иначе команда отклоняется с err: "glock" (управление группой выключено) или err: "gkind" (в группе нет такой сущности).

Для группы с включённым управлением не отправляйте прямые команды дочерним устройствам (gl = 1) — контроллер их отклонит.

10.3. Системные режимы

POST /apiaction?apikey_rest=SECRET&sm=1
POST /apiaction?apikey_rest=SECRET&cm=1
POST /apiaction?apikey_rest=SECRET&vm=0

Если охлаждение или вентиляция запрещены в настройках контроллера (st.sys.ce = false или st.sys.ve = false), команда не изменит состояние.

10.4. Ручное управление выходом

POST /apiaction?apikey_rest=SECRET&oid=out9&ov=1

Выход, закреплённый за устройством, отклоняется с err: "obusy". Перед ручным управлением проверьте st.out.d[].b.

10.5. Котёл (OpenTherm)

Правила:

• uid не требуется;
• запрос с параметрами OpenTherm завершает обработку: не смешивайте его с командами устройств, групп и системных режимов;
• нельзя одновременно передавать ot_ch_mode/ot_dhw_mode/ot_dhw_push и ot_ch/ot_dhw/ot_ch_tt/ot_dhw_tt;
• уставки проверяются по пределам котла и применяются только целиком;
• при автоматическом управлении уставку формирует контроллер: смотрите etgt/edhwtgt.

POST /apiaction?apikey_rest=SECRET&ot_ch=1
POST /apiaction?apikey_rest=SECRET&ot_ch_tt=55
POST /apiaction?apikey_rest=SECRET&ot_dhw_tt=48
POST /apiaction?apikey_rest=SECRET&ot_ch_mode=2&ot_dhw_mode=1

10.6. Ответ на команду

{
  "v": 2,
  "ok": 1,
  "cfg_hash": "1a2b3c4d5e6f7081",
  "cfg_changed": 0,
  "st": {
    "ts": 1234567,
    "sys": {
      "upm": 4312,
      "up": 258720000
    },
    "groups": [ ],
    "out": { "d": [ ] },
    "sens": { "ds": [ ], "dht": [ ] },
    "ot": { "a": false }
  }
}

В st.sys приходят только поля, которые контроллер передаёт в ответе на команду; набор может быть уже, чем в /api_climate. Наличие upm проверяйте по ответу, а не по этому примеру.

Важно: st в ответе на команду неполный. Он содержит только те устройства, которых коснулась команда. Если команда адресована системе, выходу или котлу, массив st.groups будет пустым. Для полного состояния используйте /api_climate.

11. Ошибки и статусы

11.1. HTTP-статусы

11.2. Коды err

Рекомендуемая обработка: показывать пользователю понятное сообщение для auth, glock, ot_unavailable; для noop — не считать это ошибкой, а перечитать состояние; для json_overflow и testing_active — повторить запрос с паузой.

12. Сценарии интеграции

12.1. Первый запуск и построение карты

1. GET /api_climate?scope=full
2. Проверить, что "v" = 2.
3. Построить карту:
   - groups[]: id, имя, gc, gcap
   - groups[].d[]: id, имя, режим m, тип t, признаки sl и gl, класс cap
   - out[]: id и имя
   - sens: ds[] и dht[]
4. Сохранить cfg_hash.

12.2. Циклический опрос

каждые 5 секунд:
  GET /api_climate?scope=state&cfg_hash=<сохранённый хеш>

  если ответ не получен или получен 503 → подождать 5–10 с и повторить
  если cfg_changed = 1 → перечитать конфигурацию (GET /api_climate?scope=config)

12.3. Изменение уставки помещения

1. Найти unit_id нужного устройства в карте.
2. POST /apiaction?apikey_rest=<ключ>&uid=<unit_id>&tt=23.5
3. Проверить ok.
4. Взять фактическую уставку из st.groups[].d[].tt ответа
   или из ближайшего опроса состояния.

Если в ответе ok: 0 с err: "glock" — устройство управляется группой, отправьте команду группе (gid + gk=c).

12.4. Режим «Не дома» для нескольких помещений

POST /apiaction?apikey_rest=<ключ>&uids=u_slot_0,u_slot_3&aw=1

Режим «Не дома» и ночной режим меняют целевую температуру, но не снимают требование работы. Чтобы полностью отключить отопление, дополнительно передайте p=0.

12.5. Чтение датчиков

• температуры помещений — st.groups[].d[].t;
• температура пола — st.groups[].d[].ft;
• проводные датчики — st.sens.ds[];
• температура и влажность DHT — st.sens.dht[].

Отсутствие t/h означает недостоверное значение.

12.6. Управление помещением как единым объектом

POST /apiaction?apikey_rest=<ключ>&gid=<group_id>&gk=c&tt=23.0
POST /apiaction?apikey_rest=<ключ>&gid=<group_id>&gk=c&p=0

Используйте этот способ, если в конфигурации у группы gc = 1. Дочерние устройства такой группы имеют gl = 1; прямые команды им не отправляйте.

12.7. Управление котлом

1. Прочитать st.ot, проверить a = true, c = true.
2. При необходимости изменить разрешения: ot_ch, ot_dhw.
3. Для смены уставки проверить cbmin/cbmax (или dhwbmin/dhwbmax).
4. POST команду с ot_ch_tt (или ot_dhw_tt).
5. Перечитать st.ot: etgt (edhwtgt) — фактическая уставка.

13. Ограничения и требования

1. Локальная сеть. Интерфейс не использует TLS. Не публикуйте контроллер в интернет; для удалённого доступа применяйте VPN или обратный прокси.
2. Один поток. Контроллер обрабатывает запросы последовательно. Держите один клиент на контроллер и интервал опроса не менее 5 секунд.
3. Таймауты. Устанавливайте таймаут запроса 10 секунд и корректно обрабатывайте отсутствие ответа: не наращивайте частоту опроса при ошибках.
4. Ресурсы. При нехватке памяти контроллер отвечает 503 с json_overflow. Это временная ситуация: повторите запрос позже.
5. Ключ. Ключ передаётся в URL. Не журналируйте полные URL и не показывайте ключ в интерфейсах. При пустом ключе в настройках защита команд не работает.
6. Чтение без ключа. /api_climate не требует ключа; ограничьте сетевой доступ к контроллеру на уровне инфраструктуры.
7. Идентификаторы. Не используйте порядок элементов массива и числовые индексы как идентификаторы. Используйте unit_id и group_id.
8. Не кэшируйте конфигурацию бессрочно. Всегда обрабатывайте cfg_changed.
9. Не подставляйте нули. Отсутствующее измерение — недостоверно.
10. Не смешивайте команды. OpenTherm-команды выполняются отдельным запросом.
11. Ограничения конфигурации. Не более 11 устройств, 8 групп, 10 выходов, 8 проводных датчиков и 2 каналов DHT; часть из них может быть занята.
12. Сервисные режимы. Во время проверки подключений команды отклоняются (HTTP 409). Внешняя система должна это корректно переживать и повторять попытку позже.

14. Чек-лист приёмки интеграции

• GET /api_climate?scope=full возвращает "v": 2 и заполненные cfg и st.
• Карта устройств и групп построена по unit_id и group_id.
• Циклический опрос идёт с интервалом не менее 5 секунд.
• Обрабатывается cfg_changed = 1 с повторным чтением конфигурации.
• Команда уставки возвращает ok: 1, а новое значение подтверждается в tt.
• Обрабатываются gl = 1, tl = 1, sl = true — прямые команды в этих случаях не отправляются или их отказ корректно показывается пользователю.
• Отсутствие t/h не приводит к подстановке нуля.
• Обрабатываются коды err и HTTP-статусы 401, 409, 503.
• Ключ не попадает в журналы и в клиентские интерфейсы.
• Контроллер доступен только из доверенного сегмента сети.
• Проверена работа при перезагрузке контроллера (повторная синхронизация без ошибок).

Приложение A. Быстрый старт

Проверка доступности и версии контракта:

curl -s "http://192.168.1.50/api_climate" | head -c 200

Чтение конфигурации:

curl -s "http://192.168.1.50/api_climate?scope=config"

Чтение состояния:

curl -s "http://192.168.1.50/api_climate?scope=state&cfg_hash=1a2b3c4d5e6f7081"

Чтение одного устройства:

curl -s "http://192.168.1.50/api_climate?scope=state&u_slot_0=1"

Установка уставки:

curl -s -X POST "http://192.168.1.50/apiaction" \
  -d "apikey_rest=SECRET&uid=u_slot_0&tt=23.5"

Отключение отопления помещения:

curl -s -X POST "http://192.168.1.50/apiaction" \
  -d "apikey_rest=SECRET&uid=u_slot_0&p=0"

Включение летнего режима:

curl -s -X POST "http://192.168.1.50/apiaction" \
  -d "apikey_rest=SECRET&sm=1"

Приложение B. Совместимый интерфейс /apijson

Интерфейс сохранён для совместимости с ранее выполненными интеграциями. Для новых проектов используйте /api_climate для чтения и /apiaction для управления.

B.1. Чтение

GET /apijson?apikey_rest=<ключ>&scope=full
GET /apijson?apikey_rest=<ключ>&scope=config
GET /apijson?apikey_rest=<ключ>&scope=state&cfg_hash=<хеш>

Параметры scope, cfg, cfg_hash работают так же, как в /api_climate. Отличия:

• ключ обязателен;
• фильтр по unit_id недоступен — возвращаются все устройства;
• в st.sys нет полей fw, upd, uv, o;
• блок st.ot отсутствует.

B.2. Команды

Команды адресуются именем параметра, построенным из unit_id:

GET /apijson?apikey_rest=SECRET&u_slot_0_target_temp=23.5
GET /apijson?apikey_rest=SECRET&u_slot_0_power=0&summermode=1

Ответ на команду — полный снимок конфигурации и состояния (как scope=full), без st.ot. Из кодов раздела 11 для этого интерфейса актуальны auth (HTTP 401 с телом {"ok":0,"err":"auth"}), testing_active (HTTP 409) и json_overflow (HTTP 503).

B.3. Ограничения

• Прямые команды устройствам, управляемым группой (gl = 1), не применяются.
• Во время сервисного режима проверки подключений команды отклоняются с HTTP 409.
• Интерфейс не развивается: новые возможности появляются только в /apiaction и /api_climate.