Acknowledge a relayed command for one structure

POST /api/v1/cms/commands/{id}/acks

https://app.tanba-ooh.kz/api/v1/cms/commands/{id}/acks

Технический текст справочника написан на английском.

Scope relay:commands. Operator organisations only. Say what became of the command on one structure of the installation: ok true once it is executed, false with a short error when it could not be. The platform records the time from the signature to this call, shows it on the delivery board as relayed and not verified on the device, and, for an executed cut-off or restore, updates the state of the structure's players. An answer for a structure that was never handed this command is not found. A second answer for the same structure is ignored and returns the first. When ok is true, state must be the state the command sets: blackout after a cut-off, default after a restore, the scenario named in the command after a content switch or emergency broadcast; any other state is refused with 422.

Аутентификация

Ключ API в заголовке Authorization.

Право доступа: relay:commands

Параметры

Имя	Где	Тип	Обязательный	Описание	Пример
`id`	путь	string (uuid)	да	Identifier of the command.	`01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd`
`installation`	запрос	string (uuid)	да	Identifier of the registered CMS installation.	`5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50`

Тело запроса

`application/json`

Имя	Тип	Обязательный	Описание	Пример
`structure`	string	да	Code of the structure.	`"ALM-0012"`
`ok`	boolean	да	True when the command was executed on the structure's players.	`true`
`state`	string		State the players are in now, for example `blackout` or `default`.	`"blackout"`
`error`	string		Why the command could not be executed; empty on success.	`""`

Пример

{
  "structure": "ALM-0012",
  "ok": true,
  "state": "blackout"
}

Ответы

200 The answer was recorded, or an earlier one is returned.

`application/json`

Имя	Тип	Обязательный	Описание	Пример
`command_id`	string (uuid)	да	Identifier of the command.	`"01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd"`
`structure`	string	да	Code of the structure.	`"ALM-0012"`
`ok`	boolean	да	The recorded outcome.	`true`
`acked_at`	string (date-time)	да	When the answer was recorded.	`"2026-10-14T09:00:07+05:00"`
`acked_in_s`	integer	да	Seconds from the signature of the command to the answer.	`7`

Пример

{
  "command_id": "01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd",
  "structure": "ALM-0012",
  "ok": true,
  "acked_at": "2026-10-14T09:00:07+05:00",
  "acked_in_s": 7
}

Ошибки

Ошибки приходят документом problem (application/problem+json) со стабильным полем code.

Статус	Значение
401	Нет действительной сессии или ключа API (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	Роль или право ключа этого не допускает (`forbidden`, `key_scope_denied`, `key_route_denied`).
404	Ничего нет или вызывающему это не видно.
409	The installation is retired (`installation_retired`).
422	Ошибки полей (`validation_failed`).
429	Превышен предел частоты; см. `Retry-After`.
default	Ошибка в виде документа problem.

Примеры кода

curl

curl -X POST 'https://app.tanba-ooh.kz/api/v1/cms/commands/01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd/acks?installation=5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "structure": "ALM-0012",
  "ok": true,
  "state": "blackout"
}'

Python

import requests

response = requests.post(
    "https://app.tanba-ooh.kz/api/v1/cms/commands/01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd/acks?installation=5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "structure": "ALM-0012",
        "ok": True,
        "state": "blackout",
    },
)
print(response.status_code, response.text)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "structure": "ALM-0012",
  "ok": true,
  "state": "blackout"
}`)
	req, err := http.NewRequest("POST", "https://app.tanba-ooh.kz/api/v1/cms/commands/01a1377e-c8e3-7c41-8ae9-3a8dc9413fbd/acks?installation=5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}