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

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

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

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

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 самим владельцем приборов. Ключ:

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

Авторизация

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

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 — только чтение. Управлять прибором (менять настройки, уставки и т. п.) через него нельзя.