ym88659208ym87991671
Request to change the device status (post command) | Documentation SmartMarket
Skip to main content

Request to change the device status (post command)

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:

FieldTypeMandatory?Description
devicesdict<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
stateslist<object>✔︎List of updated states (see Device state (state))
{
"devices": {
"id": {
"states": [
{
"key": string,
"value": {
"type": string,
"type_value": object
}
},
{
// ...
}
]
}
}
}

Response format

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

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 state method.

Blank response:

{
}

Response containing updated device states:

FieldTypeMandatory?Description
devicesdict<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
stateslist<object>✔︎List of current states (see Device state (state))
{
"devices": {
"id": {
"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 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": "online",
"value": {
"type": "BOOL",
"bool_value": true
}
},
{
"key": "on_off",
"value": {
"type": "BOOL",
"bool_value": true
}
}
]
}
}
}

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:

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