ym88659208ym87991671
Запрос состояния устройств (post query) | Документация для разработчиков

Запрос состояния устройств (post query)

Обновлено 30 мая 2024

Умный дом Sber запрашивает у вендора актуальное состояние устройств пользователя. Ответ должен содержать все заявленные функции устройства.

Пример ситуации использования:

  1. Пользователь в приложении вендора изменяет состояние какого-либо устройства. Например, выключает лампочку или меняет ее цвет.
  2. Умный дом периодически запрашивает у вендора состояние устройств пользователя.
  3. Вендор возвращает актуальное состояние устройств, включая текущее состояние лампочки.
  4. Умный дом Sber актуализирует состояние лампочки в приложении Салют, приложении СберБанк Онлайн, на SberPortal, SberBox и других устройствах с ассистентом Салют.

Формат запроса

Умный дом отправляет запрос на эндпоинт вендора. Заголовки см. в разделе Заголовки запросов.

POST /v1/query

Тело запроса:

ПолеТипОбязательное?Описание
deviceslist<string>✔︎Список идентификаторов устройств, состояние которых нужно вернуть
{
"devices": [
"device1_id": string,
"device2_id": string,
"device3_id": string
]
}

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

Успешный ответ:

ПолеТипОбязательное?Описание
devicesdict<string, object>✔︎Список устройств пользователя. Для каждого устройства передаются ID устройства в системе вендора и состояние его функций
IDstring✔︎ID устройства в системе вендора
stateslist<object>✔︎Список состояний функций (см. Состояние устройства (state))
{
"devices": {
"id1": {
"states": [
{
"key": string,
"value": {
"type": string,
"type_value": object
}
},
{
// ...
}
]
}
}
}

При возникновении ошибки нужно возвращать объект типа common error:

{
"code": integer,
"message": string,
"details": list<string>
}

Пример запроса и ответа

Умный дом запрашивает у вендора состояние розетки. Вендор возвращает его.

Запрос:

curl -i -X POST /v1/query \
-H Host: example.com \
-H Content-Type: application/json \
-H Authorization: Bearer qwerty-1234-... \
-H X-Request-Id: abcd-0000-ifgh-...
{
"devices": ["ABCD_003"]
}

Успешный ответ:

{
"devices": {
"ABCD_003": {
"states": [
{
"key": "online",
"value": {
"type": "BOOL",
"bool_value": true
}
},
{
"key": "on_off",
"value": {
"type": "BOOL",
"bool_value": true
}
}
]
}
}
}

Ответ с ошибкой:

{
"code": 400,
"message": "Invalid argument",
"details": []
}
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.