TAŇBA-OOH Developers

Connecting a CMS

A commercial CMS can drive TAŇBA-OOH structures once it is certified against the CMS profile (levels C1 and C2). This guide covers the three calls it makes and the one rule it must never break. The full requirement list is in the CMS profile document.

Register once, in the console

An administrator of the operator organisation does this in Integrations:

  1. Registers a signing source for the installation (name, kind and the ECDSA P-256 public key of the CMS). One source serves one installation.
  2. Registers the installation: the source, the certificate number of the certified product, the version in use, the base address and a statement of where it is hosted.
  3. Maps every player of the CMS to one structure, and links each structure to the installation.
  4. Creates an API key with the scope relay:commands and, for plays, write:plays.

Receive the signed commands

curl 'https://app.tanba-ooh.kz/api/v1/cms/commands?installation=5d0c8e7a-21b4-4c3f-9a6e-0b1d2c3e4f50&wait=30' \
  -H 'Authorization: Bearer tnbk_EXAMPLE_secret'

Call it in a loop with wait=30, or on the device_command.issued webhook. Each item holds the command, the structures it applies to and the signed envelope. The platform has already checked the envelope against the command roots; a CMS should check it too. Execute the command on the players of every listed structure within 60 seconds of receiving it, then acknowledge each structure:

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 tnbk_EXAMPLE_secret' -H 'Content-Type: application/json' \
  -d '{"structure": "ALM-0012", "ok": true, "state": "blackout"}'

A command is handed out again after 5 minutes if it is not acknowledged, and fails after the third try. The platform shows the result as relayed and not verified on the device.

The switch key belongs to the authority

A cut-off writes the player key switch to blackout, a restore writes default, and an emergency broadcast or content switch writes the scenario name. Only the code that executes relayed commands may write switch. No other CMS function, such as resume, pause, publish, its own blackout or emergency, or a restart, may write it or lift a blackout. A CMS that does is not certified.

Report plays

Plays go to the signed batch channel, POST /api/v1/pop/batches, with the scope write:plays and a signature made with the key of the installation's source. See the proof of play reference for the batch format. Such plays are attested: reported by the operator's system and signed, not seen on the device.