Dokumentacija / Integracije i izrada sadržaja / API za povezivanje vašeg sistema

API za povezivanje vašeg sistema

Uvod i snalaženje

Kako da upravljate medijima, kampanjama i izveštajima direktno iz sopstvenog sistema, bez prijavljivanja u administraciju.

Čemu služi API

API povezuje korisnikov sopstveni sistem — na primer internet prodavnicu, planer reklamnih kampanja ili interni katalog — direktno sa upravljanjem sadržajem uređaja. Vaš sistem može da otprema medije, kreira i pokreće kampanje i preuzima njihove rezultate, bez potrebe da se neko prijavi u administraciju i ručno obavlja ove radnje.

Interfejs je isti kao onaj koji koristi veb-administracija. API zato podržava iste radnje kao administracija, u okviru dozvola prijavljenog korisnika.

Kada koristiti API

Za povremeno otpremanje nekoliko medijskih datoteka i ručno pokretanje kampanje bolji izbor je administracija: čarobnjak za kampanju prikazuje pregled i proverava formate medija i kapacitet uređaja. API ima smisla kada ručni rad počne da vas usporava.

Potrebno vam je daPreporučeni pristup
Otpremite nekoliko medijskih datoteka i pokrenete kampanjuAdministracija
Redovno ažurirate sadržaj, ali ručnoAdministracija
Grupno otpremate medije iz sopstvenog sistemaAPI
Automatski kreirate kampanje iz sopstvenog raspoređivačaAPI
Preuzimate rezultate kampanja u sopstveni sistem izveštavanjaAPI

Interfejs nije verzionisan i može da se menja sa razvojem platforme. Obavestite dobavljača softvera pre uvođenja integracije i proverite da li ona i dalje radi nakon ažuriranja sistema.

Kome je vodič namenjen i ko je odgovoran

  • Dobavljač platforme upravlja interfejsom, obezbeđuje adresu administracije i podešava režim reprodukcije kompanije.
  • Korisnik odlučuje o obimu integracije i kreira namenski nalog sa potrebnim dozvolama u svojoj kompaniji — pogledajte odeljak Kreiranje korisnika i prva prijava.
  • Programer integracije povezuje korisnikov sistem sa interfejsom. Tehnička uputstva i primeri koda u ovom vodiču namenjeni su tom programeru. Ako sami razvijate integraciju, preuzimate i ovu ulogu.

Tehnička referenca

Tehnički vodič za programere integracija

Počnite zajedničkim pravilima pozivanja i prijavom. Zatim pratite tok od otpremanja medijske datoteke do pokretanja kampanje i pogledajte pregled dostupnih krajnjih tačaka.

Zajednička pravila pozivanja

  • Adresa: interfejs radi na istoj adresi kao vaša administracija; sve putanje počinju sa /api/. U primerima je adresa zamenjena sa https://admin.example.org. Ako je dostupno testno okruženje, dobavljač će vam dati njegovu adresu.
  • Prijava: svaki zahtev sadrži pristupne podatke putem HTTP Basic Auth autentifikacije. Ne koriste se sesije ni tokeni.
  • Format podataka: tela zahteva i odgovori su JSON. Izuzetak je otpremanje datoteke, gde telo čine izvorni binarni podaci.
  • Identifikatori i vrednosti: identifikatori su celi brojevi. Datum i vreme koriste format YYYY-MM-DDTHH:MM:SS, a trajanja prikazivanja izražena su u milisekundama (10000 = 10 s).
  • Rezultat: uspeh se potvrđuje statusom 200. To znači da je zahtev prihvaćen, a ne da se sadržaj već reprodukuje na uređajima.

Prijava

Korisničko ime nije adresa e-pošte, već kod od osam znakova koji sistem generiše pri kreiranju korisnika, na primer A1B2C3D4. Kreirajte namenski nalog sa najmanjim potrebnim dozvolama za integraciju; njegov pristup zatim možete da ukinete u bilo kom trenutku, bez uticaja na druge korisnike.

curl -u "A1B2C3D4:your-password" https://admin.example.org/api/public/login

Lozinka se šalje uz svaki zahtev. Čuvajte je kao tajni podatak, na primer u promenljivoj okruženja ili skladištu lozinki — nikada u izvornom kodu, repozitorijumu ili dnevnicima.

Sledeći primeri pretpostavljaju da su podešene ove promenljive:

export API="https://admin.example.org"
export AUTH="A1B2C3D4:your-password"

Primeri koriste curl jer ne zavisi od programskog jezika. Interfejs koristi standardne HTTP pozive, pa može da se poziva iz bilo kog jezika ili alata koji podržava Basic Auth, na primer Python, JavaScript, PHP, Postman ili Make.

Tok rada: od datoteke do aktivne kampanje

  1. Preuzmite identifikator kompanije. Koristićete ga u svim narednim pozivima.
  2. Otpremite medijsku datoteku. Odgovor vraća njen identifikator.
  3. Učitajte šablon kampanje. Server ga unapred popunjava podešavanjima kompanije i listom lokacija i uređaja.
  4. Izmenite šablon — naziv, period, ciljne uređaje i vizual.
  5. Kreirajte kampanju. Kreira se kao nacrt i još se ne reprodukuje.
  6. Aktivirajte kampanju. Sistem priprema novi plan reprodukcije i šalje ga uređajima.
  7. Pratite rezultate u izveštaju kampanje.

1. Identifikator kompanije

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

Odgovor (skraćen):

{
  "id": 1715714421868,
  "name": "Integration – e-shop",
  "login": "A1B2C3D4",
  "company": { "id": 1698234512001, "name": "Advertising Agency Ltd." },
  "permission": {
    "resource": 12,
    "device_layer_top": 12,
    "report_layer_top": 4
  }
}

Sačuvajte vrednost company.id; primeri je koriste kao promenljivu COMPANY. Odeljak permission navodi dozvole korisnika; njihovo značenje opisano je pod naslovom Dozvole.

2. Otpremanje medijske datoteke

Datoteka se šalje kao binarno telo zahteva pomoću PUT; njena svojstva navode se u zaglavljima.

curl -u "$AUTH" -X PUT \
  "$API/api/resource/single/$COMPANY" \
  -H "file-type: IMAGE" \
  -H "file-mime: image/jpeg" \
  -H "file-name: summer-sale.jpg" \
  -H "file-suffix: jpg" \
  --data-binary @summer-sale.jpg
ZaglavljeSadržaj
file-typeTip medija prema tabeli Tipovi medija , na primer IMAGE.
file-mimeMIME tip datoteke, na primer image/jpeg, video/mp4 ili application/pdf.
file-nameNaziv medija prikazan u administraciji; server uklanja ekstenziju. Nazive koji sadrže znakove van ASCII skupa kodirajte za URL (encodeURIComponent).
file-suffixEkstenzija datoteke bez tačke.

Isti poziv u Pythonu:

import requests

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

Odgovor sadrži identifikator medija (id) i njegov tip (type); obe vrednosti koristićete u vizualu kampanje.

{
  "id": 1724832015443,
  "type": 2,
  "name": "summer-sale",
  "width": 1920,
  "height": 1080,
  "duration": 0,
  "aspectRatio": 32
}
  • Veličina: uobičajene datoteke do približno 1.1 GB, video-zapisi sa providnom pozadinom do približno 2.1 GB. Server odbija veće datoteke uz 413.
  • Priprema video-zapisa: video-zapis se posle otpremanja konvertuje u pozadini. Spreman je kada detaljni prikaz medija (GET /api/resource/single/{companyId}/{id}) sadrži vrednost u polju dt_ready. Za slike je priprema praktično trenutna.
  • Nedostajuće zaglavlje: bez zaglavlja file-mime, file-name ili file-suffix server vraća 204 i ne kreira medijsku datoteku. Uvek proverite da li odgovor sadrži id pre nego što nastavite.

3. Šablon kampanje

Nemojte ručno da sastavljate kampanju. Zatražite šablon koji server unapred popunjava podrazumevanim periodom (mesec dana od danas), podešavanjima kompanije i listom svih lokacija i uređaja. Svaki uređaj u njemu označen je kao isActive: false.

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

Primer šablona (skraćen):

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

Vrednost settings.type određuje kompanijin režim reprodukcije: 2 = SLOT, 4 = IMPRESSION. Režim podešava dobavljač i ne može da se promeni putem API-ja.

4. Uređivanje šablona

  • name: naziv kampanje prikazan u administraciji i izveštajima.
  • start, end: početak i završetak kampanje.
  • isActive: podesite na true za uređaje na kojima kampanja treba da se reprodukuje.
  • visuals: dodajte vizual sa otpremljenom medijskom datotekom.
"visuals": [
  {
    "id": 1,
    "name": "Main visual",
    "isPrimary": true,
    "isCustom": true,
    "res": [
      {
        "id": 1,
        "conditionId": 0,
        "resourceId": 1724832015443,
        "name": "summer-sale",
        "duration": 10000,
        "type": 2
      }
    ]
  }
]
PoljeZnačenje
idBilo koji broj jedinstven unutar kampanje; server ga ponovo numeriše pri kreiranju.
isPrimarytrue za glavni vizual, false za ostale.
isCustomtrue – vizual pripada ovoj kampanji.
resourceIdIdentifikator medija iz koraka 2.
durationTrajanje prikazivanja u milisekundama.
typeTip medija; ista vrednost koju je otpremanje vratilo u polju type.

Šablon može da se uređuje skriptom, na primer pomoću jq:

jq --argjson res "$RESOURCE" '
  .name = "Summer sale 2026"
  | .start = "2026-11-02T00:00:00"
  | .end   = "2026-11-09T00:00:00"
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Main visual", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: "summer-sale", duration: 10000, type: 2 }]
    }]
' campaign.json > campaign-edited.json

Ako kampanja cilja i horizontalne i vertikalne ekrane (isHorizontal), dodajte vizual za svaku orijentaciju. U suprotnom sadržaj će na nekim ekranima biti isečen ili umanjen. Pogledajte Vizuali kampanje za više informacija.

5. Kreiranje kampanje

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

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

Kampanja se kreira kao nacrt i nigde se ne reprodukuje. Odgovor sadrži sačuvanu kampanju sa dodeljenim id i groupId. Šablon već sadrži state: 2 (nacrt); server odbija svaku drugu vrednost uz 409.

6. Aktiviranje kampanje

curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"
  • +01:00: vremenska zona kao odstupanje od UTC-a koje kampanja prati. Za srednju Evropu koristite +01:00 zimi i +02:00 tokom letnjeg računanja vremena.
  • 0: očekivani broj prikazivanja za celu kampanju. Važi u režimu IMPRESSION; u režimu SLOT koristite 0.

Kampanja koja počinje danas ili ranije postaje aktivna, a njen početak postavlja se na trenutak aktiviranja. Kampanja sa budućim početkom postaje objavljena i počinje zakazanog dana.

Sistem zatim ponovo izračunava plan reprodukcije i šalje ga obuhvaćenim uređajima. Kod povezanih uređaja ovo obično traje nekoliko desetina sekundi; uređaj bez veze prima plan kada se veza ponovo uspostavi. Kapacitet uređaja proverite u administraciji, pogledajte Kapacitet kampanje.

7. Rezultati kampanje

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

Izveštaji koriste groupId, a ne identifikator kampanje id. Prva krajnja tačka vraća sažetak kampanje, a druga brojeve zabeleženih prikazivanja. Uređaji neprekidno šalju zapise u paketima, pa vrednosti nisu dostupne u realnom vremenu. Pogledajte Izveštaj kampanje za značenje prikazanih vrednosti.

Pauziranje, zaustavljanje i brisanje

# pause an active campaign; calling it again resumes it
curl -u "$AUTH" -X PATCH \
  "$API/api/campaign/company/$COMPANY/$CAMPAIGN/+01:00/0"

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

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

Krajnja tačka iz koraka 6 funkcioniše kao prekidač: pauzira aktivnu ili objavljenu kampanju i nastavlja pauziranu. Pre poziva proverite trenutno stanje kampanje (state u detaljnom prikazu). Zaustavljena kampanja ne može ponovo da se pokrene, ali ostaje na listi zajedno sa izveštajima. Obrisana kampanja nestaje sa liste.

Pregled krajnjih tačaka

Putanje su relativne u odnosu na adresu administracije. {c} predstavlja identifikator kompanije.

Nalog

MetodPutanjaNamena
GET/api/public/loginProverava pristupne podatke i vraća korisnički profil, uključujući company.id.
GET/api/user/infoInformacije o prijavljenom korisniku.
GET/api/user/checkBrza provera važenja pristupnih podataka.

Mediji

MetodPutanjaNamena
PUT/api/resource/single/{c}Otprema datoteku (file-* zaglavlja, telo = binarni podaci).
GET/api/resource/listing/{c}/1Lista medija; 1 = bez ograničenja tipa.
GET/api/resource/single/{c}/{id}Detaljni prikaz medija.
DELETE/api/resource/single/{c}/{id}Briše medijsku datoteku.

Kampanje

MetodPutanjaNamena
GET/api/campaign/company/{c}Šablon nove kampanje.
POST/api/campaign/company/{c}Kreira kampanju kao nacrt.
PATCH/api/campaign/company/{c}Čuva izmene postojeće kampanje.
POST/api/campaign/listing/company/{c}Lista kampanja; telo zahteva sadrži filter.
GET/api/campaign/company/{c}/{id}Detaljni prikaz kampanje.
GET/api/campaign/company/{c}/group/{groupId}Detaljni prikaz kampanje prema groupId.
PATCH/api/campaign/company/{c}/{id}/{tz}/{impressions}Aktivira, pauzira ili nastavlja kampanju.
PATCH/api/campaign/company/{c}/{id}/{tz}Trajno zaustavlja kampanju.
DELETE/api/campaign/company/{c}/{id}Briše kampanju.

Lokacije i uređaji

MetodPutanjaNamena
GET/api/location/listing/{c}Lista lokacija.
GET/api/location/single/{id}Detaljni prikaz lokacije, uključujući radno vreme.
GET/api/device/listing/{c}/{locationId}Lista uređaja na lokaciji.
GET/api/device/single/{id}/{lang}Detaljni prikaz uređaja; lang je oznaka jezika, na primer en.

Izveštaji

MetodPutanjaNamena
GET/api/report/{c}/campaign/{groupId}Sažetak kampanje.
GET/api/report/{c}/campaign/{groupId}/impressionBrojevi zabeleženih prikazivanja.

Šifarnici

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

Stanje kampanje (state)

VrednostStanjeZnačenje
2NacrtSačuvana kampanja koja se ne reprodukuje.
4ObjavljenaAktivirana kampanja koja čeka dan početka.
8AktivneKampanja se reprodukuje.
16ZavršenaZavršni datum kampanje je prošao.
32ZaustavljenaKampanja je trajno zaustavljena.
64ObrisanaKampanja je obrisana.
128PauziranaReprodukcija je privremeno prekinuta.

Tipovi medija

type vrednostfile-type zaglavljeMediji
2IMAGESlika (JPG, PNG, WebP)
4VIDEOVideo
8PDFPDF dokument
16WWW_APPVeb-aplikacija
32TEXTDugačak tekst
128VIDEO_ALPHAVideo-zapis sa providnom pozadinom
256AUDIOZvuk

Za dokumente zaglavlje file-type koristi vrednost PDF, a ne DOCUMENT.

Dozvole

Interfejs primenjuje iste dozvole kao administracija i proverava ih pri svakom zahtevu. U odgovoru na prijavu svaka oblast izražena je brojem koji predstavlja zbir pojedinačnih prava:

VrednostPravo unutar sopstvene kompanije
4Pregled
8Dodavanje
16Uređivanje
32Brisanje

Na primer, resource: 28 (4 + 8 + 16) znači da korisnik sme da pregleda, dodaje i uređuje medije, ali ne i da ih briše. Više vrednosti (128 do 1024) predstavljaju ista prava van sopstvene kompanije korisnika; integraciji ona nisu potrebna.

OblastMinimum za opisani tok rada
resource – mediji12 (pregled, dodavanje)
device_layer_top – kampanje12 (pregled, dodavanje)
report_layer_top – izveštaji kampanja4 (pregled)
location – lokacije4 (pregled)
device_info – uređaji4 (pregled)

Aktiviranje, pauziranje i zaustavljanje kampanje zahtevaju pravo Dodavanje. Brisanje aktivirane kampanje ili medijske datoteke zahteva pravo Brisanje; nacrt kampanje može da se obriše i bez njega. Dobra polazna osnova je uloga Menadžer oglasa kompanije iz koje su uklonjena nepotrebna prava.

Kodovi grešaka

KodZnačenjeŠta uraditi
400Neispravan zahtevProverite identifikatore u putanji, vremensku zonu i potrebne podatke.
401Nedostaje dozvolaKorisniku nedostaje potrebno pravo ili pristup kompaniji. Kod kampanja je najčešće u pitanju nedostajuće pravo Dodavanje.
404Nije pronađenoZapis ne postoji ili ne pripada datoj kompaniji.
406Nije prihvatljivoNeispravni pristupni podaci ili je kampanja u stanju iz kojeg traženi prelaz nije dozvoljen (npr. zaustavljena).
409Konflikt stanjaKampanja koja se kreira nije nacrt.
413Datoteka je prevelikaSmanjite veličinu datoteke; ograničenja su navedena u koraku 2.
500Greška serveraPokušajte ponovo kasnije; ako se problem nastavi, obratite se dobavljaču.
Preporuke za implementaciju

Najpre testirajte integraciju u testnom okruženju ili na uređaju koji nije vidljiv javnosti — aktivirana kampanja zaista se reprodukuje na produkcionim uređajima. Van radnog vremena lokacije sadržaj se ne reprodukuje, čak ni kada je kampanja zakazana tokom celog dana.

Identifikatore medija i kampanja (id, groupId) čuvajte u sopstvenom sistemu; interfejs ne nudi pretragu kampanja po nazivu. Otpremajte medije jedan po jedan i ne tražite izveštaje češće od jednom u nekoliko minuta. Oslanjajte se samo na krajnje tačke navedene u ovom vodiču.

Potpun primer

Skripta obavlja ceo tok rada od otpremanja slike do aktiviranja kampanje na svim uređajima kompanije. Zahteva curl i jq.

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

API="https://admin.example.org"
AUTH="${INTEGRATION_AUTH:?set INTEGRATION_AUTH=login:password}"
FILE="summer-sale.jpg"
NAME="Summer sale 2026"
FROM="2026-11-02T00:00:00"
TO="2026-11-09T00:00:00"
TZ_OFFSET="+01:00"

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

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

# 3) campaign template
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > template.json

# 4) edit the template
jq --argjson res "$RESOURCE" --arg n "$NAME" --arg from "$FROM" --arg to "$TO" '
  .name = $n
  | .start = $from
  | .end = $to
  | .locations[].devices[].isActive = true
  | .visuals = [{
      id: 1, name: "Main visual", isPrimary: true, isCustom: true,
      res: [{ id: 1, conditionId: 0, resourceId: $res,
              name: $n, duration: 10000, type: 2 }]
    }]
' template.json > campaign.json

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

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

echo "Campaign $CAMPAIGN activated, report: $API/api/report/$COMPANY/campaign/$GROUP"
Niste pronašli ono što tražite?
Obratite se svom dobavljaču softvera.