Getting device states (get state)

Last updated on June 17, 2024

The vendor queries the states of the user's devices. The Sber Smart Home returns the states of the devices.

Example of a usage situation:

1. The vendor periodically queries the states of the user's devices from the Sber Smart Home — this is necessary to show up-to-date information in the vendor's application.
2. The Sber Smart Home returns the states of the user's devices.
3. The vendor updates its database and shows 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/state?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>		A list of device IDs in the vendor's system, the state of which needs to be returned. If not specified, the state of all user devices will be returned

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 device states (see Device state (state))

{
    "devices": {
        "id1": {
            "states": [
                {
                    "key": string,
                    "value": {
                        "type": string,
                        "type_value": object
                    }
                },
                {
                    // ...
                }
            ]
        }
    }
}

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 respons

Last updated on June 17, 2024

The vendor queries the state of the user's socket. The socket has the functions online and on_off, the Sber Smart Home returns their state.

Query:

curl -i -X GET /v1/state?user_id=AB12345&device_ids=ABCD_003 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": {
        "ABCD_003": {
            "states": [
                {
                    "key": "online",
                    "value": {
                        "type": "BOOL",
                        "bool_value": true
                    }
                },
                {
                    "key": "on_off",
                    "value": {
                        "type": "BOOL",
                        "bool_value": true
                    }
                }
            ]
        }
    }
}

Error response:

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