API za povezivanje s vašim sistemom

Tehnička dokumentacija

Tehničke upute za programere integracije

Najprije se upoznajte sa zajedničkim pravilima pozivanja i prijavom. Zatim prođite postupak od učitavanja medija do pokretanja kampanje i pregled dostupnih adresa.

Prijava

Korisničko ime nije e-mail adresa, nego kod od osam znakova koji je sistem generisao pri kreiranju korisnika, naprimjer A1B2C3D4. Za integraciju kreirajte zasebnog korisnika s najmanjim potrebnim dozvolama; njegov pristup tada se u svakom trenutku može ukloniti bez uticaja na ostale korisnike.

curl -u "A1B2C3D4:vasa-lozinka" https://admin.example.org/api/public/login

Lozinka se šalje sa svakim zahtjevom. Sačuvajte je kao tajni podatak, naprimjer u varijabli okruženja ili trezoru lozinki, nikada u izvornom kodu, repozitoriju ili logovima.

Primjeri u nastavku pretpostavljaju postavljene varijable:

export API="https://admin.example.org"
export AUTH="A1B2C3D4:vasa-lozinka"

Primjeri koriste alat curl jer ne zavisi od programskog jezika. Interfejs je obični HTTP pa ga je moguće pozivati iz bilo kojeg jezika ili alata s podrškom za Basic Auth, naprimjer Python, JavaScript, PHP, Postman ili Make.

Postupak: od datoteke do pokrenute kampanje

1. Saznajte identifikator Kompanije. Koristit ćete ga u svim daljnjim pozivima.
2. Učitajte medij. Odgovor vraća njegov identifikator.
3. Učitajte šablon kampanje. Server ga unaprijed popunjava postavkama Kompanije i listom lokacija i uređaja.
4. Uredite šablon — naziv, period, ciljne uređaje i vizual.
5. Kreirajte kampanju. Nastaje kao nacrt i zasad se ne reprodukuje.
6. Aktivirajte kampanju. Sistem priprema novi plan reprodukcije i šalje ga na uređaje.
7. Pratite rezultate u izvještaju kampanje.

1. Identifikator Kompanije

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

Odgovor (skraćeno):

{
  "id": 1715714421868,
  "name": "Integracija – web-prodavnica",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Reklamna agencija d.o.o." },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Sačuvajte vrijednost company.id; u primjerima se koristi kao varijabla COMPANY. Odjeljak permission navodi dozvole korisnika; njihovo značenje opisuje dio Dozvole.

2. Učitavanje medija

Datoteka se šalje kao binarno tijelo zahtjeva metodom PUT; njena svojstva određuju zaglavlja.

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

Isti poziv u jeziku Python:

import requests

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

Odgovor sadrži identifikator medija (id) i njegovu vrstu (type); obje vrijednosti koristite u vizualu kampanje.

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

• Veličina: obične datoteke najviše oko 1,1 GB, video s prozirnošću oko 2,1 GB. Veću datoteku server odbija kodom 413.
• Priprema videosnimka: video se nakon učitavanja konvertuje u pozadini. Spreman je kada detalj medija (GET /api/resource/single/{companyId}/{id}) sadrži popunjenu vrijednost dt_ready. Kod slika je priprema praktično trenutna.
• Nedostaje zaglavlje: bez file-mime, file-name ili file-suffix server vraća 204 i ne kreira medij. Prije sljedećeg koraka zato uvijek provjerite sadrži li odgovor id.

3. Šablon kampanje

Kampanju ne sastavljajte ručno. Zatražite šablon koji server unaprijed popunjava zadanim periodom (od danas na mjesec dana), postavkama Kompanije i listom svih lokacija i uređaja. Svaki je uređaj u njemu označen s isActive: false.

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

Primjer šablona (skraćeno):

{
  "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": "Tržni centar",
      "days": [ { "day": 1, "start": "09:00", "end": "21:00" } ],
      "devices": [
        {
          "id": 1698234512201,
          "name": "Ulaz A",
          "screenRatio": 32,
          "isHorizontal": true,
          "isActive": false
        }
      ]
    }
  ],
  "visuals": []
}

Vrijednost settings.type određuje način reprodukcije Kompanije: 2 = SLOT, 4 = IMPRESSION. Način postavlja pružalac i nije ga moguće promijeniti putem API-ja.

4. Uređivanje šablona

• name: naziv kampanje prikazan u administraciji i izvještajima.
• start, end: početak i kraj kampanje.
• isActive: postavite na true kod uređaja na kojima se kampanja treba reprodukovati.
• visuals: dodajte vizual s učitanim medijem.

"visuals": [
  {
    "id": 1,
    "name": "Glavni vizual",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "ljetno-snizenje",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]

Uređivanje je moguće obaviti skriptom, naprimjer alatom jq:

jq --argjson res "$RESOURCE" '
  .name = "Ljetno sniženje 2026"
  | .start = "2026-11-02T00:00:00"
  | .end   = "2026-11-09T00:00:00"
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Glavni vizual", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: "ljetno-snizenje", duration: 10000, type: 2 }]
    }]
' kampanja.json > kampanja-uredjena.json

Ako kampanja cilja ekrane u horizontalnom i vertikalnom položaju (isHorizontal), dodajte vizual za svaku orijentaciju. U suprotnom će se sadržaj na dijelu ekrana odsjeći ili smanjiti. Pojedinosti opisuje vodič Vizuali kampanje.

5. Kreiranje kampanje

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

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

Kampanja nastaje u stanju nacrta i nigdje se ne reprodukuje. Odgovor sadrži sačuvanu kampanju s dodijeljenim vrijednostima id i groupId. Šablon ima ispravno postavljeno stanje state: 2 (nacrt); drugu vrijednost server odbija kodom 409.

6. Aktivacija kampanje

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

• +01:00: vremenska zona kao pomak u odnosu na UTC prema kojoj se kampanja ravna. Za Bosnu i Hercegovinu +01:00 u zimskom i +02:00 u ljetnom računanju vremena.
• 0: očekivani broj prikaza za cijelu kampanju. Primjenjuje se u načinu IMPRESSION; u načinu SLOT navedite 0.

Kampanja s današnjim ili ranijim početkom prelazi u stanje aktivna, a njen se početak postavlja na trenutak aktivacije. Kampanja s budućim početkom prelazi u stanje objavljena i pokreće se na planirani dan.

Sistem zatim ponovo izračunava plan reprodukcije i šalje ga na pogođene uređaje. Kod povezanih uređaja to obično traje desetine sekundi; nepovezani uređaj preuzima plan nakon ponovnog uspostavljanja veze. Kapacitet uređaja provjerite u administraciji, vidi Kapacitet kampanje.

7. Rezultati kampanje

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

Izvještaji koriste groupId, a ne id kampanje. Prva adresa vraća sažetak kampanje, druga broj zabilježenih prikaza. Uređaji šalju zapise kontinuirano u grupama pa podaci nisu dostupni u stvarnom vremenu. Značenje podataka opisuje Izvještaj kampanje.

Pauziranje, zaustavljanje i brisanje

# pauziranje aktivne kampanje, ponovni poziv je ponovo pokreće
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

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

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

Adresa iz koraka 6 radi kao prekidač: aktivnu ili objavljenu kampanju pauzira, a pauziranu ponovo pokreće. Prije poziva zato provjerite trenutno stanje kampanje (state u detalju). Zaustavljenu kampanju nije moguće ponovo pokrenuti, ali ostaje na listi zajedno s izvještajima. Izbrisana kampanja nestaje s liste.

Pregled adresa

Adrese su relativne u odnosu na adresu administracije. {c} označava identifikator Kompanije.

Račun

Mediji

Kampanje

Lokacije i uređaji

Izvještaji

Šifarnici

Vrijednosti šifarnika se u JSON-u zapisuju kao brojevi.

Stanje kampanje (state)

Vrste medija

Za dokument se u zaglavlju file-type koristi vrijednost PDF, a ne DOCUMENT.

Dozvole

Interfejs primjenjuje iste dozvole kao administracija i provjerava ih kod svakog zahtjeva. U odgovoru na prijavu svako je područje izraženo brojem koji je zbir pojedinačnih prava:

Naprimjer, resource: 28 (4 + 8 + 16) znači da korisnik smije pregledati, dodavati i uređivati medije, ali ne i brisati ih. Više vrijednosti (128 do 1024) označavaju ista prava izvan vlastite Kompanije; integraciji nisu potrebne.

Aktivaciju, pauziranje i zaustavljanje kampanje omogućava pravo Dodavanje. Za brisanje aktivirane kampanje ili medija potrebno je pravo Brisanje; nacrt kampanje moguće je izbrisati i bez njega. Polazište može biti uloga Upravitelj reklama firme iz koje uklonite nepotrebna prava.

Kodovi grešaka

Kompletan primjer

Skripta obavlja cijeli postupak od učitavanja slike do aktivacije kampanje na svim uređajima Kompanije. Potrebni su alati curl i jq.

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

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?postavite INTEGRATION_AUTH=login:lozinka}"
DATOTEKA="ljetno-snizenje.jpg"
NAZIV="Ljetno sniženje 2026"
OD="2026-11-02T00:00:00"
DO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

# 1) identifikator Kompanije
COMPANY=$(curl -sf -u "$AUTH" "$API/api/public/login" | jq -r '.company.id')

# 2) učitavanje medija
RESOURCE=$(curl -sf -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: $DATOTEKA" \
  -H "file-suffix: jpg" \
  --data-binary "@$DATOTEKA" | jq -r '.id')

# 3) šablon kampanje
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > sablon.json

# 4) uređivanje šablona
jq --argjson res "$RESOURCE" --arg n "$NAZIV" --arg from "$OD" --arg to "$DO" '
  .name = $n
  | .start = $from
  | .end = $to
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Glavni vizual", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' sablon.json > kampanja.json

# 5) kreiranje nacrta
ODGOVOR=$(curl -sf -u "$AUTH" -X POST \
  "$API/api/campaign/company/$COMPANY" \
  -H "Content-Type: application/json" \
  --data @kampanja.json)
CAMPAIGN=$(echo "$ODGOVOR" | jq -r '.id')
GROUP=$(echo "$ODGOVOR" | jq -r '.groupId')

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

echo "Kampanja $CAMPAIGN aktivirana, izvještaj: $API/api/report/$COMPANY/campaign/$GROUP"