API za povezivanje s vašim sustavom

Tehnička dokumentacija

Tehničke upute za razvojne 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-adresa, nego kod od osam znakova koji je sustav generirao pri izradi korisnika, primjerice A1B2C3D4. Za integraciju izradite zasebnog korisnika s najmanjim potrebnim dozvolama; njegov pristup tada se u svakom trenutku može ukloniti bez utjecaja na ostale korisnike.

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

Lozinka se šalje sa svakim zahtjevom. Pohranite je kao tajni podatak, primjerice u varijablu okruženja ili trezor lozinki, nikada u izvorni kod, repozitorij ili zapisnike.

Primjeri u nastavku pretpostavljaju postavljene varijable:

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

Primjeri koriste alat curl jer ne ovisi o programskom jeziku. Sučelje je obični HTTP pa ga je moguće pozivati iz bilo kojeg jezika ili alata s podrškom za Basic Auth, primjerice Python, JavaScript, PHP, Postman ili Make.

Postupak: od datoteke do pokrenute kampanje

1. Saznajte identifikator Tvrtke. Koristit ćete ga u svim daljnjim pozivima.
2. Učitajte medij. Odgovor vraća njegov identifikator.
3. Učitajte predložak kampanje. Poslužitelj ga unaprijed ispunjava postavkama Tvrtke i popisom lokacija i uređaja.
4. Uredite predložak — naziv, razdoblje, ciljne uređaje i vizual.
5. Izradite kampanju. Nastaje kao skica i zasad se ne reproducira.
6. Aktivirajte kampanju. Sustav priprema novi plan reprodukcije i šalje ga na uređaje.
7. Pratite rezultate u izvještaju kampanje.

1. Identifikator Tvrtke

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

Odgovor (skraćeno):

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

Spremite 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; njezina 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 poslužitelj odbija kodom 413.
• Priprema videozapisa: video se nakon učitavanja konvertira u pozadini. Spreman je kada detalj medija (GET /api/resource/single/{companyId}/{id}) sadrži popunjenu vrijednost dt_ready. Kod slika je priprema praktički trenutačna.
• Nedostaje zaglavlje: bez file-mime, file-name ili file-suffix poslužitelj vraća 204 i ne izrađuje medij. Prije sljedećeg koraka zato uvijek provjerite sadrži li odgovor id.

3. Predložak kampanje

Kampanju ne sastavljajte ručno. Zatražite predložak koji poslužitelj unaprijed ispunjava zadanim razdobljem (od danas na mjesec dana), postavkama Tvrtke i popisom 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 predloška (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": "Trgovački 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 Tvrtke: 2 = SLOT, 4 = IMPRESSION. Način postavlja pružatelj i nije ga moguće promijeniti putem API-ja.

4. Uređivanje predloška

• 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 reproducirati.
• 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, primjerice 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-uredena.json

Ako kampanja cilja zaslone u vodoravnom i okomitom položaju (isHorizontal), dodajte vizual za svaku orijentaciju. U suprotnom će se sadržaj na dijelu zaslona obrezati ili smanjiti. Pojedinosti opisuje vodič Vizuali kampanje.

5. Izrada kampanje

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

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

Kampanja nastaje u stanju skice i nigdje se ne reproducira. Odgovor sadrži spremljenu kampanju s dodijeljenim vrijednostima id i groupId. Predložak ima ispravno postavljeno stanje state: 2 (skica); drugu vrijednost poslužitelj 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 Hrvatsku +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 njezin se početak postavlja na trenutak aktivacije. Kampanja s budućim početkom prelazi u stanje objavljena i pokreće se na planirani dan.

Sustav zatim ponovno izračunava plan reprodukcije i šalje ga na pogođene uređaje. Kod povezanih uređaja to obično traje desetke sekundi; nepovezani uređaj preuzima plan nakon ponovne uspostave 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 skupinama pa podaci nisu dostupni u stvarnom vremenu. Značenje podataka opisuje Izvještaj kampanje.

Pauziranje, zaustavljanje i brisanje

# pauziranje aktivne kampanje, ponovni poziv je ponovno 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 ponovno pokreće. Prije poziva zato provjerite trenutačno stanje kampanje (state u detalju). Zaustavljenu kampanju nije moguće ponovno pokrenuti, ali ostaje na popisu zajedno s izvještajima. Izbrisana kampanja nestaje s popisa.

Pregled adresa

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

Račun

Mediji

Kampanje

Lokacije i uređaji

Izvještaji

Šifrarnici

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

Stanje kampanje (state)

Vrste medija

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

Dozvole

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

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

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

Kodovi pogrešaka

Cjeloviti primjer

Skripta obavlja cijeli postupak od učitavanja slike do aktivacije kampanje na svim uređajima Tvrtke. 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 Tvrtke
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) predložak kampanje
curl -sf -u "$AUTH" "$API/api/campaign/company/$COMPANY" > predlozak.json

# 4) uređivanje predloška
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 }]
    }]
' predlozak.json > kampanja.json

# 5) izrada skice
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"