Обновление устройств пользователя (put devices)

Обновлено 4 августа 2023

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

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

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

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

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

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

PUT /v1/devices

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

Поле	Тип	Обязательное?	Описание
devices	list<object>	✔︎	Список устройств (см. Устройство пользователя (device))

{
    "devices": [
        {
            "id": string,
            "parent_id": string,
            "name": string,
            "default_name": string,
            "nicknames": [
                string,
                string
                // ...
            ],
            "home": string,
            "room": string,
            "groups": [
                string,
                string
                // ...
            ],
            "model_id": string,
            "hw_version": string,
            "sw_version": string,
            "partner_meta": {
                "key": value,
                "key": value,
                // ...
            },
        },
        {
            // ...
        }
    ]
}

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

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

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

 HTTP/1.1 200 OK

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

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

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

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

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

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

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

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

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

Запрос:

curl -i -X PUT /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": [
        {
            "id": "ABCD_003",
            "name": "Моя лампа",
            "default_name": "Умная лампа",
            "nicknames": [
                "Светодиодная лампа",
                "Смарт-лампа"
            ],
            "home": "Мой дом",
            "room": "Гостиная",
            "groups": [
                "Верхний свет",
                "Ниша"
            ],
            "model_id": "QWERTY123",
            "hw_version": "3.2",
            "sw_version": "5.7",
            "partner_meta": {
                "internal-id": 1234,
                "specificity": "microchip 2A"
            },
        }
    ]
}

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

HTTP/1.1 200 OK

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

{
    "errors": [
        {
            "id": "ABCD_003",
            "code": 500,
            "message": "System error"
        }
    ]
}