Запрос всех устройств пользователя и их функций (get devices)

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

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

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

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

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

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

GET /v1/devices

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

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

Поле	Тип	Обязательное?	Описание
devices	list<objects>	✔︎	Список устройств (см. Устройство пользователя (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,
                // ...
            },
        },
        {
            // ...
        }
    ]
}

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

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

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

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

Запрос:

curl -i -X GET /v1/devices \
-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"
            },
        },
        {
            "id": "ABCD_004",
            "name": "Моя розетка",
            "default_name": "Умная розетка",
            "nicknames": [
                "Смарт-розетка",
                "Управляемая розетка"
            ],
            "home": "Мой дом",
            "room": "Гостиная",
            "groups": [
                "Видеотехника",
                "Звук"
            ],
            "model_id": "QWERTY124",
            "hw_version": "3.1",
            "sw_version": "5.6",
            "partner_meta": {
                "internal-id": 1235,
            },
        },
    ]
}

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

{
    "code": 400,
    "message": "Invalid argument",
    "details": []
}