DaSens API

Программный доступ к телеметрии приборов, объектам, простоям и нарядам. Тот же сервис, что и кабинет, — но здесь его машинная сторона.

Ищете кабинет? Он на lk.dasens.ru — графики, события, простои, наряды. Эта страница нужна, только если вы подключаете к DaSens свою программу.

Интерактивная документация openapi.json Проверка живости

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

Как войти

Два способа, и выбирать между ними не нужно: человек входит сессией, программа — ключом.

Способ	Кому	Как
Сессия	человеку в браузере	`POST /api/v1/auth/login` — дальше кука `ds_session`, 30 дней, отзывается из панели
Ключ программы	интеграции, скрипту, дашборду	заголовок `X-API-Key`. Ключ выдаётся в панели («Люди и доступы» → «Ключи для программ») и показывается один раз

curl -H "X-API-Key: ВАШ_КЛЮЧ" https://api.dasens.ru/api/v1/devices

Что ключ НЕ может — намеренно.

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

Потерянный ключ отзывается в панели одной кнопкой и перестаёт работать сразу.

Что можно

Раздел	О чём
`/api/v1/telemetry`	последние значения, выборка за период, приём замеров
`/api/v1/assets`	объекты оборудования, площадки и линии, события, простои и их причины
`/api/v1/devices`	приборы, их состояние в парке, привязка по коду
`/api/v1/work`	наряды: создание, приоритеты, наряд из простоя
`/api/v1/notify`	каналы уведомлений и проверка связи по ним
`/api/v1/inventory`	платы, датчики, размещения
`/api/v1/auth`	вход, сессии, ключи, доступы к организациям
`/api/v1/errors`	панель ошибок; сюда же браузер клиента шлёт свои сбои

Полный список с параметрами и примерами ответов — в интерактивной документации, она открывается после входа.

Правила, о которые спотыкаются

Время — UTC	всегда и везде, включая ответы. Часовой пояс — свойство площадки, а не сервера: прибор в Красноярске и прибор в Краснодаре пишут в одну шкалу, иначе их не сравнить.
Деньги — целыми	в минорных единицах (копейках) плюс код валюты. Дробных рублей в API нет: округление, случившееся дважды, — это расхождение в отчёте.
Чужое — 404	не 403. «Нет прав на объект X» само по себе подтверждает, что X существует; перебором идентификаторов так составляется карта чужого парка.
Версия в пути	`/api/v1`. Ломающие изменения поедут в `/api/v2`, старая версия не исчезнет молча.

Приборы приходят сюда сами

Прибор DaSens за NAT снаружи видит только этот адрес. По нему он знакомится с облаком (получает свой доступ к брокеру) и скачивает образ прошивки, когда его обновляют по воздуху. Эти два маршрута предназначены приборам, а не людям, и в документации не показаны.

Телеметрия приборов идёт не сюда, а на mqtt.dasens.ru:8883 — постоянным соединением по MQTT поверх TLS.

Если что-то не так

`401`	нет входа: не передан ключ или истекла сессия
`403`	вход есть, но прав не хватает — текст ошибки называет, каких именно
`404`	нет такого объекта или он не ваш — снаружи эти случаи неразличимы намеренно
`409`	действие противоречит состоянию: дубль, недопустимый переход, занятый номер
`429`	слишком часто
`500`	наша ошибка. Она уже записана в панель с номером обращения — назовите время запроса, и мы найдём её целиком

Ошибки отвечают JSON с полем detail — текстом по-русски, пригодным для показа человеку.

DaSens · dasens.ru · кабинет · вопросы по интеграции — sales@dasens.ru