Добавление моделей устройств (post models)

Обновлено 22 мая 2023

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

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

1. Вендор начал производить или продавать в России новую модель устройства: лампочку, розетку или другое.
2. Вендор уведомляет умный дом Sber о новой модели устройства.
3. Умный дом Sber добавляет новую модель устройства в свою базу.

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

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

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

POST /v1/models

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

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

{
    "models": [
        {
            "id": string,
            "manufacturer": string,
            "model": string,
            "hw_version": string,
            "sw_version": string,
            "description": string,
            "category": string,
            "features": [
                string,
                string,
                // ...
            ],
            "dependencies": {
                "func_name": {
                    "key": string,
                    "value": [
                        {
                            "type": string,
                            "type_value": object
                        },
                        {
                            // ...
                        }
                    ]
                }
            },
            "allowed_values": {
                "func_name": {
                    "type": string,
                    "type_values": {
                        "min": object,
                        "max": object,
                        "step": 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>
}

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

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

Запрос:

curl -i -X POST /v1/models HTTP/1.1 \
-H Host: example.com \
-H Content-Type: application/json \
-H Authorization: Bearer qwerty-1234-... \
-H X-Request-Id: abcd-0000-ifgh-...

{
    "models": [
        {
            "id": "QWERTY123",
            "manufacturer": "Xiaqara",
            "model": "SM1123456789",
            "hw_version": "3.1",
            "sw_version": "5.6",
            "description": "Умная розетка Xiaqara",
            "category": "socket",
            "features": [
                "online",
                "on_off",
                "sleep_timer",
                "child_lock",
                "current",
                "power",
                "voltage"
            ],
            "allowed_values": {
                "power": {
                    "type": "INTEGER",
                    "integer_values": {
                        "min": "10",
                        "max": "45000",
                        "step": "1"
                    }
                }
            }
        }
    ]
}

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

HTTP/1.1 200 OK

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

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