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.

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

Authorization тақырыбындағы API кілті.

Рұқсат: 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	No valid session or API key (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	The role or the key's scope does not allow this (`forbidden`, `key_scope_denied`, `key_route_denied`).
404	Nothing there, or not visible to the caller.
409	The installation is retired (`installation_retired`).
422	Field errors (`validation_failed`).
429	Rate limit; see `Retry-After`.
default	An error as a problem document.

Код мысалдары

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))
}