Get the user’s device list (get devices)

Last updated on May 25, 2023

The vendor queries for a list of the user's devices. Sber Smart Home returns the list.

Sample case:

1. From time to time, the vendor queries Sber Smart Home for a list of user devices - it is needed to show an up-to-date information in the vendor's app.
2. Sber Smart Home returns the list of user devices.
3. The vendor updates its database and shows the up-to-date information in its application.

Query format

The vendor sends a query 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.

GET /v1/devices?user_id=<string>&device_ids=<device_ids>

Query parameters:

Field	Type	Mandatory?	Description
user_id	string	✔︎	User ID in the vendor’s system Sber Smart Home gets IDs during account linking and then stores them (see the Request user information (get user) method)
device_ids	list<string>		List of device IDs in the vendor's system. It is posted when the vendor needs to know whether a user of Sber Smart Home has any specific devices. For example, if the vendor wants to make sure that certain devices have been added to Sber Smart Home

Response format

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

Success response:

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

If an error occurs, you must return an object of the Common error (common error) type:

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

Sample query and response

Last updated on May 25, 2023

The vendor queries for a list of the user's devices. Sber Smart Home returns a list of two devices: a socket and a lamp.

Query:

curl -i -X GET /v1/devices?user_id=AB12345 HTTP/1.1 \
-H Host: example.com \
-H Content-Type: application/json \
-H Authorization: Bearer qwerty-1234-... \
-H X-Request-Id: abcd-0000-ifgh-...

Success response:

{
    "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"
            },
        },
        {
            "id": "ABCD_004",
            "name": "My outlet",
            "default_name": "Smart outlet",
            "nicknames": [
                "Smart socket",
                "Controlled socket"
            ],
            "home": "My home",
            "room": "Living room",
            "groups": [
                "Video equipment",
                "Sound"
            ],
            "model_id": "QWERTY124",
            "hw_version": "3.1",
            "sw_version": "5.6",
            "partner_meta": {
                "internal-id": 1235,
            },
        },
    ]
}

Error response:

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