API na prepojenie s vaším systémom

Technická dokumentácia

Technická časť pre vývojárov integrácie

Najprv sa oboznámte so spoločnými pravidlami volania a prihlásením. Potom prejdite postup od nahrania média po spustenie kampane a prehľad dostupných adries.

Prihlásenie

Prihlasovacím menom nie je e-mail, ale osemznakový kód, ktorý systém vygeneroval pri založení používateľa, napríklad A1B2C3D4. Pre integráciu založte samostatného používateľa s minimálnymi nevyhnutnými oprávneniami; jeho prístup potom možno kedykoľvek odobrať bez vplyvu na ostatných používateľov.

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

Heslo sa odosiela s každou požiadavkou. Uložte ho ako tajný údaj, napríklad v premennej prostredia alebo v trezore hesiel, nikdy nie do zdrojového kódu, repozitára alebo logov.

Ukážky ďalej predpokladajú nastavené premenné:

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

Ukážky používajú nástroj curl, pretože nezávisí od programovacieho jazyka. Rozhranie je bežné HTTP, preto ho možno volať z ľubovoľného jazyka alebo nástroja s podporou Basic Auth, napríklad Python, JavaScript, PHP, Postman alebo Make.

Postup: od súboru k spustenej kampani

1. Zistite identifikátor Spoločnosti. Použijete ho vo všetkých ďalších volaniach.
2. Nahrajte médium. Odpoveď vráti jeho identifikátor.
3. Načítajte šablónu kampane. Server ju predvyplní nastavením Spoločnosti a zoznamom lokalít a zariadení.
4. Upravte šablónu — názov, termín, cieľové zariadenia a vizuál.
5. Založte kampaň. Vznikne ako koncept a zatiaľ sa neprehráva.
6. Aktivujte kampaň. Systém pripraví nový plán prehrávania a odošle ho do zariadení.
7. Sledujte výsledky v reporte kampane.

1. Identifikátor Spoločnosti

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

Odpoveď (skrátené):

{
  "id": 1715714421868,
  "name": "Integrácia – e-shop",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Reklamná agentúra s.r.o." },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Hodnotu company.id si uložte, v ukážkach ako premennú COMPANY. Sekcia permission uvádza oprávnenia používateľa; ich význam opisuje časť Oprávnenia.

2. Nahranie média

Súbor sa odosiela ako binárne telo požiadavky metódou 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: letny-vypredaj.jpg" \
  -H "file-suffix: jpg" \
  --data-binary @letny-vypredaj.jpg

Rovnaké volanie v jazyku Python:

import requests

with open("letny-vypredaj.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": "letny-vypredaj.jpg",
            "file-suffix": "jpg",
        },
        data=f,
    )
r.raise_for_status()
resource_id = r.json()["id"]

Odpoveď obsahuje identifikátor média (id) a jeho typ (type); obe hodnoty použijete vo vizuáli kampane.

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

• Veľkosť: bežné súbory najviac približne 1,1 GB, video s priehľadnosťou približne 2,1 GB. Väčší súbor server odmietne kódom 413.
• Príprava videa: video sa po nahraní konvertuje na pozadí. Pripravené je, keď detail média (GET /api/resource/single/{companyId}/{id}) obsahuje vyplnenú hodnotu dt_ready. Pri obrázkoch je príprava prakticky okamžitá.
• Chýbajúca hlavička: bez file-mime, file-name alebo file-suffix server vráti 204 a médium nevytvorí. Pred ďalším krokom preto vždy overte, že odpoveď obsahuje id.

3. Šablóna kampane

Kampaň neskladajte ručne. Vyžiadajte si šablónu, ktorú server predvyplní predvoleným termínom (od dnešného dňa na jeden mesiac), nastavením Spoločnosti a zoznamom všetkých lokalít a zariadení. Každé zariadenie je v nej označené isActive: false.

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

Ukážka šablóny (skrátené):

{
  "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 prehrávania Spoločnosti: 2 = SLOT, 4 = IMPRESSION. Režim nastavuje poskytovateľ a cez API ho zmeniť nemožno.

4. Úprava šablóny

• name: názov kampane zobrazený v administrácii a reportoch.
• start, end: začiatok a koniec kampane.
• isActive: nastavte na true pri zariadeniach, na ktorých sa má kampaň prehrávať.
• visuals: doplňte vizuál s nahraným médiom.

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

Úpravu možno vykonať skriptom, napríklad nástrojom jq:

jq --argjson res "$RESOURCE" '
  .name = "Letný výpredaj 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: "letny-vypredaj", duration: 10000, type: 2 }]
    }]
' kampan.json > kampan-upravena.json

Ak kampaň cieli na obrazovky na šírku aj na výšku (isHorizontal), pridajte vizuál pre každú orientáciu. Inak sa obsah na časti obrazoviek oreže alebo zmenší. Podrobnosti opisuje návod Vizuály kampane.

5. Založenie kampane

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 v stave koncept a nikde sa neprehráva. Odpoveď obsahuje uloženú kampaň s pridelenými hodnotami id a groupId. Šablóna má stav state: 2 (koncept) nastavený správne; inú hodnotu server odmietne kódom 409.

6. Aktivácia kampane

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

• +01:00: časové pásmo ako posun voči UTC, podľa ktorého sa kampaň riadi. Pre Slovensko +01:00 v zimnom a +02:00 v letnom čase.
• 0: očakávaný počet zobrazení za celú kampaň. Uplatní sa v režime IMPRESSION; v režime SLOT uveďte 0.

Kampaň s dnešným alebo skorším začiatkom prejde do stavu aktívna a jej začiatok sa nastaví na okamih aktivácie. Kampaň s budúcim začiatkom prejde do stavu publikovaná a spustí sa v naplánovaný deň.

Systém potom prepočíta plán prehrávania a odošle ho do dotknutých zariadení. Pri pripojených zariadeniach to zvyčajne trvá desiatky sekúnd; nepripojené zariadenie plán prevezme po obnovení spojenia. Kapacitu zariadení overíte v administrácii, pozri Kapacita kampane.

7. Výsledky kampane

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

Reporty používajú groupId, nie id kampane. Prvá adresa vracia súhrn kampane, druhá počty zaznamenaných zobrazení. Zariadenia odosielajú záznamy priebežne v dávkach, údaje preto nie sú k dispozícii v reálnom čase. Význam údajov opisuje Report kampane.

Pozastavenie, ukončenie a vymazanie

# pozastavenie aktívnej kampane, opakované volanie ju znova spustí
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

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

# vymazanie
curl -u "$AUTH" -X DELETE \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN"

Adresa z kroku 6 funguje ako prepínač: aktívnu alebo publikovanú kampaň pozastaví, pozastavenú znova spustí. Pred volaním preto overte aktuálny stav kampane (state v detaile). Ukončenú kampaň už znova spustiť nemožno; zostáva však v zozname aj s reportmi. Vymazaná kampaň zo zoznamu zmizne.

Prehľad adries

Adresy sú relatívne k adrese administrácie. {c} označuje identifikátor Spoločnosti.

Účet

Médiá

Kampane

Lokality a zariadenia

Reporty

Číselníky

Hodnoty číselníkov sa v JSON zapisujú ako čísla.

Stav kampane (state)

Typy médií

Pre dokument sa v hlavičke file-type používa hodnota PDF, nie DOCUMENT.

Oprávnenia

Rozhranie uplatňuje rovnaké oprávnenia ako administrácia a kontroluje ich pri každej požiadavke. V odpovedi prihlásenia je každá oblasť vyjadrená číslom, ktoré je súčtom čiastkových práv:

Napríklad resource: 28 (4 + 8 + 16) znamená, že používateľ smie médiá zobraziť, pridať a upraviť, ale nie vymazať. Vyššie hodnoty (128 až 1024) označujú rovnaké práva mimo vlastnej Spoločnosti; integrácia ich nepotrebuje.

Aktiváciu, pozastavenie aj ukončenie kampane umožňuje právo Pridať. Na vymazanie aktivovanej kampane alebo média je potrebné právo Vymazať; koncept kampane možno vymazať aj bez neho. Východiskom môže byť rola Správca firemnej reklamy, z ktorej odoberiete nepotrebné práva.

Chybové kódy

Kompletný príklad

Skript vykoná celý postup od nahrania obrázka po aktiváciu kampane na všetkých zariadeniach Spoloč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}"
SUBOR="letny-vypredaj.jpg"
NAZOV="Letný výpredaj 2026"
OD="2026-11-02T00:00:00"
DO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

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

# 2) nahranie 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: $SUBOR" \
  -H "file-suffix: jpg" \
  --data-binary "@$SUBOR" | jq -r '.id')

# 3) šablóna kampane
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > sablona.json

# 4) úprava šablóny
jq --argjson res "$RESOURCE" --arg n "$NAZOV" --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ženie 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) aktivácia
curl -sf -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/$TZ_OFFSET/0" > /dev/null

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