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

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

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

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

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

Вендор отправляет уведомление на эндпоинт умного дома Sber: https://partners.iot.sberdevices.ru/. Заголовки см. в разделе Заголовки запросов.

POST /v1/devices

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

Поле Тип Обязательное? Описание
user_id string ✔︎ Идентификатор пользователя. Умный дом получает ID при связывании аккаунтов и затем хранит их (см. метод Запрос информации о пользователе (get user))
devices list<object> ✔︎ Список добавленных устройств (см. Устройство пользователя (device))
{
    "user_id": string,
    "devices": [
        {
            "id": string,
            "name": string,
            "default_name": string,
            // ...
        },
        {
            "id": string,
            "name": string,
            "default_name": string,
            // ...
        },
    ]
}

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

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

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

HTTP/1.1 200 OK

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

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

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

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

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

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

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

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

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

Запрос:

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-...
{
    "user_id": AB12345
    "devices": [
        {
        "id": "ABCD_005",
        "name": "Ночник",
        "default_name": "Умная лампа"
        }
    ]
}

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

HTTP/1.1 200 OK

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

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

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней