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 da | Preporučeni pristup |
|---|---|
| Otpremite nekoliko medijskih datoteka i pokrenete kampanju | Administracija |
| Redovno ažurirate sadržaj, ali ručno | Administracija |
| Grupno otpremate medije iz sopstvenog sistema | API |
| Automatski kreirate kampanje iz sopstvenog raspoređivača | API |
| Preuzimate rezultate kampanja u sopstveni sistem izveštavanja | API |
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 sahttps://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/loginLozinka 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
- Preuzmite identifikator kompanije. Koristićete ga u svim narednim pozivima.
- Otpremite medijsku datoteku. Odgovor vraća njen identifikator.
- Učitajte šablon kampanje. Server ga unapred popunjava podešavanjima kompanije i listom lokacija i uređaja.
- Izmenite šablon — naziv, period, ciljne uređaje i vizual.
- Kreirajte kampanju. Kreira se kao nacrt i još se ne reprodukuje.
- Aktivirajte kampanju. Sistem priprema novi plan reprodukcije i šalje ga uređajima.
- 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| Zaglavlje | Sadržaj |
|---|---|
file-type | Tip medija prema tabeli Tipovi medija , na primer IMAGE. |
file-mime | MIME tip datoteke, na primer image/jpeg, video/mp4 ili application/pdf. |
file-name | Naziv medija prikazan u administraciji; server uklanja ekstenziju. Nazive koji sadrže znakove van ASCII skupa kodirajte za URL (encodeURIComponent). |
file-suffix | Ekstenzija 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 poljudt_ready. Za slike je priprema praktično trenutna. - Nedostajuće zaglavlje: bez zaglavlja
file-mime,file-nameilifile-suffixserver vraća204i ne kreira medijsku datoteku. Uvek proverite da li odgovor sadržiidpre 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.jsonPrimer š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 natrueza 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
}
]
}
]| Polje | Značenje |
|---|---|
id | Bilo koji broj jedinstven unutar kampanje; server ga ponovo numeriše pri kreiranju. |
isPrimary | true za glavni vizual, false za ostale. |
isCustom | true – vizual pripada ovoj kampanji. |
resourceId | Identifikator medija iz koraka 2. |
duration | Trajanje prikazivanja u milisekundama. |
type | Tip 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.jsonAko 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:00zimi i+02:00tokom letnjeg računanja vremena.0: očekivani broj prikazivanja za celu kampanju. Važi u režimu IMPRESSION; u režimu SLOT koristite0.
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
| Metod | Putanja | Namena |
|---|---|---|
GET | /api/public/login | Proverava pristupne podatke i vraća korisnički profil, uključujući company.id. |
GET | /api/user/info | Informacije o prijavljenom korisniku. |
GET | /api/user/check | Brza provera važenja pristupnih podataka. |
Mediji
| Metod | Putanja | Namena |
|---|---|---|
PUT | /api/resource/single/{c} | Otprema datoteku (file-* zaglavlja, telo = binarni podaci). |
GET | /api/resource/listing/{c}/1 | Lista 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
| Metod | Putanja | Namena |
|---|---|---|
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
| Metod | Putanja | Namena |
|---|---|---|
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
| Metod | Putanja | Namena |
|---|---|---|
GET | /api/report/{c}/campaign/{groupId} | Sažetak kampanje. |
GET | /api/report/{c}/campaign/{groupId}/impression | Brojevi zabeleženih prikazivanja. |
Šifarnici
Vrednosti šifarnika zapisuju se kao brojevi u JSON-u.
Stanje kampanje (state)
| Vrednost | Stanje | Značenje |
|---|---|---|
2 | Nacrt | Sačuvana kampanja koja se ne reprodukuje. |
4 | Objavljena | Aktivirana kampanja koja čeka dan početka. |
8 | Aktivne | Kampanja se reprodukuje. |
16 | Završena | Završni datum kampanje je prošao. |
32 | Zaustavljena | Kampanja je trajno zaustavljena. |
64 | Obrisana | Kampanja je obrisana. |
128 | Pauzirana | Reprodukcija je privremeno prekinuta. |
Tipovi medija
type vrednost | file-type zaglavlje | Mediji |
|---|---|---|
2 | IMAGE | Slika (JPG, PNG, WebP) |
4 | VIDEO | Video |
8 | PDF | PDF dokument |
16 | WWW_APP | Veb-aplikacija |
32 | TEXT | Dugačak tekst |
128 | VIDEO_ALPHA | Video-zapis sa providnom pozadinom |
256 | AUDIO | Zvuk |
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:
| Vrednost | Pravo unutar sopstvene kompanije |
|---|---|
4 | Pregled |
8 | Dodavanje |
16 | Uređivanje |
32 | Brisanje |
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.
| Oblast | Minimum za opisani tok rada |
|---|---|
resource – mediji | 12 (pregled, dodavanje) |
device_layer_top – kampanje | 12 (pregled, dodavanje) |
report_layer_top – izveštaji kampanja | 4 (pregled) |
location – lokacije | 4 (pregled) |
device_info – uređaji | 4 (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
| Kod | Značenje | Šta uraditi |
|---|---|---|
400 | Neispravan zahtev | Proverite identifikatore u putanji, vremensku zonu i potrebne podatke. |
401 | Nedostaje dozvola | Korisniku nedostaje potrebno pravo ili pristup kompaniji. Kod kampanja je najčešće u pitanju nedostajuće pravo Dodavanje. |
404 | Nije pronađeno | Zapis ne postoji ili ne pripada datoj kompaniji. |
406 | Nije prihvatljivo | Neispravni pristupni podaci ili je kampanja u stanju iz kojeg traženi prelaz nije dozvoljen (npr. zaustavljena). |
409 | Konflikt stanja | Kampanja koja se kreira nije nacrt. |
413 | Datoteka je prevelika | Smanjite veličinu datoteke; ograničenja su navedena u koraku 2. |
500 | Greška servera | Pokušajte ponovo kasnije; ako se problem nastavi, obratite se dobavljaču. |
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"Povezane teme i sledeći koraci
← Nazad na pregled – Integracije i izrada sadržaja
Obratite se svom dobavljaču softvera.
