API Telemat: интеграция приборов мониторинга с вашим ПО

Показания приборов Telemat можно получать не только в приложении, но и в собственном программном обеспечении: в системе диспетчеризации, учётной системе или на внутреннем информационном табло. Для этого есть API — обычный HTTPS-запрос, который возвращает текущие данные ваших приборов в формате JSON.

Так один и тот же GSM-датчик температуры работает и как самостоятельный прибор с push-уведомлениями, и как источник данных для вашей системы удалённого мониторинга. По каждому каналу вы получаете последнее значение, а по прибору — статус (на связи, нет сигнала, обслуживание не оплачено), источник питания и уровень сигнала сети. Как показывать эти данные и что с ними делать, решаете вы.

Ключ доступа владелец приборов создаёт в мобильном приложении Telemat. Ключ открывает только те приборы, которые привязаны к его владельцу. Прибору по-прежнему не нужны SIM-карта и интернет на объекте: он сам передаёт показания на сервер, а ваша система читает их оттуда. Серверы находятся в России.

Ключ запрашивается только в мобильном приложении. У владельца может быть только один ключ: при запросе нового ключа прежний удаляется и перестаёт работать.

API работает только на чтение: получить показания можно, управлять прибором и менять уставки — нельзя.

Текущая температура на сайте: пивной бар, сауна, баня

С помощью API можно выводить текущую температуру прямо на сайте. Пивной бар покажет гостям температуру в холодильнике с разливным пивом, сауна или баня — что парная уже прогрелась и можно приходить. Так же можно показывать температуру воды в бассейне или купели, в оранжерее, на винном складе или в погребе — везде, где посетителю интересно знать, что там сейчас. Это справочное значение для посетителей, а не показание поверенного прибора.

Схема простая. Прибор передаёт показания на сервер Telemat раз в минуту, сервер вашего сайта запрашивает их через API и отдаёт посетителям готовое значение. Три правила, чтобы всё работало надёжно:

запрашивайте API на сервере вашего сайта, а не в браузере посетителя: ключ — секрет, и в коде страницы его увидит любой;
сохраняйте полученное значение и показывайте посетителям его: лимит API — 2 запроса в минуту на ключ, и он не должен зависеть от числа посетителей сайта;
если status не ok или value равно null, покажите «нет данных», а не ноль и не прошлое значение.

Датчики Telemat как дополнительный сигнал для SCADA-систем

Благодаря API датчики Telemat можно использовать как дополнительный сигнал для SCADA-систем, АСУ ТП и диспетчеризации. SCADA или диспетчерская система периодически запрашивает показания по HTTPS и получает их в JSON: значение по каждому каналу прибора, статус (на связи, нет сигнала, обслуживание не оплачено), источник питания и уровень сигнала сети. В системе эти данные появляются рядом с сигналами штатных датчиков и контроллеров и участвуют в тех же экранах, трендах и тревогах.

Дополнительный канал телеметрии нужен там, где штатный контроль уже есть, а объект удалён или проводная связь до него неудобна: склад, холодильная камера, насосная станция, теплица, сервисный объект без выделенной сети. GSM-датчик температуры сам передаёт показания на сервер Telemat, поэтому ему не нужны SIM-карта, Wi-Fi и роутер на объекте. Прокладывать кабель до диспетчерской не надо, а удалённый мониторинг температуры по независимому каналу связи добавляется поверх существующей автоматики. Telemat не заменяет штатный контроль, а дополняет его.

Для подключения нужна SCADA-система или шлюз, которые умеют отправлять HTTP-запросы с заголовком Authorization и разбирать JSON. Каналы прибора заводятся в системе как обычные сигналы, а опрос идёт не чаще двух раз в минуту. Правила те же, что и для сайта: если status не ok или value равно null, отметьте сигнал как недостоверный, а не записывайте ноль. API работает только на чтение: уставки и управление оборудованием остаются в вашей системе.

Инструкция по API

Документ для разработчика, который подключает своё программное обеспечение к показаниям приборов Telemat. Он не связан с мобильным приложением и имеет отдельный, стабильный контракт.

Базовый адрес

https://lk.telemat.su

Все пути ниже указаны относительно этого адреса: GET /api/external/v1/devices означает GET https://lk.telemat.su/api/external/v1/devices.

Получение ключа

Ключ запрашивается только в мобильном приложении Telemat версии не ниже 2.0.11, самим владельцем приборов: раздел «Датчик» → кнопка «Ключ API» → «Создать ключ». Ключ:

привязан к конкретному, уже вошедшему в приложение пользователю;
даёт доступ только к тем приборам, которые привязаны к этому пользователю в приложении, — ни к каким другим, и только на чтение;
показывается один раз, в момент создания: восстановить показанное значение нельзя;
не имеет срока действия — работает, пока его не заменят или не отзовут.

У владельца всегда не больше одного действующего ключа. Каждый новый запрос ключа в приложении удаляет прежний и выдаёт новый, без дополнительного подтверждения: старый ключ перестаёт работать сразу. Поэтому после выпуска нового ключа обновите его во всех системах, где использовался старый. Если ключ потерян, запросите новый.

Отозвать ключ без замены можно в том же окне приложения («Отозвать ключ»). Там же видны дата создания ключа и дата последнего использования; сам ключ повторно не показывается.

Авторизация

Ключ передаётся в заголовке запроса:

Authorization: Bearer <ваш ключ>

Если ключ неверный, отозван, заменён новым или не передан, сервер ответит 401. Если передан ключ, не предназначенный для внешнего API (например, случайно подставили не тот токен), — 403.

Получение данных

GET /api/external/v1/devices
GET /api/external/v1/devices?deviceId=6525600
GET /api/external/v1/devices?deviceId=6525600,4444445

Без параметра deviceId возвращаются данные по всем приборам, привязанным к ключу. С параметром — только по указанным серийным номерам (один или несколько через запятую).

Пример ответа

{
  "code": 200,
  "message": null,
  "paginate": null,
  "result": {
    "devices": [
      {
        "deviceId": "6525600",
        "status": "ok",
        "power": "mains",
        "signalLevel": 4,
        "channels": [
          { "channelId": 1, "value": 21.3, "unit": "°C" },
          { "channelId": 3, "value": 7.5, "unit": "°C" }
        ]
      }
    ]
  }
}

Поля

Поле	Тип	Описание
`deviceId`	строка	Серийный номер прибора (тот, что на корпусе), а не внутренний технический идентификатор
`status`	строка	Статус прибора, см. таблицу ниже
`power`	строка или `null`	Источник питания, см. таблицу ниже. `null` — данные ещё не поступали
`signalLevel`	число 0–5 или `null`	Уровень сигнала сети, «палки». `null` — нет данных
`channels`	массив	Один элемент на каждый измерительный канал прибора. У большинства приборов сегодня канал один
`channels[].channelId`	число	Стабильный номер канала на этом приборе
`channels[].value`	число или `null`	Последнее известное значение. `null` — либо показаний нет вообще, либо последнее показание было с ошибкой датчика. В обоих случаях достоверного значения сейчас нет: не подставляйте вместо него 0 или прошлое значение
`channels[].unit`	строка	Единица измерения (`°C` и т. п.)

Статусы прибора (`status`)

Код	Значение
`ok`	Прибор в норме, данные свежие
`no_signal`	Прибор не выходит на связь
`battery_low_signal`	Прибор не выходит на связь, вероятная причина — разряженная батарея
`pay_over`	Обслуживание прибора не оплачено, данные не поступают
`decommissioned`	Прибор выведен из эксплуатации
`new`	Прибор ещё не активирован
`setup`	Идёт первичная настройка после активации

Список кодов может дополняться новыми значениями. Код, который обрабатывает ответ, не должен падать на незнакомом значении status: достаточно относиться к нему как к «не ok».

Источник питания (`power`)

Код	Значение
`mains`	Работает от сети 220 В
`battery_full`	От встроенной батареи, заряд высокий
`battery_half`	От встроенной батареи, заряд средний
`battery_low`	От встроенной батареи, заряд низкий

Ограничение частоты запросов

Не более 2 запросов в минуту на один ключ. Показания на приборе обновляются раз в минуту, поэтому опрашивать чаще нет смысла: более свежих данных вы не получите. Лимит рассчитан с небольшим запасом на возможное расхождение часов между вашей системой и сервером, не больше.

При превышении лимита сервер отвечает 429 — подождите и повторите запрос не раньше, чем через несколько секунд.

Ошибки

Все ошибки возвращаются в общем формате:

{ "code": 403, "message": "текст ошибки", "paginate": null, "result": null }

HTTP-код	Причина
`401`	Ключ не передан или недействителен (в том числе отозван или заменён новым)
`403`	Ключ передан, но не является ключом внешнего API, либо запрошен прибор, не принадлежащий владельцу ключа
`429`	Превышена частота запросов

Что важно знать при интеграции

Значения null в power, signalLevel и channels[].value — не ошибка запроса, а честное «сейчас нет достоверных данных». Не интерпретируйте null как ноль.
Ошибка датчика — состояние канала, а не прибора: она видна как value: null у конкретного элемента channels, а не как отдельный код в status. Прибор при этом остаётся ok, если он на связи и всё остальное в порядке, — так же, как в приложении ошибка одного канала не окрашивает в красный весь прибор целиком.
Набор каналов может отличаться по количеству и порядку от прибора к прибору и в будущем может измениться у уже подключённого прибора (например, если владелец сменит модель). Ориентируйтесь на channelId, а не на позицию в массиве.
API — только чтение. Управлять прибором (менять настройки, уставки и т. п.) через него нельзя.