Device state (post query)

Last updated on June 17, 2024

Sber Smart Home queries a vendor for the current status of a user's devices. The response should contain all the stated functions of a device.

Sample case:

1. A user changes the status of a device in the vendor application. For example, he/she turns a light bulb off or changes its colour.
2. From time to time, Sber Smart Home queries the vendor for the current status of a user's devices.
3. The vendor returns the current state of the devices, including that of the light bulb.
4. Sber Smart Home updates the status of the light bulb in Salute mobile app, SberPortal, SberBox and other devices supported with Salute assistants.

Query format

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

POST /v1/query

Query body:

Field	Type	Mandatory?	Description
devices	list<string>	✔︎	List of device IDs to return their state

{
    "devices": [
        "device1_id": string,
        "device2_id": string,
        "device3_id": string
    ]
}

Response format

Success response:

Field	Type	Mandatory?	Description
devices	dict<string, object>	✔︎	List of the user devices. For each device, the device ID in the vendor's system and the status of its functions are returned
ID	string	✔︎	Device ID in the vendor's system
states	list<object>	✔︎	List of function 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 response

Sber Smart Home queries the vendor for the status of a socket. The vendor returns it.

Query:

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

{
    "devices": ["ABCD_003"]
}

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": []
}