Device state change request (post command)

Last updated on June 17, 2024

Sber Smart Home queries the vendor for changing a device status.

Sample case:

1. A user in Salute mobile app, SberPortal, SberBox, or another device supported with Salute assistants changes the state of a lamp, for example, turns it off.
2. Sber Smart Home posts to the vendor a command to change the lamp status.
3. The vendor receives the command and sends a shutdown command to the lamp. The user lamp goes out.

Query format

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

POST /v1/command

Query body:

Field	Type	Mandatory?	Description
devices	dict<string, object>	✔︎	Devices to change their status. For each device, the device ID in the vendor's system and the updated status of its functions are returned
ID	string	✔︎	Device ID in the vendor's system
states	list<object>	✔︎	List of updated states (see Device state (state))

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

Response format

The response can be blank or include updated states of devices. For example, if the device state does not change immediately when the curtains are opened - then it is better to return an empty response first and update the state later using the post state method.

Blank response:

{}

Response containing updated device states:

Field	Type	Mandatory?	Description
devices	dict<string, object>	✔︎	Devices with their state updated For each device, the device ID in the vendor's system and the updated status of its functions are returned
ID	string	✔︎	Device ID in the vendor's system
states	list<object>	✔︎	List of current states (see Device state (state))

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

If an error occurs, the endpoint may return:

• A list of errors containing error objects. Each object points to specific devices whose status could not be updated.
• A common error that describes the problem as a whole and is returned when the problem cannot be juxtaposed with specific devices.

When the Sber Smart Home returned the statuses of several devices and the vendor could change the statuses of some of them, but an error occurred when updating the rest, an error response should be sent, including the list of devices with their statuses 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

Sber Smart Home queries for a change in the socket status.

Query:

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

{
    "devices": {
        "ABCD_003": {
            "states": [
                {
                    "key": "on_off",
                    "value": {
                        "type": "BOOL",
                        "bool_value": true
                    }
                }
            ]
        }
    }
}

Success response:

{
    "devices": {
        "ABCD_003": {
            "states": [
                {
                    "key": "on_off",
                    "value": {
                        "type": "BOOL",
                        "bool_value": true
                    }
                }
            ]
        }
    }
}

Error response:

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