API pro propojení s vaším systémem

Technická dokumentace

Technická část pro vývojáře integrace

Nejprve se seznamte se společnými pravidly volání a přihlášením. Poté projděte postup od nahrání média po spuštění kampaně a přehled dostupných adres.

Přihlášení

Přihlašovacím jménem není e-mail, ale osmiznakový kód, který systém vygeneroval při založení uživatele, například A1B2C3D4. Pro integraci založte samostatného uživatele s minimálními nutnými oprávněními; jeho přístup pak lze kdykoli odebrat, aniž by se to dotklo ostatních uživatelů.

curl -u "A1B2C3D4:vase-heslo" https://admin.example.org/api/public/login

Heslo se odesílá s každým požadavkem. Uložte je jako tajný údaj, například v proměnné prostředí nebo trezoru hesel, nikdy ne do zdrojového kódu, repozitáře nebo logů.

Ukázky dále předpokládají nastavené proměnné:

export API="https://admin.example.org"
export AUTH="A1B2C3D4:vase-heslo"

Ukázky používají nástroj curl, protože nezávisí na programovacím jazyce. Rozhraní je běžné HTTP, lze jej proto volat z libovolného jazyka nebo nástroje s podporou Basic Auth, například Python, JavaScript, PHP, Postman nebo Make.

Postup: od souboru ke spuštěné kampani

1. Zjistěte identifikátor Společnosti. Použijete jej ve všech dalších voláních.
2. Nahrajte médium. Odpověď vrátí jeho identifikátor.
3. Načtěte šablonu kampaně. Server ji předvyplní nastavením Společnosti a seznamem lokalit a zařízení.
4. Upravte šablonu — název, termín, cílová zařízení a vizuál.
5. Založte kampaň. Vznikne jako koncept a zatím se nepřehrává.
6. Aktivujte kampaň. Systém připraví nový plán přehrávání a odešle jej na zařízení.
7. Sledujte výsledky v reportu kampaně.

1. Identifikátor Společnosti

curl -u "$AUTH" "$API/api/public/login"

Odpověď (zkráceno):

{
  "id": 1715714421868,
  "name": "Integrace – e-shop",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Reklamní agentura s.r.o." },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Hodnotu company.id si uložte, v ukázkách jako proměnnou COMPANY. Sekce permission uvádí oprávnění uživatele; jejich význam popisuje část Oprávnění.

2. Nahrání média

Soubor se odesílá jako binární tělo požadavku metodou PUT; jeho vlastnosti určují hlavičky.

curl -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: letni-vyprodej.jpg" \
  -H "file-suffix: jpg" \
  --data-binary @letni-vyprodej.jpg

Stejné volání v jazyce Python:

import requests

with open("letni-vyprodej.jpg", "rb") as f:
    r = requests.put(
        f"{API}/api/resource/single/{COMPANY}",
        auth=("A1B2C3D4", "vase-heslo"),
        headers={
            "file-type": "IMAGE",
            "file-mime": "image/jpeg",
            "file-name": "letni-vyprodej.jpg",
            "file-suffix": "jpg",
        },
        data=f,
    )
r.raise_for_status()
resource_id = r.json()["id"]

Odpověď obsahuje identifikátor média (id) a jeho typ (type); obě hodnoty použijete ve vizuálu kampaně.

{
  "id": 1724832015443,
  "type": 2,
  "name": "letni-vyprodej",
  "width": 1920,
  "height": 1080,
  "duration": 0,
  "aspectRatio": 32
}

• Velikost: běžné soubory nejvýše přibližně 1,1 GB, video s průhledností přibližně 2,1 GB. Větší soubor server odmítne kódem 413.
• Příprava videa: video se po nahrání konvertuje na pozadí. Připravené je, jakmile detail média (GET /api/resource/single/{companyId}/{id}) obsahuje vyplněnou hodnotu dt_ready. U obrázků je příprava prakticky okamžitá.
• Chybějící hlavička: bez file-mime, file-name nebo file-suffix server vrátí 204 a médium nevytvoří. Před dalším krokem proto vždy ověřte, že odpověď obsahuje id.

3. Šablona kampaně

Kampaň neskládejte ručně. Vyžádejte si šablonu, kterou server předvyplní výchozím termínem (od dnešního dne na jeden měsíc), nastavením Společnosti a seznamem všech lokalit a zařízení. Každé zařízení je v ní označeno isActive: false.

curl -u "$AUTH" "$API/api/campaign/company/$COMPANY" > kampan.json

Ukázka šablony (zkráceno):

{
  "id": -1,
  "groupId": -1,
  "state": 2,
  "name": "",
  "start": "2026-11-01T10:00:00",
  "end": "2026-12-01T10:00:00",
  "isCommercial": true,
  "isNonCommercial": false,
  "settings": {
    "type": 2,
    "companyCount": 10,
    "companyDuration": 10000,
    "campaignCount": 1,
    "campaignDuration": 10000
  },
  "locations": [
    {
      "id": 1698234512100,
      "name": "OC Centrum",
      "days": [ { "day": 1, "start": "09:00", "end": "21:00" } ],
      "devices": [
        {
          "id": 1698234512201,
          "name": "Vchod A",
          "screenRatio": 32,
          "isHorizontal": true,
          "isActive": false
        }
      ]
    }
  ],
  "visuals": []
}

Hodnota settings.type určuje režim přehrávání Společnosti: 2 = SLOT, 4 = IMPRESSION. Režim nastavuje poskytovatel a přes API jej změnit nelze.

4. Úprava šablony

• name: název kampaně zobrazený v administraci a reportech.
• start, end: začátek a konec kampaně.
• isActive: nastavte na true u zařízení, na kterých se má kampaň přehrávat.
• visuals: doplňte vizuál s nahraným médiem.

"visuals": [
  {
    "id": 1,
    "name": "Hlavní vizuál",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "letni-vyprodej",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]

Úpravu lze provést skriptem, například nástrojem jq:

jq --argjson res "$RESOURCE" '
  .name = "Letní výprodej 2026"
  | .start = "2026-11-02T00:00:00"
  | .end   = "2026-11-09T00:00:00"
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Hlavní vizuál", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: "letni-vyprodej", duration: 10000, type: 2 }]
    }]
' kampan.json > kampan-upravena.json

Pokud kampaň cílí na obrazovky na šířku i na výšku (isHorizontal), přidejte vizuál pro každou orientaci. Jinak se obsah na části obrazovek ořízne nebo zmenší. Podrobnosti popisuje návod Vizuály kampaně.

5. Založení kampaně

curl -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @kampan-upravena.json \
  -o odpoved.json

export CAMPAIGN=$(jq -r '.id' odpoved.json)
export GROUP=$(jq -r '.groupId' odpoved.json)

Kampaň vznikne ve stavu koncept a nikde se nepřehrává. Odpověď obsahuje uloženou kampaň s přidělenými hodnotami id a groupId. Šablona má stav state: 2 (koncept) nastaven správně; jinou hodnotu server odmítne kódem 409.

6. Aktivace kampaně

curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

• +01:00: časové pásmo jako posun proti UTC, podle kterého se kampaň řídí. Pro Českou republiku +01:00 v zimním a +02:00 v letním čase.
• 0: očekávaný počet zobrazení za celou kampaň. Uplatní se v režimu IMPRESSION; v režimu SLOT uveďte 0.

Kampaň s dnešním nebo dřívějším začátkem přejde do stavu aktivní a její začátek se nastaví na okamžik aktivace. Kampaň s budoucím začátkem přejde do stavu publikovaná a spustí se v naplánovaný den.

Systém poté přepočítá plán přehrávání a odešle jej na dotčená zařízení. U připojených zařízení to obvykle trvá desítky sekund; nepřipojené zařízení plán převezme po obnovení spojení. Kapacitu zařízení ověříte v administraci, viz Kapacita kampaní.

7. Výsledky kampaně

curl -u "$AUTH" "$API/api/report/$COMPANY/campaign/$GROUP"
curl -u "$AUTH" "$API/api/report/$COMPANY/campaign/$GROUP/impression"

Reporty používají groupId, nikoli id kampaně. První adresa vrací souhrn kampaně, druhá počty zaznamenaných zobrazení. Zařízení odesílají záznamy průběžně v dávkách, údaje proto nejsou k dispozici v reálném čase. Význam údajů popisuje Report kampaně.

Pozastavení, ukončení a smazání

# pozastavení aktivní kampaně, opakované volání ji znovu spustí
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

# trvalé ukončení
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00"

# smazání
curl -u "$AUTH" -X DELETE \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN"

Adresa z kroku 6 funguje jako přepínač: aktivní nebo publikovanou kampaň pozastaví, pozastavenou znovu spustí. Před voláním proto ověřte aktuální stav kampaně (state v detailu). Ukončenou kampaň již znovu spustit nelze; zůstává však v seznamu i s reporty. Smazaná kampaň ze seznamu zmizí.

Přehled adres

Adresy jsou relativní k adrese administrace. {c} označuje identifikátor Společnosti.

Účet

Média

Kampaně

Lokality a zařízení

Reporty

Číselníky

Hodnoty číselníků se v JSON zapisují jako čísla.

Stav kampaně (state)

Typy médií

Pro dokument se v hlavičce file-type používá hodnota PDF, nikoli DOCUMENT.

Oprávnění

Rozhraní uplatňuje stejná oprávnění jako administrace a kontroluje je u každého požadavku. V odpovědi přihlášení je každá oblast vyjádřena číslem, které je součtem dílčích práv:

Například resource: 28 (4 + 8 + 16) znamená, že uživatel smí média zobrazit, přidat a upravit, ale ne vymazat. Vyšší hodnoty (128 až 1024) označují stejná práva mimo vlastní Společnost; integrace je nepotřebuje.

Aktivaci, pozastavení i ukončení kampaně umožňuje právo Přidat. Ke smazání aktivované kampaně nebo média je potřeba právo Vymazat; koncept kampaně lze smazat i bez něj. Výchozím bodem může být role Správce firemní reklamy, ze které odeberete nepotřebná práva.

Chybové kódy

Kompletní příklad

Skript provede celý postup od nahrání obrázku po aktivaci kampaně na všech zařízeních Společnosti. Vyžaduje nástroje curl a jq.

#!/usr/bin/env bash
set -euo pipefail

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?nastavte INTEGRATION_AUTH=login:heslo}"
SOUBOR="letni-vyprodej.jpg"
NAZEV="Letní výprodej 2026"
OD="2026-11-02T00:00:00"
DO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

# 1) identifikátor Společnosti
COMPANY=$(curl -sf -u "$AUTH" "$API/api/public/login" | jq -r '.company.id')

# 2) nahrání média
RESOURCE=$(curl -sf -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: $SOUBOR" \
  -H "file-suffix: jpg" \
  --data-binary "@$SOUBOR" | jq -r '.id')

# 3) šablona kampaně
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > sablona.json

# 4) úprava šablony
jq --argjson res "$RESOURCE" --arg n "$NAZEV" --arg from "$OD" --arg to "$DO" '
  .name = $n
  | .start = $from
  | .end = $to
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Hlavní vizuál", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' sablona.json > kampan.json

# 5) založení konceptu
ODPOVED=$(curl -sf -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @kampan.json)
CAMPAIGN=$(echo "$ODPOVED" | jq -r '.id')
GROUP=$(echo "$ODPOVED" | jq -r '.groupId')

# 6) aktivace
curl -sf -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/$TZ_OFFSET/0" > /dev/null

echo "Kampaň $CAMPAIGN aktivována, report: $API/api/report/$COMPANY/campaign/$GROUP"