Add user's devices (post devices)

Last updated on May 25, 2023

The vendor notifies Sber Smart Home that a user has added one device or more.

Sample case:

1. A user adds one or more devices in the vendor application.
2. The vendor sends a notification to Sber Smart Home about the added devices.
3. Sber Smart Home posts new devices in Salute mobile app, SberPortal, SberBox and other devices supported with Salute assistants.

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.

POST /v1/devices

Query body:

Field	Type	Mandatory?	Description
user_id	string	✔︎	User ID. Sber Smart Home gets IDs during account linking and then stores them (see the Request user information (get user) method)
devices	list<object>	✔︎	List of added devices (see User device (device))

{
    "user_id": string,
    "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,
                // ...
            },
        },
        {
            // ...
        }
    ]
}

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 devices with their adding unsuccessful.
• A common error. that describes the problem as a whole and is returned when the problem cannot be juxtaposed with specific devices.

If a vendor notified of several devices, and Sber Smart Home has managed to post some of them, but an error occurs when posting the rest, Sber Smart Home will send an error response containing a list of devices not posted.

Device-specific error:

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

General error:

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

Sample query and response

In the sample, the user adds a smart lamp. The vendor notifies Sber Smart Home about it.

Query:

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_003",
            "name": "My lamp",
            "default_name": "Smart lamp",
            "nicknames": [
                "LED lamp",
                "Smart lamp"
            ],
            "home": "My home",
            "room": "Living room",
            "groups": [
                "Overhead light",
                "Alcove"
            ],
            "model_id": "QWERTY123",
            "hw_version": "3.2",
            "sw_version": "5.7",
            "partner_meta": {
                "internal-id": 1234,
                "specificity": "microchip 2A"
            }
        }
    ]
}

Success response:

HTTP/1.1 200 OK

Error response:

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