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

Передача состояния устройств (post state)

Обновлено 11 марта 2024

Вендор уведомляет умный дом Sber об изменении состояния устройства пользователя.

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

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

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

Вендор отправляет уведомление на эндпоинт умного дома Sber: https://partners.iot.sberdevices.ru/. Обратите внимание, что для обращения к облаку Sber на сервере вендора должны быть установлены российские сертификаты.

Заголовки см. в разделе Заголовки запросов.

POST /v1/state

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

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

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

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

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

HTTP/1.1 200 OK

При возникновении ошибки умный дом может возвращать:

  • Список errors, содержащий объекты error. Каждый объект указывает на конкретные устройства, обновить состояние которых не удалось.
  • Общую ошибку common error. Описывает проблему в целом и отправляется, только если проблему не удалось соотнести с конкретными устройствами.

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

Ошибка конкретного устройства:

{
"errors": [
{
"id": string,
"code": integer,
"message": string
}
]
}

Общая ошибка:

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

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

Вендор уведомляет об изменении состояния функций online и on_off розетки.

Запрос:

curl -i -X POST /v1/devices HTTP/1.1 \
-H Host: example.com \
-H Content-Type: application/json \
-H Authorization: Bearer qwerty-1234-... \
-H X-Request-Id: abcd-0000-ifgh-...
{
"devices": [
"ABCD_003": {
"states": [
{
"key": "online",
"value": {
"type": "BOOL",
"bool_value": true
}
},
{
"key": "on_off",
"value": {
"type": "BOOL",
"bool_value": true
}
}
]
}
]
}

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

HTTP/1.1 200 OK

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

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