Update device models (put models)

Last updated on May 25, 2023

The vendor sends to Sber Smart Home an up-to-date information about the vendor’s device models.

Sample case:

1. The vendor has changed the specifications of a device model. For example, all devices now have a new version of the firmware.
2. The vendor notifies Sber Smart Home of a change in a user's device model.
3. Sber Smart Home updates the model information in its database.

Query format

The vendor sends a notification to Sber Smart Home endpoint: https://partners.iot.sberdevices.ru/. Please note that in order to access the Sber cloud, Russian certificates must be installed on vendor's server.

For the headers, see Query headers.

PUT /v1/models

Query body:

Field	Type	Mandatory?	Description
models	list<object>	✔︎	List of device models (see Device model (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
                    },
                },
                {
                    // ...
                }
            }
        },
        {
            // ...
        }
    ]
}

Response format

Sber Smart Home sends a response to the vendor's endpoint. For the headers, see Query headers.

Success response:

HTTP/1.1 200 OK

If an error occurs, the endpoint may return:

• A list of errors containing error objects. Each object points to specific models with their updating unsuccessful.
• A common error. that describes the problem as a whole and is returned when the problem cannot be juxtaposed with specific models.

If the vendor notified of several models, and Sber Smart Home has managed to update some of them, but an error occurs when updating the rest, Sber Smart Home will send an error response containing a list of models not updated.

Device-specific error:

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

Common error:

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

Sample query and response

The vendor notifies Sber Smart Home that a model of smart socket has been updated.

Query:

curl -i -X PUT /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": "Smart socket 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"
                    }
                }
            }
        }
    ]
}

Success response:

HTTP/1.1 200 OK

Error response:

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