Dokumentacija za SSP API

API platforme na strani ponude za platforme za programatsko oglašavanje

API v1

Potreban SSP Bearer token

Visoka propusnost

Osnovni URL

https://polads.eu/api/v1

Ograničenje brzine

Visoka propusnost za programatske platforme

GET /online-advertisement/{PAID}

10.000 zahtjeva u minuti

Ograničenje brzine primjenjuje se po SSP tokenu

PUT /online-advertisement/{PAID}/metrics

1000 zahtjeva u minuti

Broji se zasebno za svaki SSP token i odvojeno od krajnje točke za oznaku, pa prijava mjernih podataka nikad ne troši vaše zahtjeve za oznaku

GET

/online-advertisement/{PAID}

Dohvatite oblikovanu oznaku transparentnosti za internetske oglase

📊 Kompaktni format oznake

Ova krajnja točka vraća kompaktnu oznaku transparentnosti usklađenu s pravom EU-a, prikladnu za prikaz uz internetske oglase. Radi samo za oglase kod kojih je medium = "online".

SSP token Bearer

PA-ID

Primjer zahtjeva

curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
  -H "Authorization: Bearer YOUR_SSP_TOKEN" \
  -H "Accept: application/json"

Primjer odgovora

{
  "text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
  "link": "https://polads.eu/ABC12",
  "PAID": "ABC12"
}

Polja odgovora

text

string

Oblikovani tekst oznake

link

string

URL stranice o transparentnosti

PAID

string

Identifikator političkog oglasa

Primjer upotrebe

Prikažite oznaku na svojoj platformi:

<a href="[link]" target="_blank" rel="noopener">
  [text]
</a>

Prijava mjernih podataka o angažmanu

PUT

/online-advertisement/{PAID}/metrics

Prijavite kumulativni broj pregleda i interakcija za objavljenu obavijest koju ste isporučili

Vaš SSP token treba dopuštenje metrics:write. Administrator ga uključuje za token koji već upotrebljavate, pa se ne izdaje novi token.

Šaljite tekuće ukupne vrijednosti od objave obavijesti, nikad promjenu od svoje posljednje isporuke. Svaka isporuka zamjenjuje prethodne podatke, pa ponovno slanje istih ukupnih vrijednosti ništa ne mijenja.

Podatke možete prijaviti za bilo koju objavljenu obavijest, bez obzira na to kojem izdavaču pripada. Podaci se prikazuju u njezinoj javnoj obavijesti o transparentnosti zajedno s datumom posljednje prijave.

Primjer zahtjeva

curl -X PUT "https://polads.eu/api/v1/online-advertisement/ABC12/metrics" \
  -H "Authorization: Bearer YOUR_SSP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"viewsCount": 15000, "engagementsCount": 320}'

Polja zahtjeva

viewsCount

integer

Broj pregleda oglasa od objave

engagementsCount

integer

Broj interakcija s oglasom u obliku klikova, oznaka „sviđa mi se” i komentara od objave

Oba su polja obavezna, a svako mora biti cijeli broj od 0 do 2147483647.

Primjer odgovora

{
  "viewsCount": 15000,
  "engagementsCount": 320,
  "engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}

Odgovori s pogreškom koje vraća ova krajnja točka

401 INVALID_TOKEN

Zaglavlje Authorization nedostaje ili je token nepoznat, opozvan ili je riječ o partnerskom tokenu. U oba slučaja vraća se kod INVALID_TOKEN.

{
  "error": "Missing or invalid Authorization header. Expected: Bearer <token>",
  "code": "INVALID_TOKEN"
}

{
  "error": "Invalid or revoked SSP API token.",
  "code": "INVALID_TOKEN"
}

403 INSUFFICIENT_SCOPE

Token je valjan, ali mu nije dodijeljeno dopuštenje metrics:write. Zamolite svojeg administratora da ga uključi.

{
  "error": "This token is not authorised to write metrics. Required scope: metrics:write.",
  "code": "INSUFFICIENT_SCOPE"
}

404 NOT_FOUND

Za taj PA-ID ne postoji nijedna objavljena obavijest. Kao i kod krajnje točke za oznaku, 404 vraća i obavijest koju njezin izdavač još nije odobrio ili čiji je datum početka objave još u budućnosti.

{
  "error": "Advertisement not found",
  "code": "NOT_FOUND"
}

409 METRICS_NOT_APPLICABLE

Obavijest je izvan područja za koje su definirani mjerni podaci o angažmanu. Napomena 15 Priloga II. obuhvaća internetsku ili nativnu obavijest za koju su korištene tehnike ciljanja ili tehnike isporuke oglasa i čije je prikazivanje već počelo. Ništa se ne zapisuje.

{
  "error": "Engagement metrics do not apply to this notice",
  "code": "METRICS_NOT_APPLICABLE"
}

400 INVALID_METRICS

Tijelo zahtjeva nije valjan JSON ili brojevi pregleda i interakcija nedostaju, negativni su ili nisu cijeli brojevi. Odgovor navodi što nije prošlo provjeru.

{
  "error": "Invalid engagement metrics",
  "code": "INVALID_METRICS",
  "issues": [
    {
      "path": "viewsCount",
      "message": "Too small: expected number to be >=0"
    }
  ]
}

{
  "error": "Invalid request body",
  "code": "INVALID_METRICS"
}

429 RATE_LIMITED

Premašeno je ograničenje po tokenu. Odgovor sadrži zaglavlja X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "limit": 1000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Autentifikacija

Format zaglavlja

Authorization: Bearer YOUR_SSP_TOKEN

Format tokena

Heksadecimalni niz od 64 znaka (entropija od 256 bitova)

Upravljanje tokenima

SSP tokenima upravljaju samo administratori sustava. Obratite se svom administratoru da biste dobili token.

Zahtjevi za pristup

Ne primjenjuje se nijedan pretplatnički plan

SSP token izdaje se integratoru, a ne izdavaču, pa nije povezan ni s jednim računom izdavača i nema plana koji bi se provjeravao. Za razliku od partnerskog API-ja, ovdje ništa ne ovisi o pretplati. Partnerski token na ovoj se krajnjoj točki odbija s kodom 401, a SSP token na isti se način odbija na partnerskim krajnjim točkama.

Kada krajnja točka vraća 404

Obavijest se dohvaća prema istom pravilu vidljivosti kao i u javnom registru. Za obavijest koja još nije potvrđena, koju njezin izdavač još nije odobrio ili čiji je datum početka objave još u budućnosti vraća se 404. Odgovor 404 stoga nije dokaz da je PA-ID pogrešan.

Oznaka transparentnosti

Iste informacije, prikazane uz oglas koji se poslužuje

Gornja krajnja točka vraća jednoredni TEKST oznake, za oznaku koju iscrtava vaša vlastita platforma. Oznaka transparentnosti vraća gotovu, interaktivnu obavijest koju postavljate uz oglas u ugrađenom okviru. Oba prikaza opisuju istu obavijest o transparentnosti.

Jedan URL po verziji

Svaki upravljački element demonstracije odgovara točno jednom od ovih parametara, pa verziju možete odabrati na stranici s demonstracijom i kopirati URL koji vidite.

# Kutna oznaka, samo znak
GET https://polads.eu/badge/{PA-ID}

# Kutna oznaka s prikazanim tekstom
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Stalno vidljiva traka s oznakom
GET https://polads.eu/badge/{PA-ID}?layout=label

Što radi pojedini parametar i što znači ako ga izostavite

layout=label odabire traku. Bez njega se prikazuje kutna oznaka. variant=labelled prikazuje tekst na zatvorenoj oznaci. Bez njega se prikazuje samo znak. w i h navode prostor u kojem se oznaka nalazi i određuju kako se ona prilagođava kada je prostora malo. Ako ih izostavite, oznaka pretpostavlja da ima dovoljno prostora, što je ispravno za standardne formate.

hover=0 služi za demonstraciju, a ne za vašu stranicu

Nameće prikaz bez lebdenja pokazivača kako bi demonstracija mogla prikazati verziju za dodirne zaslone u stolnom pregledniku. Prava oznaka sama provjerava uređaj. Ako tu vrijednost fiksno postavite, svakom posjetitelju čiji se uređaj s njom ne slaže šaljete pogrešnu verziju.

Slušatelj promjene veličine je obavezan

Kutna oznaka učitava se u veličini 32 puta 32 kako bi prekrila što manji dio oglasnog materijala, a zatim pri otvaranju traži od stranice domaćina više prostora. Bez slušatelja uopće se ne može otvoriti. Traka s oznakom prilagođava se blaže i obrezuje se samo pri malim širinama.

Dostupno samo za objavljenu obavijest

Oznaka se poslužuje nakon što je obavijest potvrđena, nakon što ju je izdavač odobrio i nakon što je prošao datum početka objave. Za PA-ID pod embargom ili bez odobrenja odgovor 404 vraća se namjerno, a ne zbog pogreške.

Otvorite interaktivnu demonstraciju i kopirajte kod za ugradnju

Odgovori s pogreškom

Svaka pogreška vraća JSON tijelo s porukom o pogrešci, a svaki odgovor sadržava zaglavlje X-API-Version. Krajnja točka za oznaku ne vraća strojno čitljivo polje s kodom, pa se oslanjajte na njezin HTTP status, a ne na tijelo odgovora. Pogreške krajnje točke za mjerne podatke ipak sadržavaju kod i navedene su gore uz tu krajnju točku.

401 Neovlašteno

{
  "error": "Invalid or revoked SSP API token."
}

{
  "error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}

400 Neispravan zahtjev

Oglas je pronađen, ali njegov medij nije online. Odgovor vraća stvarnu vrijednost medija, primjerice print. PA-ID koji nedostaje ili je nepoznat umjesto toga vraća 404.

{
  "error": "This endpoint is only for online advertisements",
  "medium": "print"
}

404 Nije pronađeno

{
  "error": "Advertisement not found"
}

429 Prekoračeno ograničenje brzine

{
  "error": "Rate limit exceeded",
  "limit": 10000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Verzioniranje i povlačenje

Ovo je verzija API v1, a svaki odgovor to navodi u zaglavlju X-API-Version. Nekompatibilne promjene izlaze na novoj putanji umjesto da mijenjaju ovu. Krajnja točka v1 neće biti isključena bez zaglavlja Deprecation najmanje 90 dana unaprijed, u skladu s RFC 8594.

Strojno čitljiva specifikacija

Cjeloviti dokument OpenAPI 3.1 poslužuje se na /api/docs. Usmjerite Postman, Swagger UI ili generator klijenta izravno onamo umjesto da prepisujete ovu stranicu.

https://polads.eu/api/docs

Integrirate se kao medijski ili izdavački partner? Pročitajte dokumentaciju partnerskog API-ja

Dokumentacija za SSP API

API platforme na strani ponude za platforme za programatsko oglašavanje

API v1

Potreban SSP Bearer token

Visoka propusnost

Osnovni URL

https://polads.eu/api/v1

Ograničenje brzine

Visoka propusnost za programatske platforme

GET /online-advertisement/{PAID}

10.000 zahtjeva u minuti

Ograničenje brzine primjenjuje se po SSP tokenu

PUT /online-advertisement/{PAID}/metrics

1000 zahtjeva u minuti

Broji se zasebno za svaki SSP token i odvojeno od krajnje točke za oznaku, pa prijava mjernih podataka nikad ne troši vaše zahtjeve za oznaku

GET

/online-advertisement/{PAID}

Dohvatite oblikovanu oznaku transparentnosti za internetske oglase

📊 Kompaktni format oznake

Ova krajnja točka vraća kompaktnu oznaku transparentnosti usklađenu s pravom EU-a, prikladnu za prikaz uz internetske oglase. Radi samo za oglase kod kojih je medium = "online".

SSP token Bearer

PA-ID

Primjer zahtjeva

curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
  -H "Authorization: Bearer YOUR_SSP_TOKEN" \
  -H "Accept: application/json"

Primjer odgovora

{
  "text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
  "link": "https://polads.eu/ABC12",
  "PAID": "ABC12"
}

Polja odgovora

text

string

Oblikovani tekst oznake

link

string

URL stranice o transparentnosti

PAID

string

Identifikator političkog oglasa

Primjer upotrebe

Prikažite oznaku na svojoj platformi:

<a href="[link]" target="_blank" rel="noopener">
  [text]
</a>

Prijava mjernih podataka o angažmanu

PUT

/online-advertisement/{PAID}/metrics

Prijavite kumulativni broj pregleda i interakcija za objavljenu obavijest koju ste isporučili

Vaš SSP token treba dopuštenje metrics:write. Administrator ga uključuje za token koji već upotrebljavate, pa se ne izdaje novi token.

Primjer zahtjeva

curl -X PUT "https://polads.eu/api/v1/online-advertisement/ABC12/metrics" \
  -H "Authorization: Bearer YOUR_SSP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"viewsCount": 15000, "engagementsCount": 320}'

Polja zahtjeva

viewsCount

integer

Broj pregleda oglasa od objave

engagementsCount

integer

Broj interakcija s oglasom u obliku klikova, oznaka „sviđa mi se” i komentara od objave

Oba su polja obavezna, a svako mora biti cijeli broj od 0 do 2147483647.

Primjer odgovora

{
  "viewsCount": 15000,
  "engagementsCount": 320,
  "engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}

Odgovori s pogreškom koje vraća ova krajnja točka

401 INVALID_TOKEN

Zaglavlje Authorization nedostaje ili je token nepoznat, opozvan ili je riječ o partnerskom tokenu. U oba slučaja vraća se kod INVALID_TOKEN.

{
  "error": "Missing or invalid Authorization header. Expected: Bearer <token>",
  "code": "INVALID_TOKEN"
}

{
  "error": "Invalid or revoked SSP API token.",
  "code": "INVALID_TOKEN"
}

403 INSUFFICIENT_SCOPE

Token je valjan, ali mu nije dodijeljeno dopuštenje metrics:write. Zamolite svojeg administratora da ga uključi.

{
  "error": "This token is not authorised to write metrics. Required scope: metrics:write.",
  "code": "INSUFFICIENT_SCOPE"
}

404 NOT_FOUND

{
  "error": "Advertisement not found",
  "code": "NOT_FOUND"
}

409 METRICS_NOT_APPLICABLE

{
  "error": "Engagement metrics do not apply to this notice",
  "code": "METRICS_NOT_APPLICABLE"
}

400 INVALID_METRICS

Tijelo zahtjeva nije valjan JSON ili brojevi pregleda i interakcija nedostaju, negativni su ili nisu cijeli brojevi. Odgovor navodi što nije prošlo provjeru.

{
  "error": "Invalid engagement metrics",
  "code": "INVALID_METRICS",
  "issues": [
    {
      "path": "viewsCount",
      "message": "Too small: expected number to be >=0"
    }
  ]
}

{
  "error": "Invalid request body",
  "code": "INVALID_METRICS"
}

429 RATE_LIMITED

Premašeno je ograničenje po tokenu. Odgovor sadrži zaglavlja X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "limit": 1000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Autentifikacija

Format zaglavlja

Authorization: Bearer YOUR_SSP_TOKEN

Format tokena

Heksadecimalni niz od 64 znaka (entropija od 256 bitova)

Upravljanje tokenima

SSP tokenima upravljaju samo administratori sustava. Obratite se svom administratoru da biste dobili token.

Zahtjevi za pristup

Ne primjenjuje se nijedan pretplatnički plan

Kada krajnja točka vraća 404

Oznaka transparentnosti

Iste informacije, prikazane uz oglas koji se poslužuje

Jedan URL po verziji

Svaki upravljački element demonstracije odgovara točno jednom od ovih parametara, pa verziju možete odabrati na stranici s demonstracijom i kopirati URL koji vidite.

# Kutna oznaka, samo znak
GET https://polads.eu/badge/{PA-ID}

# Kutna oznaka s prikazanim tekstom
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Stalno vidljiva traka s oznakom
GET https://polads.eu/badge/{PA-ID}?layout=label

Što radi pojedini parametar i što znači ako ga izostavite

hover=0 služi za demonstraciju, a ne za vašu stranicu

Slušatelj promjene veličine je obavezan

Dostupno samo za objavljenu obavijest

Otvorite interaktivnu demonstraciju i kopirajte kod za ugradnju

Odgovori s pogreškom

401 Neovlašteno

{
  "error": "Invalid or revoked SSP API token."
}

{
  "error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}

400 Neispravan zahtjev

Oglas je pronađen, ali njegov medij nije online. Odgovor vraća stvarnu vrijednost medija, primjerice print. PA-ID koji nedostaje ili je nepoznat umjesto toga vraća 404.

{
  "error": "This endpoint is only for online advertisements",
  "medium": "print"
}

404 Nije pronađeno

{
  "error": "Advertisement not found"
}

429 Prekoračeno ograničenje brzine

{
  "error": "Rate limit exceeded",
  "limit": 10000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Verzioniranje i povlačenje

Strojno čitljiva specifikacija

Cjeloviti dokument OpenAPI 3.1 poslužuje se na /api/docs. Usmjerite Postman, Swagger UI ili generator klijenta izravno onamo umjesto da prepisujete ovu stranicu.

https://polads.eu/api/docs

Integrirate se kao medijski ili izdavački partner? Pročitajte dokumentaciju partnerskog API-ja