+ 
+ Введение
+Система ZONT предоставляет API для получения информации +о состоянии устройств ZONT и Mega SX, а также для управления ими через внешние приложения и сайты.
+ +Все функции, доступные в веб-интерфейсе личного кабинета, доступны и +через API, что позволяет реализовать полноценную интеграцию с системой.
+ +++Обратите внимание: документация API находится в процессе обновления. +Если вы не нашли необходимую функцию — свяжитесь с нами, +и мы постараемся помочь или дополнить описание.
+
Облегчённое API
+Если вам не требуется вся полнота возможностей, рекомендуем воспользоваться +облегчённым API — оно предназначено +для базового взаимодействия с приборами и может быть удобным решением для быстрых интеграций.
+Примеры
# $ pip install requests
+
+import requests
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+В правой части страницы вы найдёте готовые работающие примеры кода на разных языках, +которые делают соответствующие запросы к API. Язык примеров можно переключить +с помощью кнопок справа вверху.
+ +-
+
- Примеры на Python используют библиотеку requests +
- Примеры на PHP используют библиотеку Requests for PHP +
Формат запросов
POST https://my.zont.online/api/set_io_port HTTP/1.1
+Host: zont-online.ru
+Content-Type: application/json
+Content-Length: 88
+Authorization: Basic ZWxvbjptYXJzNGV2ZXI=
+X-ZONT-Client: elon@tesla.com
+
+{
+ "device_id": 1209,
+ "portname": "siren",
+ "type": "bool",
+ "value": true
+}
+Обращения к API производятся с помощью POST-запросов на адрес https://my.zont.online/api/method, где method — названия метода API. Некоторые методы вызываются с помощью метода GET, это оговаривается отдельно в описании этих методов.
В каждом запросе должен быть указан заголовок X-ZONT-Client. Укажите в этом заголовке ваш e-mail или иной контакт, по которому мы сможем связаться с вами в случае планируемых изменений в API.
Параметры запроса передаются одним из способов:
+ +-
+
- В теле запроса в формате JSON. Заголовок
Content-Typeпри этом должен быть равенapplication/json. Этот способ является предпочтительным.
+ - В теле запроса в формате
имя1=значение1&имя2=значение2. Это стандартный формат передачи параметров в POST-запросах. ЗаголовокContent-Typeпри этом должен быть равенapplication/x-www-form-urlencoded. Такой способ передачи параметров может использоваться только в тех случаях, когда параметры простые, без вложенности.
+ - В случае GET-запроса параметры передаются в URL, например:
https://my.zont.online/api/method?arg1=value1&arg2=value2.
+
Результат запроса
{
+ "ok": false,
+ "error": "no_such_device",
+ "error_ui": "Устройство не найдено"
+}
+Если не оговорено иное, сервер отвечает на запрос результатом в формате JSON.
+В возвращаемом объекте всегда присутствует поле "ok", которое равно true в случае успеха или false в случае
+ошибки. Если поле "ok" равно false, то в ответе также будут присутствовать поля "error" с кодом ошибки
+и "error_ui" с её описанием на русском языке. "error_ui" может содержать либо строку, либо массив строк если
+возникло несколько ошибок.
Аутентификация
+Большинство запросов к API требуют аутентификации. В данный момент поддерживается два метода аутентификации: +с помощью пароля, и с помощью аутентификационного токена.
+ +Предпочтительная схема взаимодействия с API выглядит так:
+ +-
+
- Получить аутентификационный токен с помощью метода
get_authtoken. Этот запрос подтвердить +логином и паролем пользователя.
+ - Дальнейшие запросы аутентифицировать полученным токеном, а пароль пользователя больше не использовать и не хранить. +
- Если запрос к API провалился с кодом 403, то возможно токен был отозван пользователем. В этом случае
+нужно предложить пользователю снова ввести логин и пароль, получить новый токен с помощью
get_authtoken+и в дальнешем использовать его.
+
Аутентификация паролем
curl 'https://my.zont.online/api/get_authtoken' \
+ -u 'login:password' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"client_name": "My cool app"}'
+import requests
+
+result = requests.post(
+ 'https://my.zont.online/api/get_authtoken',
+ auth=('login', 'password'),
+ headers={'X-ZONT-Client': 'your@email.com'},
+ json={"client_name": "My cool app"}
+).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$response = Requests::post(
+ 'https://my.zont.online/api/get_authtoken',
+ ['X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json'],
+ json_encode(['client_name' => 'My cool app']),
+ ['auth' => ['login', 'password']]
+);
+++ +Не забудьте заменить login, password на логин и пароль пользователя, your@email.com на email разработчика, а "My cool app" — на название вашего приложения
+
Просто укажите логин и пароль пользователя с помощью HTTP Basic Authentication. Это можно сделать либо встроенными средствами вашей http-библиотеки, либо указав заголовок:
+ +Authorization: Basic XXX
где XXX — это строка логин:пароль, закодированная в Base64.
Аутентификация с помощью токена
curl 'https://my.zont.online/api/some_method' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'X-ZONT-Token: xxxxxxxxxxxxxxxxxx'
+import requests
+
+result = requests.post(
+ 'https://my.zont.online/api/some_method',
+ headers={'X-ZONT-Client': 'your@email.com',
+ 'X-ZONT-Token': 'xxxxxxxxx'}
+).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$response = Requests::post(
+ 'https://my.zont.online/api/some_method',
+ ['X-ZONT-Client' => 'your@email.com', 'X-ZONT-Token': 'xxxxxxxx']
+);
+Укажите аутентификационный токен в заголовке X-ZONT-Token.
Метод get_authtoken — Получение аутентификационного токена
curl 'https://my.zont.online/api/get_authtoken' \
+ -u 'login:password' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"client_name": "My cool app"}'
+import requests
+
+result = requests.post(
+ 'https://my.zont.online/api/get_authtoken',
+ auth=('login', 'password'),
+ headers={'X-ZONT-Client': 'your@email.com'},
+ json={"client_name": "My cool app"}
+).json()
+
+token = result['token']
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$response = Requests::post(
+ 'https://my.zont.online/api/get_authtoken',
+ ['X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json'],
+ json_encode(['client_name' => 'My cool app']),
+ ['auth' => ['login', 'password']]
+);
+
+$token = json_decode($response->body)->token;
+POST https://my.zont.online/api/get_authtoken
Возвращает аутентификационный токен для использования в дальнейшем для запросов от имени указанного пользователя.
+ +Этот метод должен отправляться с аутентификацией по паролю.
+Параметры
+| Имя | +Тип | +Описание | +
|---|---|---|
client_name |
+string | +человекопонятное название вашего приложения | +
Результат
+В поле token будет строка — аутентификационный токен, который нужно указывать в заголовке X-ZONT-Token
+в последующих запросах.
Устройства
+ +devices — Запрос устройств
curl 'https://my.zont.online/api/devices' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"load_io": true}'
+import requests
+
+url = 'https://my.zont.online/api/devices'
+data = {'load_io': True}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/devices';
+$data = array('load_io' => true);
+
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::post($url, $headers, json_encode($data), $options);
+$result = json_decode($response->body, true);
+++Результат:
+
{
+ "ok": true,
+ "devices": [
+ {
+ "device_id": 1209
+ ...
+ }
+ ]
+}
+POST https://my.zont.online/api/devices
Возвращает список всех устройств пользователя, а также их параметров.
+Параметры
+| Имя | +Тип | +Описание | +
|---|---|---|
load_io |
+bool | +возвращать ли в поле io Состояния устройства (см. Параметры устройств) |
+
Результат
+В поле devices возвращается массив объектов, описывающих устройства. Порядок элементво в массиве соответствует порядку устройств в личном кабинете пользователя.
Каждый объект, описывающий устройство, может иметь поля, описанные в разделе Параметры устройств.
+ + +add_device — Добавить устройство
curl 'https://my.zont.online/api/add_device' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"devtype": "ZTC-700", "name": "my car", "serial": "012345678915", "timezone": 3}'
+import requests
+
+url = 'https://my.zont.online/api/add_device'
+data = {
+ 'devtype': 'ZTC-700',
+ 'name': 'my car',
+ 'serial': '012345678915',
+ 'timezone': 3
+}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/add_device';
+$data = array(
+ 'devtype' => "ZTC-700",
+ 'name' => "my car",
+ 'serial' => "012345678915",
+ 'timezone' => 3
+);
+
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::post($url, $headers, json_encode($data), $options);
+$result = json_decode($response->body, true);
+++Результат:
+
{
+ "ok": true,
+ "device_id": 1209
+}
+POST https://my.zont.online/api/add_device
Добавить устройство в аккаунт пользователя.
+Параметры
+| Имя | +Тип | +Обязательный | +Описание | +
|---|---|---|---|
devtype |
+string |
+да | +Тип устройства. Один из идентификаторов, описанных в разделе Типы устройств. | +
name |
+string |
+да | +Название устройства для пользователя. | +
serial |
+string |
+да | +Серийный номер | +
timezone |
+int |
+да | +Часовой пояс | +
tel_password |
+string |
+нет | +Телефонный пароль (для GSM-устройств). Телефонный пароль запрашивается устройством при дозвоне на него с номера, не являющегося доверенным. Строка должна состоять только из цифр. | +
notes |
+string |
+нет | +Произвольные заметки об устройстве (например, номер его SIM-карты, чтобы не забыть) | +
wifi_credentials |
+array |
+нет | +Параметры Wi-Fi-сети (только для устройств с Wi-Fi). Массив объектов вида {"ssid": "имя_сети", "password": "пароль_сети"}. ZONT H-2 поддерживает не более одной сети. |
+
boiler_vendor |
+string |
+нет | +Производитель котла (для отопительных устройств) | +
boiler_model |
+string |
+нет | +Модель котла (для отопительных устройств) | +
Результат
+Возвращается объект с полем device_id равным ID нового устройства.
delete_device — Удалить устройство
curl 'https://my.zont.online/api/delete_device' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"device_id": 1209, "clear_data": true}'
+import requests
+
+url = 'https://my.zont.online/api/delete_device'
+data = {
+ 'device_id': 1209,
+ 'clear_data': True
+}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/delete_device';
+$data = array(
+ 'device_id' => 1209,
+ 'clear_data' => true
+);
+
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::post($url, $headers, json_encode($data), $options);
+$result = json_decode($response->body, true);
+++Результат:
+
{
+ "ok": true
+}
+POST https://my.zont.online/api/delete_device
Удалить устройство из аккаунта пользователя.
+Параметры
+| Имя | +Тип | +Обязательный | +Описание | +
|---|---|---|---|
device_id |
+int |
+да | +ID устройства | +
transfer |
+bool |
+нет | +Передать устройство другому пользователю вместо удаления | +
transfer_username |
+string |
+нет | +Логин пользователя, которому передать устройство. Применяется только если параметр transfer равен true. |
+
clear_access |
+bool |
+нет | +Отозвать доступ других пользователей к этому устройству. Если поле transfer не равно true, то доступ других пользователей к устройству отзывается независимо от значения этого параметра. |
+
clear_data |
+bool |
+нет | +Удалить все накопленные данные по этому устройству | +
Результат
+{"ok": true}
update_device — Изменение настроек устройства
curl 'https://my.zont.online/api/update_device' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"device_id": 1580, "thermostat_mode_temps": {"comfort": 21}}'
+import requests
+
+url = 'https://my.zont.online/api/update_device'
+data = {
+ 'device_id': 1580,
+ 'thermostat_mode_temps': {
+ 'comfort': 21
+ }
+}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/update_device';
+$data = array(
+ 'device_id' => 1580,
+ 'thermostat_mode_temps' => array(
+ 'comfort' => 21
+ )
+);
+
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::post($url, $headers, json_encode($data), $options);
+$result = json_decode($response->body, true);
+++Результат:
+
{
+ "ok": true,
+ "thermostat_mode_temps": {
+ "comfort": 21, // только это поле было изменено
+ "econom": 16,
+ "idle": 5,
+ "full_off": false
+ }
+}
+POST https://my.zont.online/api/update_device
Изменяет параметры устройства. Если устройство на связи, обновлённые параметры будут сразу же отправлены ему. Если связи с устройством в данные момент нет, то настройки будут отправлены при следующем выходе на связь.
+Параметры
+| Имя | +Тип | +Описание | +
|---|---|---|
device_id |
+int |
+ID устройства | +
Все остальные параметры в запросе обозначают настройки устройства, которым нужно установить соответствующие значения. Возможные имена, значения и форматы настроек описаны в разделе Параметры устройств.
+ +В случае составного параметра, имеющего внутренние поля, в запросе могут быть указаны только некоторые поля этого параметра. Остальные поля сохранят своё прежнее значение. Так, в примере справа была изменена только целевая температура режима Комфорт, а температуры других режимов остались прежними.
+Результат
+В возвращаемом объекте указываются все параметры, которые были изменены по запросу, и их новые значения.
+ + +set_io_port — Управление состоянием устройства
curl 'https://my.zont.online/api/set_io_port' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"device_id": 1209, "portname": "guard-state",
+ "type": "string", "value": "enabled"}'
+import requests
+
+url = 'https://my.zont.online/api/set_io_port'
+data = {
+ 'device_id': 1209,
+ 'portname': 'guard-state',
+ 'type': 'string',
+ 'value': 'enabled'
+}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/set_io_port';
+$data = array(
+ 'device_id' => 1209,
+ 'portname' => 'guard-state',
+ 'type' => 'string',
+ 'value' => 'enabled'
+);
+
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::post($url, $headers, json_encode($data), $options);
+$result = json_decode($response->body, true);
+++Результат:
+
{
+ "ok": true
+}
+POST https://my.zont.online/api/set_io_port
Посылает устройству команду на изменение одного из следующих Состояний:
+ +-
+
guard-state— состояние охраны
+siren— состояние сирены
+engine-block— состояние блокировки двигателя
+webasto— состояние подогревателя двигателя
+auto-ignition— состояние автозапуска
+
Отправка команды возможна только тогда, когда устройство на связи. Метод всегда возвращает успешное значение, даже в случае, когда связи с устройством нет или если отправка команды не удалась.
+Параметры
+| Имя | +Тип | +Описание | +
|---|---|---|
device_id |
+int |
+ID устройства | +
portname |
+string |
+Имя состояния. Допустима одна из строк: "guard-state", "siren", "engine-block", "webasto" или "auto-ignition" |
+
type |
+string |
+Тип значения. Нужные значения описаны в следующей таблице | +
value |
++ | Требуемое значение состояния | +
Значение параметров type и value:
| Имя состояния | +type |
+value |
+
|---|---|---|
"guard-state" |
+"string" |
+"enabled" для постановки на охрану, "disabled" для снятия с охраны |
+
"auto-ignition" |
+"auto-ignition" |
+объект с полем state, равным: "enabled" для нормального включения автозапуска, "engine" для запуска только двигателя (без подогревателя), "webasto" для включения только подогревателя, "disabled" для выключения автозапуска, "delay" для продления автозапуска. При использовании state: "delay" также должно быть указано поле time с количеством секунд, до которых нужно продлить автозапуск. |
+
| прочие | +"bool" |
+true для включения или false для выключения соответствующего состояния |
+
Результат
+Возвращается объект с единственным полем ok.
send_custom_command — Отправка пользовательской команды
curl 'https://my.zont.online/api/send_custom_command' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"device_id": 18945, "command_id": 1}'
+import requests
+
+url = 'https://my.zont.online/api/send_custom_command'
+data = {
+ 'device_id': 18945,
+ 'command_id': 1
+}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/send_custom_command';
+$data = array(
+ 'device_id' => 18945,
+ 'command_id' => 1
+);
+
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::post($url, $headers, json_encode($data), $options);
+$result = json_decode($response->body, true);
+++Результат:
+
{
+ "ok": true
+}
+POST https://my.zont.online/api/send_custom_command
Посылает устройству одну из пользовательских команд, которые задаются для ZTC-7xx и Mega SX в настроечной утилите.
+ +Отправка команды возможна только тогда, когда устройство на связи. Метод всегда возвращает успешное значение, даже в случае, когда связи с устройством нет или если отправка команды не удалась.
+Параметры
+| Имя | +Тип | +Описание | +
|---|---|---|
device_id |
+int |
+ID устройства | +
command_id |
+int |
+ID команды | +
Идентификтор команды соответствует полю commands[...].id одного из элементов массива в настройке custom_controls (см. Пользовательские команды и статусы).
Результат
+Возвращается объект с одним лишь полем ok.
Загрузка данных
+Устройства ZONT накапливают и отправляют на сервер различные виды данных, которые могут быть получены с сервера +через API.
+load_data — Загрузка различных видов данных
curl 'https://my.zont.online/api/load_data' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"requests": [
+ {"device_id": 1580,
+ "data_types": ["temperature", "events"],
+ "mintime": 1495011600,
+ "maxtime": 1495022400},
+ {"device_id": 1209,
+ "data_types": ["gps", "events"],
+ "mintime": 1495011600,
+ "maxtime": 1495022400}
+ ]}'
+import requests
+
+url = 'https://my.zont.online/api/load_data'
+data = {
+ 'requests': [
+ {
+ 'device_id': 1580,
+ 'data_types': ['temperature', 'events'],
+ 'mintime': 1495011600,
+ 'maxtime': 1495022400
+ },
+ {
+ 'device_id': 1209,
+ 'data_types': ['gps', 'events'],
+ 'mintime': 1495011600,
+ 'maxtime': 1495022400
+ }
+ ]
+}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/load_data';
+$data = array(
+ 'requests' => array(
+ array(
+ 'device_id' => 1580,
+ 'data_types' => array('temperature', 'events'),
+ 'mintime' => 1495011600,
+ 'maxtime' => 1495022400
+ ),
+ array(
+ 'device_id' => 1209,
+ 'data_types' => array('gps', 'events'),
+ 'mintime' => 1495011600,
+ 'maxtime' => 1495022400
+ )
+ )
+);
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::post($url, $headers, json_encode($data), $options);
+$result = json_decode($response->body, true);
+++Результат:
+
{
+ "responses": [
+ {
+ "ok": true,
+ "device_id": 1580,
+ "temperature": ...,
+ "events": ...
+ },
+ {
+ "ok": true,
+ "device_id": 1209,
+ "gps": ...,
+ "events": ...
+ }
+ ]
+}
+POST https://my.zont.online/api/load_data
Получить историю показаний датчиков, историю перемещений, событий или любых других данных, которые устройство +передало на сервер.
+Параметры
+ + +Один HTTP-запрос к методу load_data может одновременно загрузить данные разных типов и сразу по нескольким устройствам.
+Для этого метод принимает параметр requests, который должен быть массивом из объектов-запросов, имеющих следующие поля:
| Имя | +Тип | +Обязательный | +Описание | +
|---|---|---|---|
device_id |
+int |
+да | +ID устройства | +
data_types |
+array |
+да | +Список названий типов данных, которые нужно загрузить. Каждый элемент — строка, обозначающая тип данных, например "gps" или "temperature". Список доступных типов данных приведён в разделе Типы сохраняемых данных. |
+
mintime |
+int |
+нет | +Начало временного диапазона (включительно) | +
maxtime |
+int |
+нет | +Конец временного диапазона (включительно) | +
Временные метки указываются в формате unix time, то есть в виде целого числа секунд, прошедших с 1970-01-01 00:00:00 (UTC).
+Результат
+Ответ будет содержать поле responses с массивом ответов, соответствующих запросам, переданным в параметре requests
+в том же порядке.
Каждый ответ содержит поля:
+ +| Имя | +Тип | +Описание | +
|---|---|---|
ok |
+bool |
+Успешно ли обработан запрос | +
device_id |
+int |
+ID устройства | +
Кроме того ответ будет содержать поля, совпадающие по названиям с типами данных, указанными в поле data_types
+запроса. Каждое такое поле в значении будет содержать сами запрошенные данные. Формат этих данных описан
+в разделе Типы сохраняемых данных.
raw_events — История событий
curl 'https://my.zont.online/api/raw_events' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"device_id": 1209, "only": ["GuardOn", "GuardOff"],
+ "mintime": 1486252800, "maxtime": 1486339200}'
+import requests
+
+url = 'https://my.zont.online/api/raw_events'
+data = {
+ 'device_id': 1209,
+ 'mintime': 1486252800,
+ 'maxtime': 1486339200,
+ 'only': ['GuardOn', 'GuardOff']
+}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/raw_events';
+$data = array(
+ 'device_id' => 1209,
+ 'mintime' => 1486252800,
+ 'maxtime' => 1486339200,
+ 'only' => array('GuardOn', 'GuardOff')
+);
+
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::post($url, $headers, json_encode($data), $options);
+$result = json_decode($response->body, true);
+++Результат:
+
{
+ "ok": true,
+ "events": [
+ [
+ "GuardOn-1486253766", // id
+ 1486253766, // время
+ "GuardOn", // тип
+ 43.871066, // долгота
+ 56.166916, // широта
+ null, // продолжительность
+ { // данные
+ "reason": "fob", // причина постановки на охрану
+ "fob_number": 1 // номер брелока
+ },
+ false // тревожное?
+ ],
+
+ ...
+ ]
+}
+POST https://my.zont.online/api/raw_events
Получить список событий, зарегистрированных устройством в заданном промежутке времени.
+Параметры
+| Имя | +Тип | +Обязательный | +Описание | +
|---|---|---|---|
device_id |
+int |
+да | +ID устройства | +
mintime |
+int |
+да | +Начало временного диапазона (включительно) | +
maxtime |
+int |
+да | +Конец временного диапазона (включительно) | +
only |
+array |
+нет | +Интересующие типы событий | +
except |
+array |
+нет | +Не интересующие типы событий | +
Время указывается в целых секундах, прошедших с 1970-01-01 00:00:00 (UTC). Не забудьте сделать поправку на нужный часовой пояс!
+ +С помощью параметров only и except можно отфильтровать возвращаемый список событий. Каждый из этих
+необязательных параметров может содержать массив типов событий (строк). Если указан параметр only, то возвращаются
+только события типов, указанных в нём. Если указан except, то события типов, указанных в нём, не возвращаются. Если
+оба парамтера не указаны, возвращаются все события.
Результат
+Ответ будет содержать поле events, содержащее массив событий, отсортированных по времени. Каждое событие — это массив, содержащий
+следующие элементы:
| Индекс | +Тип | +Описание | +
|---|---|---|
| 0 | +string |
+Идентификатор события. Мы решили отказаться от уникальных идентификаторов событий, поэтому это поле существует только для совместимости со старыми версиями клиентов и не является в действительности уникальным. Не рекомендуем использовать это поле, оно будет удалено в будущих версиях API. | +
| 1 | +int |
+Время события (в секундах с 1970-01-01 00:00:00 UTC) | +
| 2 | +string |
+Тип события | +
| 3 | +float |
+Долгота местоположения события в градусах (null если неизвестно) |
+
| 4 | +float |
+Широта местоположения события в градусах (null если неизвестно) |
+
| 5 | +int |
+Длительность события в секундах (null если неизвестно). Указывается только для некоторых типов событий, например "Stop" (остановка). |
+
| 6 | +object |
+Дополнительная информация о событии (null если отсутствует). Формат этого поля определяется типом события. |
+
| 7 | +bool |
+Является ли событие тревожным («важным») | +
Типы событий
+| Тип | +Тревожное | +Описание | +Доп. данные | +
|---|---|---|---|
"Stop" |
+нет | +Остановка устройства с GPS. Продолжительность остановки в секундах передаётся не в поле дополнительных данных, а в поле длительности. | +null |
+
"PowerOn" |
+нет | +Включение устройства. В поле длительности — время в секундах, в течение которого устройство было выключено. | +null |
+
"PowerOff" |
+нет | +Выключение устройства | +null |
+
"MainPowerLost" |
+да | +Пропадание основного питания | +null |
+
"MainPowerFound" |
+да | +Появление основного питания | +null |
+
"GPSLost" |
+нет | +Потеря сигнала GPS | +null |
+
"GPSFound" |
+нет | +Нахождение сигнала GPS | +null |
+
"GSMLost" |
+нет | +Потеря сигнала GSM | +null |
+
"GSMFound" |
+нет | +Регистрация в сети GSM | +null |
+
"connected" |
+нет | +Соединение с сервером | +null |
+
"disconnected" |
+нет | +Отключение от сервера | +"reason" — причина отключения (строка) |
+
"reconnected" |
+нет | +Переподключение к серверу | +null |
+
"GuardOn" |
+нет | +Постановка на охрану | +"reason" — причина постановки:
"fob_number" — номер брелока "phonenumber" — номер телефона. |
+
"GuardOff" |
+нет | +Снятие с охраны | +(см. "GuardOn") |
+
"AlarmButton" |
+да | +Нажатие тревожной кнопки | +null |
+
"Shock1" |
+нет | +Слабый удар | +null |
+
"Shock2" |
+да | +Сильный удар | +null |
+
"Door" |
+да | +Тревога по открытию двери | +null |
+
"Door1", "Door2", "Door3", "Door4", "Door5", "Door6" |
+да | +Тревога по открытию соответствующей двери | +null |
+
"HoodTrunk" |
+да | +Тревога по открытию капота/багажника | +null |
+
"Hood" |
+да | +Тревога по открытию капота | +null |
+
"Trunk" |
+да | +Тревога по открытию багажника | +null |
+
"AutoIgnition" |
+нет | +Автозапуск двигателя | +"reason" — причина ("manual" — по команде, "temperature" — по температуре, "timer" — по таймеру, "schedule" — по расписанию) "result" — результат ("success" — успешно, "fail" — неуспешно, "breakdown" — двигатель заглох) |
+
"EngineBreakdown" |
+да | +Аварийная остановка двигателя | +null |
+
"SoftwareUpgrade" |
+нет | +Обновление ПО | +"firmware_version" — версия прошивки, "profile_version" — версия профиля |
+
"Alarm" |
+да | +Тревога | +null |
+
"AlarmIgnition" |
+да | +Тревога по зажиганию | +null |
+
"AlarmTilt" |
+да | +Тревога по датчику наклона | +null |
+
"AlarmBrake" |
+да | +Тревога по педали тормоза | +null |
+
"EngineBlock" |
+да | +Сработала блокировка двигателя | +null |
+
"Moving" |
+да | +Тревога по движению | +null |
+
"Blackout" |
+да | +Глушение сигнала GSM | +null |
+
"GSMLostAlarm" |
+да | +Тревога по пропаданию сигнала GSM | +null |
+
"EngineStarted" |
+нет | +Двигатель заведён | +null |
+
"EngineStopped" |
+нет | +Двигатель остановлен | +null |
+
"DriverCallButton" |
+да | +Кнопка вызова водителя | +null |
+
"OutCallTone" |
+нет | +Дозвон: гудок | +"number" — номер телефона |
+
"OutCallConnection" |
+нет | +Дозвон: соединение | +"number" — номер телефона |
+
"OutCallEnd" |
+нет | +Дозвон: завершение | +"number" — номер телефона |
+
"OutSMS" |
+нет | +Исходящее SMS | +"number" — номер телефона, "text" — текст |
+
"InCall" |
+нет | +Входящий вызов | +"number" — номер телефона |
+
"InCallConnection" |
+нет | +Входящий вызов: соединение | +"number" — номер телефона |
+
"InCallEnd" |
+нет | +Входящий вызов: завершение | +"number" — номер телефона |
+
"InSMS" |
+нет | +Входящее SMS | +"number" — номер телефона, "text" — текст |
+
"ThermometerUpdate" |
+нет | +Найден термодатчик | +"slot" — номер слота (с нуля), "type" — тип ("wired" — проводной, "radio" — радио), "serial" — серийный номер |
+
"TemperatureHigh" |
+да | +Температура выше порога | +"message" — текстовое сообщение (название датчика) |
+
"TemperatureLow" |
+да | +Температура ниже порога | +"message" — текстовое сообщение (название датчика) |
+
"ThermometerMalfunction" |
+да | +Термодатчик недоступен | +"message" — текстовое сообщение (название датчика) |
+
"BatteryLow" |
+да | +Разряд аккумулятора | +"voltage" — напряжение в вольтах |
+
"RadioFOBAdded" |
+нет | +Добавлен брелок или радиореле | +"slot" — номер слота |
+
"BoilerFail" |
+да | +Авария котла | +null |
+
"BoilerFailCancel" |
+да | +Авария котла устранена | +null |
+
"Landmark" |
+нет | +Метка (ZONT Трекер) | +"label" — имя метки |
+
"ZoneAlarm" |
+да | +Срабатывание охранной зоны | +"message" — сообщение, "zone" — номер зоны |
+
"ZoneAlarmCancel" |
+нет | +Восстановление охранной зоны | +"message" — сообщение, "zone" — номер зоны |
+
"OTFail" |
+да | +Авария котла или её устранение (OpenTherm). Аварии нет если поле "c" равно нулю, а массив "f" пуст |
+"c" — код ошибки OEM "f" — массив флагов сбоя:
|
+
"OTLost" |
+да | +Потеря связи по OpenTherm | +null |
+
"OTFound" |
+да | +Восстановление связи по OpenTherm | +null |
+
"UploadSuccess" |
+нет | +Файлы успешно загружены | ++ |
"UploadFailed" |
+да | +Не удалось загрузить файлы | ++ |
"UserEvent" |
+нет | +Пользовательское событие | +"message" — сообщение |
+
"UserAlarm" |
+да | +Пользовательское тревожное событие | +"message" — сообщение |
+
"ExtSensorWarning" |
+да | +Предупредительная зона доп. датчика | ++ |
"ExtSensorAlarm" |
+да | +Тревожная зона доп. датчика | ++ |
"CurrentECUErrors" |
+да | +Текущие ошибки ЭБУ (диагностика двигателя автомобиля) | +"errors" — коды ошибок OBD-II (массив чисел) |
+
"SavedECUErrors" |
+да | +Сохранённые ошибки ЭБУ (диагностика двигателя автомобиля) | +"errors" — коды ошибок OBD-II (массив чисел) |
+
Типы сохраняемых данных
+В этом разделе перечислены различные типы данных, которые устройства передают на сервер ZONT, и которые вы можете
+загрузить с сервера с помощью метода load_data.
Для каждого вида данных указано его строковое название, которое нужно передавать в параметре "data_types" запроса,
+и которое используется в качестве ключа в возвращаемом ответе. Также описан формат, в котором эти данные возвращаются.
Формат Delta-time Array
+++Пример кодирования температурных показаний:
+
[
+ [1495098587, 21.4], // 18.05.2017 12:09:47 — 21.4 °C
+ [-60, 21.5], // 18.05.2017 12:10:47 — 21.5 °C
+ [-60, 21.7], // 18.05.2017 12:11:47 — 21.7 °C
+ [-60, 21.4] // 18.05.2017 12:12:47 — 21.4 °C
+]
+При передаче сохранённых данных как правило нужно закодировать набор значений, каждое из которых привязано к моменту времени. +Например это могут быть GPS-координаты, значения температуры, события. Если при передаче таких данных в формате JSON каждую +метку времени передавать в виде полного значения времени, то эти временные метки будут занимать значительный объём данных, +иногда превышающий объём самих значений. Для экономии трафика мы используем простой способ дельта-кодирования временных меток, +который в дальнейшем называем Delta-time Array.
+ +Delta-time Array — это массив массивов следующей структуры:
+ +[ [time1, ...], [time2, ...], ... [timeN, ...] ]
Первым элементом каждого массива является метка времени. Остальные элементы зависят от характера кодируемых данных.
+ +Метки времени являются целыми числами подчинаются следующему правилу:
+ +-
+
- Если метка времени — положительное число, то она обозначает время в формате unix time, то есть в целых секундах
+с 1970-01-01 00:00:00 (UTC). Например,
1495098587обозначает 18.05.2017 12:09:47 (UTC+03) (московское время).
+ - Если метка времени — отрицательное число, то её абсолютное значение означает разницу в секундах от предыдущей
+метки. Например,
-60означает предыдущую метку времени плюс одна минута. Отрицательные значения +меток могут идти друг за другом, и тогда каждая кодирует время, прошедшее от предыдущей.
+
Первая метка времени в массиве — всегда положительная. Последующие могут быть как положительными, так и отрицательными.
+temperature — показания температурных датчиков
+++Пример ответа на
+load_data:
{
+ "responses": [
+ {
+ "ok": true,
+ "device_id": 1580,
+
+ "temperature": {
+ "41da3643-47b6-4f97-afc9-d9faf9a569de": {
+ "name": "Датчик",
+ "color": "#c4443b",
+ "sort": 1,
+ "temperature": [
+ [1495011630, 20.2],
+ [-60, 20.1],
+ [-60, 20.2],
+ [-60, 20.2],
+ ...
+ ]
+ }
+ }
+ }
+ ]
+}
+Этот вид сохраняемых данных используется для устройств ZONT H, Mega SX и H-1000. В него попадают показания +проводных и беспроводных температурных датчиков, подключенных к устройству. Их показания сохраняются раз в минуту.
+ +При запросе данных методом load_data температурные показания возвращаются в виде объекта. Полям этого объекта
+соответствуют уникальные строковые идентификаторы термодатчиков, а значения — объекты со следующей структурой:
| Поле | +Тип | +Описание | +
|---|---|---|
name |
+string |
+Название датчика | +
color |
+string |
+Цвет датчика, задаваемый пользователем в веб-интерфейсе, в виде hex-строки (#rrggbb) | +
sort |
+int |
+Задаёт порядок отображения датчиков. При показе пользователю списка датчиков, их следует отсортировать по возрастанию этого поля. | +
temperature |
+array |
+Массив показаний датчика за запрошенный период в формате Delta-time Array | +
thermostat_work — данные о работе термостата
{
+ "responses": [
+ "ok": true,
+ "device_id": 1580,
+
+ "thermostat_work": {
+ "thermostat_mode": [[1495011630, 1], [-3600, 2], ...],
+ "boiler_work_time": [[1495011630, 60], [-60, 60], [-60, 23], [-60, 0], ...],
+ "target_temp": [[1495011630, 23], [-3600, 18], ...],
+ "power": [[1495011630, true], [-86400, true]],
+ "fail": [[1495011630, false], [-86400, false]],
+ "zones": {
+ "1": {
+ "target_temp": [[1495011630, 23], [-3600, 18], ...],
+ "worktime": [[1495011630, 60], [-60, 60], [-60, 23], [-60, 0], ...],
+ }
+ },
+ "ot": {
+ "s": [[1495011630, ["ch", "fl"]], [-120, ["ch"]], ...],
+ "cs": [[1495011630, 57], [-60, 58], ...],
+ "ff": [[1495011630, {"c": 0, "f": []}], [-86400, {"c": 0, "f": []}]],
+ ...
+ }
+ }
+ ]
+}
+Устройства ZONT H ежеминутно сохраняют информацию о работе термостата и значения различных параметров.
+ +При запросе этого типа данных с помощью метода load_data будет возвращён объект со следующими полями:
| Поле | +Тип | +Описание | +
|---|---|---|
thermostat_mode |
+ DTA<int> | +
+ Режим термостата. Кодируется числом. +Для H-1/H-2 с прошивками ниже xx:82 и H-1000/Mega SX с прошивками ниже xx:172 число означает: +
Для более новых прошивок число означает номер задаваемого пользователем режима. Если вам необходима + описание как получить настройки режимов — напишите нам. + |
+
boiler_work_time |
+ DTA<int> | +
+ (для однозонного термостата) Количество секунд, в течение которых котёл работал за последнюю минуту. +Под работой котла здесь понимается состояние выхода термостата. То есть при отсутствии основного питания, + значение этого параметра не будет соответствовать действительности, так как реле не будет на самом + деле переключаться. + |
+
target_temp
+ | ||
pza_t |
+ DTA<float> | +Расчётная температура ПЗА | +
dhw_t |
+ DTA<float> | +Заданная температура ГВС | +
power |
+ DTA<bool> | +
+ Наличие основного питания: Термостаты ZONT H при отсутствии питания не управляют термостатом, реле переходит в нормальное состояние (см. документацию). + |
+
fail |
+ DTA<bool> | +
+ Признак аварии котла: true — авария есть, false — аварии нет.
+ При наличии OpenTherm больше информации об аварии можно получить в поле ot.
+ |
+
gate |
+ DTA<bool> | +Активность режима Комнатного термостата: true — режим включен, термостат
+ управляется внешним комнатным термостатом; false — режим выключен, термостат
+ управляет по обычному алгоритму. |
+
ot |
+ object |
+ Состояние OpenTherm. Поля объекта соответствуют аналогичным полям состояния
+ last-boiler-state.ot, а значениями
+ полея являются массивы Delta-time array из соответствующих
+ величин. |
+
zones |
+ object |
+
+ (для многозонного термостата) Информация о работе отдельных зон. Полями объекта являются + номера зон, а значениями — объекты со следующими полями: + + |
+
custom_controls — история состояний пользовательских статусов
+++Пример ответа на
+custom_controls
{
+ "responses": [
+ {
+ "ok": true,
+ "device_id": 18945,
+
+ "custom_controls": [
+ [1498710530,0],
+ [-8,2],
+ [-6277,3],
+ [-15,1],
+ [-4961,0],
+ ...
+ ]
+ }
+ ]
+}
+Сохраняемые данные типа custom_controls используются для устройств Mega SX, H-1000 и ZTC. Запросив этот
+тип данных можно получить историю переключений пользовательских статусов.
При запросе данных с помощью метода load_data данные возвращаются в виде массива в
+формате Delta-time Array. В качестве значений в этом массиве передаются целые числа.
+Каждый бит в двоичном представлении числа обозначает состояние статуса с соответствующим идентификатором.
Например, от сервера получен такой ответ:
+ +[[1498710120, 0], [-86, 6], [-5, 2]]
Этот ответ обозначает:
+ +-
+
- 2017-06-29 04:22:00 UTC — все статусы неактивны (
0не содержит битов, равных 1)
+ - через 86 секунд включились статусы с идентификаторами 1 и 2 (
6это110₂, биты считаются с нуля от младшего с старшему)
+ - ещё через 5 секунд статус с идентификатором 2 выключился (
4это100₂, бит номер 2 обнулился)
+
z3k_temperature — история состояний пользовательских статусов
+++Пример ответа на
+z3k_temperature
{
+ "responses": [
+ {
+ "ok": true,
+ "device_id": 18945,
+ "z3k_temperature": {
+ 4104: [
+ [1498710530,0],
+ [-8,2],
+ [-6277,3],
+ [-15,1],
+ [-4961,0],
+ ...
+ ], ...
+ }}
+ ]
+}
+Сохраняемые данные типа z3k_temperature используются для устройств H-2000+, H-2000 PRO H-2000 PRO.V2, Climatic, H1V.02, SMART NEW и им подобных. Запросив этот
+тип данных можно получить историю значений с датчиков температуры.
При запросе данных с помощью метода load_data данные возвращаются в виде массива в
+формате Delta-time Array. В качестве значений в этом массиве передаются целые числа.
+Ключом является ID объекта из z3k_config.
z3k_radio_sensor — история значений с радиодатчиков
+По аналогии с z3k_temperature
z3k_heating_circuit — история состояний контуров отопления
+По аналогии с z3k_temperature
z3k_web_element — история состояний пользовательских кнопок
+По аналогии с z3k_temperature
z3k_boiler_adapter — данные о работе котла по OpenTherm / EMS / BSB
+++Пример ответа на
+z3k_boiler_adapter
{
+ "responses": [
+ {
+ "ok": true,
+ "device_id": 457157,
+ "z3k_boiler_adapter": {
+ "4097": {
+ "s": [[1735603200, ["ch", "fl"]], [-60, ["ch"]], ...],
+ "cs": [[1735603200, 57.0], [-60, 58.0], ...],
+ "rml": [[1735603200, 35.0], [-60, 28.0], ...],
+ "bt": [[1735603200, 56.5], [-60, 57.0], ...],
+ "wp": [[1735603200, 1.4], [-60, 1.4], ...],
+ "ff": [[1735603200, {"c": 0, "f": []}], ...],
+ ...
+ },
+ "4098": { ... }
+ }
+ }
+ ]
+}
+Сохраняемые данные типа z3k_boiler_adapter используются для устройств H-2000+, H-2000+ PRO, H-2000+ PRO.V2, Climatic, H1V.02, SMART NEW и им подобных, у которых к z3k подключены адаптеры котлов (OpenTherm, EMS+, BSB, BridgeNet и т.п.). Запросив этот тип данных, можно получить историю значений всех регистров котлового адаптера с шагом до одной минуты — это те же ряды, что отображаются на графиках в личном кабинете (модуляция горелки, расчётная температура теплоносителя, давление и т.д.).
Ключом первого уровня является ID адаптера из z3k_config (например 4097, 4098). Значением — объект, в котором имена полей совпадают с одноимёнными полями состояния last-boiler-state.ot, а сами значения представляют собой Delta-time Array из соответствующих величин. Полный список полей:
| Поле | +Тип | +Описание | +
|---|---|---|
s |
+DTA<array<string>> | +Массив флагов состояния ("ch", "dhw", "fl", "cl", "ch2", "di", "f"). См. last-boiler-state.ot.s. |
+
cs |
+DTA<float> | +Расчётная температура теплоносителя отопления, °C. | +
cs2 |
+DTA<float> | +Расчётная температура теплоносителя второго контура отопления, °C. | +
bt |
+DTA<float> | +Фактическая температура теплоносителя, °C. | +
rwt |
+DTA<float> | +Температура обратного потока, °C. | +
dt |
+DTA<float> | +Фактическая температура ГВС, °C. | +
ot |
+DTA<float> | +Уличная температура, °C. | +
rml |
+DTA<float> | +Относительный уровень модуляции горелки, %. | +
mrml |
+DTA<float> | +Максимальный уровень модуляции, %. | +
wp |
+DTA<float> | +Давление теплоносителя, бар. | +
fr |
+DTA<float> | +Скорость потока ГВС, л/мин. | +
rp |
+DTA<float> | +Заданная мощность котла, %. | +
rt |
+DTA<float> | +Заданная комнатная температура, °C. | +
rors |
+DTA<float> | +Уставка ПЗА, °C. | +
rbp |
+DTA<float> | +Заданное давление в котле, бар. | +
ds |
+DTA<float> | +Заданная температура ГВС, °C. | +
db |
+DTA<array<int>> | +Допустимые границы заданной температуры ГВС, [min, max]. |
+
b |
+DTA<array<int>> | +Допустимые границы заданной температуры котла, [min, max]. |
+
ff |
+DTA<object> | +Состояние аварии. Структура объекта — как в last-boiler-state.ot.ff: { "c": <OEM-код>, "f": [<флаги>] }. |
+
sc |
+DTA<object> | +Конфигурация slave-устройства. | +
mv |
+DTA<array<int>> | +Версия мастера, [major, minor]. |
+
sv |
+DTA<array<int>> | +Версия slave, [major, minor]. |
+
Набор полей зависит от протокола адаптера и модели котла: если адаптер не передаёт регистр, соответствующее поле в ответе будет отсутствовать.
+ztc_state — состояние контроллера (питание, GSM, Wi-Fi)
+++Пример ответа на
+ztc_state
{
+ "responses": [
+ {
+ "ok": true,
+ "device_id": 457157,
+ "ztc_state": {
+ "gsm_level": [[1735603200, 24], [-60, 23], ...],
+ "gsm_state": [[1735603200, 1], ...],
+ "gsm_balance": [[1735603200, 150], ...],
+ "voltage": [[1735603200, 12.1], [-60, 12.1], ...],
+ "wifi_rssi": [[1735603200, 62], ...],
+ "status_flags":[[1735603200, 81], [-60, 81], ...],
+ "temperature": [
+ [[1735603200, 22.4], [-60, 22.5], ...],
+ [],
+ [],
+ [],
+ []
+ ]
+ }
+ }
+ ]
+}
+Сохраняемые данные типа ztc_state — это история служебного состояния контроллера, которое присылается раз в минуту. Доступно для устройств H-2000+, H-2000+ PRO, Climatic, SMART NEW и других z3k-устройств, а также для ZTC-7xx / Mega SX. Запросив этот тип данных, можно получить историю уровня сигнала GSM, состояния регистрации в сети, баланса SIM-карты, напряжения питания, уровня сигнала Wi-Fi и встроенных температурных входов.
При запросе данных методом load_data возвращается объект со следующими полями:
| Поле | +Тип | +Описание | +
|---|---|---|
gsm_level |
+DTA<int> | +Уровень сигнала GSM, целое число в диапазоне 0..31 (null — данные не передавались). |
+
gsm_state |
+DTA<int> | +Состояние регистрации в GSM-сети: 0 — не зарегистрирован, 1 — домашняя сеть, 2 — поиск сети, 3 — отказ в регистрации, 5 — роуминг, 255 — неизвестно. |
+
gsm_balance |
+DTA<int> | +Баланс SIM-карты, в копейках/центах (null — данные не передавались). |
+
voltage |
+DTA<float> | +Напряжение основного питания, В. | +
wifi_rssi |
+DTA<int> | +Уровень сигнала Wi-Fi (RSSI). Применимо только для устройств с Wi-Fi. | +
status_flags |
+DTA<int> | +Битовая маска состояния. Биты: 0 — наличие основного питания, 1 — наличие питания по USB, 2 — связь по GSM, 3 — связь по Wi-Fi, 4 — связь по Ethernet, 5 — питание от аккумулятора, 6 — установлено соединение с сервером. Например, значение 81 (0b1010001) означает «есть основное питание, связь по Ethernet, соединение с сервером установлено». |
+
temperature |
+array of DTA<float> | +Показания пяти встроенных температурных входов контроллера. Массив всегда содержит 5 элементов (по индексу = номеру входа); для входов, на которых датчик не подключён, элемент будет пустым массивом. | +
Поля gsm_* и wifi_rssi присутствуют в ответе только если контроллер передавал соответствующие данные за запрошенный период.
Типы устройств
+В рамках системы ZONT выпускается множество устройств с различным назначением. Каждой модели соответствует свой идентификатор.
+ +| Идентификатор | +Модель | +Описание | +
|---|---|---|
T100 |
+ZONT H-1/H-1V | +Домашний GSM-термостат | +
T102 |
+ZONT H-2 | +Домашний Wi-Fi-термостат | +
L1000 |
+ZONT L-1000 | +Многофункциональный программируемый GSM/Wi-Fi-термостат | +
ZTC-100 |
+ZTC-100 | +Спутниковый поисковый модуль | +
ZTC-110 |
+ZTC-110 | +Спутниковый охранно-поисковый модуль | +
ZTC-500 |
+ZTC-500 | +Автомобильная сигнализация | +
ZTC-700 |
+ZTC-700 | +Автомобильная сигнализация | +
ZTC-700M |
+ZTC-700M | +Автомобильная сигнализация | +
ZTC-701M |
+ZTC-701M | +Автомобильная сигнализация | +
ZTC-710 |
+ZTC-710 | +Автомобильная сигнализация | +
ZTC-720 |
+ZTC-720 | +Автомобильная сигнализация | +
tracker |
+ZONT Трекер | +Приложение для Android | +
ZTA-110 |
+ZTA-110 | +Объектовая сигнализация | +
SX250 |
+Mega SX-LRW | +Объектовая сигнализация | +
SX170 |
+Mega SX-170 | +Объектовая сигнализация | +
SX300 |
+Mega SX-300 | +Объектовая сигнализация | +
SX350 |
+Mega SX-350 | +Объектовая сигнализация | +
Параметры устройств
+У каждого устройства есть Настройки и Состояния.
+ +Настройками называют те параметры, значения которых обычно редко изменяются и которыми есть смысл управлять при отсутствии связи с устройством (например: список доверенных номеров, целевые температуры). Состояния — это параметры, описывающие устройство только в данный момент, значения которых могут меняться в зависимости от внешних воздействий (например: состояние охраны, уровень сигнала).
+ +Получить текущие Настройки устройств можно с помощью метода devices. Если при запросе указать "load_io": true, то в каждом объекте, описывающем устройство, в поле "io" также будут возвращены Состояния устройств.
Изменить Настройки можно с помощью метода update_device. Управлять Состояниями — с помощью метода set_io_port.
Ниже приведены описания всех параметров устройств, сгруппированные по области применения. Обратите внимание, что одно и то же устройство может относиться к нескольким разделам.
+Общие для всех типов устройств
Настройки
{
+ "id": 1209,
+ "serial": "973BF3309550",
+ "name": "Сигнализация"
+
+ ...
+}
+| Название | +Тип | +Описание | +
|---|---|---|
id |
+int |
+Идентификатор устройства | +
serial |
+string |
+Серийный номер | +
name |
+string |
+Название | +
Состояние беспроводной сети
Настройки
{
+ "balance": {
+ "ussd": "*102#",
+ "warning": true,
+ "limit": 30
+ },
+ "trusted_phones": "+79082394312,+79102417612",
+ "gsm_roaming": "same"
+
+ ...
+}
+| Название | +Тип | +Описание | +||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
balance |
+ object |
+
+ Настройки отслеживания баланса SIM-карты + +
|
+ ||||||||||||
trusted_phones |
+ string |
+ Доверенные номера телефонов, разделённые запятой | +||||||||||||
gsm_roaming |
+ string |
+
+ Разрешение использования интернета в роуминге +
|
+
Состояния
{
+ "io": {
+ "balance-value": "56",
+ "gsm-state": {
+ "level": 29,
+ "operator": "MTS",
+ "state": "home-network"
+ },
+ ...
+ }
+
+ ...
+}
+| Название | +Тип | +Описание | +||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
balance-value |
+ string|null |
+ Текущее значение баланса SIM-карты | +||||||||||||
gsm-state |
+ object |
+
+ Состояние GSM/Wi-Fi +
|
+
Охрана (ZTC, Mega SX, ZONT H)
Состояния
{
+ "io": {
+ "guard-state": "enabled",
+ "siren": false
+ ...
+ }
+
+ ...
+}
+| Название | +Тип | +Описание | +
|---|---|---|
guard-state |
+string |
+"enabled" если охрана активна, "disabled" если не активна или "enabling" если выполняется постановка на охрану |
+
siren |
+bool |
+сирена активна в данный момент | +
Взаимодействие с автомобилем (ZTC)
Настройки
{
+ "temperature_conf": {
+ "assignments": [
+ "cabin",
+ "engine"
+ ]
+ }
+ ...
+}
+| Название | +Тип | +Описание | +||||||
|---|---|---|---|---|---|---|---|---|
temperature_conf |
+ object |
+
+ Настройка термодатчиков. Объект со следующими полями:
+
|
+
Состояния
{
+ "io": {
+ "engine-block": false,
+ "webasto": false,
+ "auto-ignition": {
+ "available": true,
+ "state": "enabled",
+ "configuration": {
+ "engine": true,
+ "webasto": false
+ },
+ "current_mode": {
+ "engine": true,
+ "webasto": false
+ },
+ "until": 1478811896
+ },
+ "ignition-state": true,
+ "engine-state": true,
+ "doors": false,
+ "door-1": null,
+ "door-2": null,
+ "door-3": null,
+ "door-4": null,
+ "hood-trunk": null,
+ "hood": false,
+ "trunk": false,
+ "ecu-diagnostics-enabled": true,
+ "temperature": [
+ {"state": "ok", "value": 21},
+ {"state": "ok", "value": 73},
+ {"state": "disconnected", "value": 0}
+ ]
+ ...
+ }
+
+ ...
+}
+Управление отоплением (ZONT H)
Старый и новый формат режимов отопления
+Ранние весии прошивок ZONT H-1, H-1V, H-2 поддерживали ровно 4 режима отопления: «Эконом», «Комфорт», +«Расписание» и «Антизаморозка/Выключен». В новых версиях появились более гибкие настраиваемые режимы, а также +появилась отдельная концепция «целевых температур», которые имеют приоритет над текущим режимом отопления, +в случае если целевая температура отредактирована пользователем вручную.
+ +Это изменение отразилось и на API. В описании настроек ниже те поля, которые относятся только к старому +или только к новому формату режимов, будут отмечены комментарием.
+ +В устройстве всегда работает либо старая, либо новая схема режимов, они не совмещаются. Тем не менее для +новой схемы API всё равно выдаёт для устройства и старые поля тоже для ограниченной обратной совместимости. +Поля, соответствующие новому формату, имеют приоритет.
+ +Версии прошивок, поддерживающих новый формат:
+ +| Модель | +Версия прошивки | +
|---|---|
| ZONT H-1, H-1V, H-1B, H-2 | +≥ xx:82 | +
| ZONT H-1000, H-2000 | +любая | +
Настройки
{
+ // старый формат режимов
+ "thermostat_mode": "comfort",
+ "thermostat_mode_temps": {
+ "econom": 15,
+ "comfort": 21.5,
+ "idle": 5,
+ "full_off": false
+ },
+
+ // новый формат режимов
+ "thermostat_ext_mode": 1,
+ "thermostat_ext_modes_config": {
+ "0": {
+ "active": true,
+ "name": "Эконом",
+ "zone_sensors": {"0": null, "1": null},
+ "zone_temp": {"0": 15, "1": 15}
+ },
+ "1": {
+ "active": true,
+ "name": "Расписание",
+ "schedule_number": 1,
+ "zone_sensors": {},
+ "zone_temp": {},
+ },
+ "2": {
+ "active": true,
+ "name": "Выключен",
+ "zone_temp": {"0": false, "1": false},
+ },
+ "3": {"active": false, ...},
+ ...
+ },
+
+ "tempschedule": {
+ "day": [23, 23, 23, ..., 23],
+ "week": {
+ "0": [16, 16, 16, ..., 16],
+ ...
+ "6": [21.5, 21.5, ..., 21.5]
+ }
+ },
+
+ "thermometers": [
+ {
+ "uuid": "57d5c19005b605000bc4502b",
+ "is_assigned_to_slot": true,
+ "name": "Кухня",
+ "color": "#a05be5",
+ "functions": [{"f": "control", "zone": 1}],
+ "limits": {
+ "high": 30,
+ "low": 16
+ },
+ "type": "wired",
+ "last_value_time": 1478383975,
+ "last_state": "ok",
+ "last_value": 21.2
+ }
+ ...
+ ],
+
+ "ot_enabled": true,
+ "ot_mode": "analog",
+ "ot_max_setpoint": 80,
+ "ot_min_setpoint": 5,
+ "ot_max_ml": 100,
+ "ot_dhw_setpoint": 46,
+ "ot_min_wp": 0,
+ "ot_config": ["ch", "dhw"],
+ "ot_save_params": ["bt", "dt", "ot"]
+
+ ...
+}
+| Название | +Тип | +Описание | +
|---|---|---|
thermostat_mode |
+ string |
+
+ (Только для старого формата режимов) + Режим термостата. Возможные значения: +
|
+
thermostat_mode_temps |
+ object |
+
+ (Только для старого формата режимов) + Целевая температура фиксированных режимов термостата. Объект имеет следующие поля: +
|
+
thermostat_ext_mode |
+ int |
+
+ (Только для нового формата режимов) + Номер текущего режима отопления. Соответствует индексу в объекте thermostat_ext_modes_config.
+ |
+
thermostat_ext_modes_config |
+ object |
+
+ (Только для нового формата режимов) + Конфигурация режимо отопления. Объект (не массив!), ключами которого являются номера режимов (начиная с нуля), + а значениями — объекты конфигурации режима. Эти объекты имеют следующие поля: +
|
+
tempstep |
+ float |
+ Шаг изменения температуры кнопками – и + в веб-интерфейсе и мобильном приложении. | +
tempschedule |
+ object |
+
+ Расписание температур. Применяется устройством когда выставлен режим «Расписание».
+
|
+
thermometers |
+ array |
+
+ Данные о термодатчиках. Массив объектов, каждый из которых имеет следующие поля:
+
|
+
ot_enabled |
+ bool |
+ OpenTherm включен | +
ot_mode |
+ string |
+ Режим работы OpenTherm: "analog" — обычный, "relay" — псевдорелейный |
+
ot_max_setpoint |
+ float |
+ Максимальная заданная температура теплоносителя (OpenTherm) | +
ot_min_setpoint |
+ float |
+ Минимальная заданная температура теплоносителя (OpenTherm) | +
ot_max_ml |
+ float |
+ Максимальный уровень модуляции горелки в процентах (OpenTherm) | +
ot_dhw_setpoint |
+ float |
+ Заданная температура ГВС (OpenTherm) | +
ot_min_wp |
+ float |
+ Минимальное давление теплоносителя (OpenTherm) | +
ot_config |
+ array |
+
+ Настройки функционала OpenTherm. Массив, содержащий строковые флаги: +
|
+
ot_save_params |
+ array |
+
+ Параметры OpenTherm для ежеминутного сохранения. По выбранным параметрам можно будет увидеть графики в веб-интерфейсе и приложениях ZONT. Массив, содержащий строковые флаги: +
Параметры |
+
Состояния
{
+ "io": {
+ "last-boiler-state": {
+ "time": 1479881662,
+ "boiler_work_time": 60,
+ "thermostat_mode": "comfort",
+ "target_temp": 22.0,
+ "gate": false,
+ "power": true,
+ "fail": false,
+ "pza_t": null,
+ "ot": {
+ "s": ["ch", "fl"],
+ "cs": 37,
+ "ff": {"f": [], "c": 0},
+ "bt": 35,
+ "dt": 32,
+ "ot": -12.0
+ }
+ }
+ ...
+ }
+
+ ...
+}
+| Название | +Тип | +Описание | +
|---|---|---|
last-boiler-state |
+ object |
+
+ Текущий статус термостата. Термостат присылает обновлённый статус раз в минуту. Имеет следующие поля: +
|
+
Пользовательские команды и статусы (ZTC-7xx, Mega SX)
{
+ "custom_controls": [
+ { // таких блоков может быть несколько
+ "statuses": [
+ {
+ "id": 0,
+ "type": "status",
+ "name": "Насос"
+ }
+ ],
+ "commands": [
+ {
+ "id": 0,
+ "type": "command",
+ "name": "Включить насос"
+ },
+ {
+ "id": 1,
+ "type": "command",
+ "name": "Выключить насос"
+ }
+ ]
+ }
+ ],
+
+ "io": {
+ "custom_controls_state": {
+ "0": 1,
+ "1": 1
+ ...
+ }
+
+ ...
+ }
+
+ ...
+}
+Настройки
+| Название | +Тип | +Описание | +
|---|---|---|
custom_controls |
+ array |
+
+ Данные о пользовательских командах и статусах, задаваемых в настроечной утилите. Массив элементов, каждый из которых представляет собой ноль или более кнопок и не более одного статуса, сгруппированные в один графический элемент интерфейса (кнопку или индикатор). + +Каждый объект имеет следующие поля: + +
Статус — это некоторое состояние устройства, которое может принимать значения 0 или 1 (например, 0 — свет не горит, 1 — свет горит). Команда — запрос устройству на выполнение какого-то действия (например, включить свет) + +Каждая команда или статус имеют следующие поля: + +
Отправить устройству команду из списка можно с помощью метода send_custom_command. + |
+
Состояния
+| Название | +Тип | +Описание | +
|---|---|---|
custom_controls_state |
+object |
+Текущие значения пользовательских статусов (см. настройку custom_controls). Имеет форму {"0": 1, "1": 1, ...}. Каждому идентификатору статуса ставится в соответствие 0 или 1 в зависимости от текущего значения этого статуса в устройстве. |
+
Получение архивов данных
+С помощью API вы можете запросить выгрузку архива со всеми данными по устройству за нужный период времени.
+ +Чтобы получить архив, нужно сначала запросить его создание методом generate_archive,
+а затем скачать полученный файл с помощью метода download_generated_archive.
generate_archive — создать архив
curl 'https://my.zont.online/api/generate_archive' \
+ -u 'demo:demo' \
+ -H 'X-ZONT-Client: your@email.com' \
+ -H 'Content-Type: application/json' \
+ -d '{"device_id": 1209, "split_by": "days",
+ "mintime": 1486252800, "maxtime": 1486339200}'
+import requests
+
+url = 'https://my.zont.online/api/generate_archive'
+data = {
+ 'device_id': 1209,
+ 'mintime': 1486252800,
+ 'maxtime': 1486339200,
+ 'split_by': 'days'
+}
+
+headers = {'X-ZONT-Client': 'your@email.com'}
+result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$url = 'https://my.zont.online/api/generate_archive';
+$data = array(
+ 'device_id' => 1209,
+ 'mintime' => 1486252800,
+ 'maxtime' => 1486339200,
+ 'split_by' => 'days'
+);
+
+$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
+$options = array('auth' => array('demo', 'demo'));
+$request = Requests::post($url, $headers, json_encode($data), $options);
+$response = json_decode($request->body, true);
+++Результат:
+
{
+ "ok": true,
+ "archive_id": "58f4b58205b605000733f5c6"
+}
+POST https://my.zont.online/api/generate_archive
Запросить создание файла с архивом данных.
+Параметры
+| Имя | +Тип | +Обязательный | +Описание | +
|---|---|---|---|
device_id |
+int |
+да | +ID устройства | +
mintime |
+int |
+да | +Начало временного диапазона (включительно) | +
maxtime |
+int |
+да | +Конец временного диапазона (включительно) | +
split_by |
+string |
+да | +Интервал разбиения данных по файлам в архиве. "days" — отдельные файлы на каждый день, "months" — отдельные файлы на каждый месяц. |
+
Время указывается в целых секундах, прошедших с 1970-01-01 00:00:00 (UTC). Не забудьте сделать поправку на нужный часовой пояс!
+Результат
+Ответ будет содержать поле archive_id, содержащее уникальный строковый идентификатор созданного архива.
+Этот идентификатор нужно указать в методе download_generated_archive чтобы скачать
+файл архива.
download_generated_archive — скачать файл архива
curl 'https://my.zont.online/api/download_generated_archive?archive_id=58f4b58205b605000733f5c6' \
+ -u 'demo:demo' >archive.zip
+import requests
+
+url = 'https://my.zont.online/api/download_generated_archive'
+data = {'archive_id': '58f4b58205b605000733f5c6'}
+result = requests.get(url, data, auth=('demo', 'demo'))
+with open('archive.zip', 'wb') as f:
+ f.write(result.content)
+<?php
+require_once 'Requests.php';
+Requests::register_autoloader();
+
+$archive_id = '58f4b58205b605000733f5c6';
+$url = 'https://my.zont.online/api/download_generated_archive?archive_id=' . $archive_id;
+$options = array('auth' => array('demo', 'demo'));
+$response = Requests::get($url, array(), $options);
+file_put_contents('archive.zip', $response->body);
+++ +Результат будет записан в файл
+archive.zip
GET https://my.zont.online/api/download_generated_archive
Скачать файл, созданный методом generate_archive. Обратите внимание, этот метод
+работает по запросу GET.
Параметры
+| Имя | +Обязательный | +Описание | +
|---|---|---|
| archive_id | +да | +идентификатор архива | +
Результат
+В ответ сервер отправит zip-архив с данными.
+ +