Dokumentacija partnerskog API-ja

API s podacima o političkim oglasima za medijske organizacije i izdavače

API v1

Potreban je partnerski token nositelja

U skladu s GDPR-om

Osnovni URL

https://polads.eu/api/v1

Sve krajnje točke zahtijevaju autentifikaciju partnerskim tokenom nositelja

Ograničenje broja zahtjeva

Sve partnerske krajnje točke dijele isto ograničenje broja zahtjeva po tokenu nositelja

GET /advertisement-full/{PAID}

1000 zahtjeva u minuti

GET /advertisement/{PAID}

1000 zahtjeva u minuti

Ograničenje broja zahtjeva primjenjuje se po partnerskom tokenu na svim krajnjim točkama

Uvjeti pristupa

Što partnerski token mora ispunjavati da bi ijedna krajnja točka odgovorila

Plan Pro, provjerava se pri svakom zahtjevu

Partnerski API dio je plana Pro, i za čitanje i za pisanje. Ne postoji zaseban dodatak za API koji bi trebalo kupiti. Plan se provjerava pri svakom pojedinom zahtjevu, a ne bilježi se pri stvaranju tokena, pa istekla pretplata prekida pristup već pri sljedećem pozivu uz odgovor 403 PRO_PLAN_REQUIRED, a obnova ga jednako trenutačno vraća.

Opsezi pristupa

Svaki partnerski token može čitati. Za prijavu mjernih podataka o angažmanu dodatno je potreban opseg pristupa metrics:write. Opsezi se biraju pri izdavanju tokena i poslije se ne mogu mijenjati: da biste ih promijenili, opozovite token i izdajte novi.

Samo partnerski tokeni

Ove krajnje točke odbijaju SSP token uz kod 401, a SSP krajnja točka na isti način odbija partnerski token. Te dvije vrste tokena zasebne su vjerodajnice, a ne dvije razine dopuštenja unutar jedne.

Kada krajnja točka vrati 404

Kod 404 nije dokaz da je PA-ID pogrešan

GET /advertisement/{PAID} pronalazi obavijest prema istom pravilu vidljivosti kao javni registar. Obavijest koja još nije potvrđena, koju njezin izdavač još nije odobrio ili čiji je datum početka objave još u budućnosti ovdje vraća 404 jednako kao u registru. Isto vrijedi i za SSP krajnju točku.

Krajnja točka za potpuni zapis namjerno je drukčija

Krajnja točka GET /advertisement-full/{PAID} ograničena je na vaše vlastite obavijesti, pa odgovara i za obavijest čiji datum početka još nije nastupio. Vi ste izdavač koji tu obavijest mora pregledati prije početka objave, pa bi njezino uskraćivanje vama poništilo svrhu.

GET

/advertisement-full/{PAID}

Dohvatite potpune podatke o oglasu, uključujući SVA polja osjetljiva s gledišta GDPR-a (potreban je Bearer token)

Ograničeno na vaše vlastite obavijesti. PA-ID drugog izdavača, samostalno objavljena obavijest bez izdavača i identifikator koji ne postoji svi vraćaju isti kod 404, a odgovor ih ne razlikuje.

⚠️ Upozorenje: podaci osjetljivi s gledišta GDPR-a

Ova krajnja točka vraća SVA polja, uključujući adrese e-pošte, brojeve telefona i pune adrese. Koristite je samo ako imate legitimnu poslovnu potrebu i sklopljene odgovarajuće ugovore o obradi podataka.

Token Bearer

PA-ID

Primjer zahtjeva

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

Odgovor sadržava (NEFILTRIRANO)

Polja oglašivača:

companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country

Polja kampanje:

name, totalValue, medium, isOngoing, startDate, endDate

Oglašivači i voditelji obrade:

Sva polja, uključujući e-poštu, telefone i pune adrese

Prijava mjernih podataka o angažmanu

PUT

/advertisement/{PAID}/metrics

Šaljite podatke o broju prikaza i angažmanu nakon objave za vlastite obavijesti.

Ova krajnja točka zahtijeva ključ s opsegom Čitanje i pisanje. Partnerski API uključen je u plan Pro.

Mjerne podatke možete prijaviti samo za obavijesti objavljene putem vlastitog računa.

Obavijest pripada drugom izdavaču. Ništa se ne zapisuje.

Primjer zahtjeva

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

Dostupna polja

Podatkovna polja koja vraća API, s njihovim vrstama

Osnovne informacije

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Usklađenost i financiranje

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Ciljanje

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Pravni podaci i metapodaci

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

označava neobavezno polje koje može biti bez vrijednosti ili prazno

Primjeri koda

// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();

Odgovori s pogreškom

Svaka pogreška vraća tijelo u formatu JSON s porukom o pogrešci, a svaki odgovor sadrži zaglavlje X-API-Version. Strojno čitljiv kod prati odbijanja zbog nevažećeg tokena i zbog plana te vlastite pogreške provjere krajnje točke metrics. Nedostajuće zaglavlje Authorization, pogreška 404 ili 429 s krajnje točke za čitanje i bilo koja unutarnja pogreška poslužitelja sadrže samo poruku.

401 INVALID_TOKEN

Nijedan aktivni token ne odgovara vjerodajnici Bearer ili je token opozvan. Nedostajuće ili neispravno zaglavlje Authorization također daje odgovor 401, ali ga samo krajnja točka metrics označava ovim kodom. SSP token na partnerskoj krajnjoj točki dobiva isti odgovor.

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Invalid or revoked partner API token. This endpoint only accepts partner tokens, not SSP tokens.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

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

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

403 PRO_PLAN_REQUIRED

Token je valjan, ali njegov izdavač nema plan Pro. Plan se provjerava prije opsega, pa token samo za čitanje koji pripada izdavaču bez plana Pro vraća pogrešku o planu, a ne o opsegu.

GET /advertisement/{PAID}GET /advertisement-full/{PAID}PUT /advertisement/{PAID}/metrics

{
  "error": "The Pro plan is required to use the partner API.",
  "code": "PRO_PLAN_REQUIRED"
}

403 INSUFFICIENT_SCOPE

Token je valjan i ima plan Pro, ali mu nedostaje opseg metrics:write potreban za prijavu mjernih podataka.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Obavijest pripada drugom izdavaču. Ništa se ne zapisuje.

PUT /advertisement/{PAID}/metrics

{
  "error": "This advertisement belongs to a different publisher.",
  "code": "FORBIDDEN"
}

400 INVALID_METRICS

Tijelo zahtjeva nije valjan JSON ili dva broja nedostaju, negativna su ili nisu cijeli brojevi. Odgovor navodi što nije prošlo provjeru.

PUT /advertisement/{PAID}/metrics

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

PUT /advertisement/{PAID}/metrics

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

409 METRICS_NOT_APPLICABLE

Oglas je izvan područja za koje su definirani mjerni podaci o angažmanu. Napomena 15 Priloga II obuhvaća internetski ili nativni oglas pri kojem su korištene tehnike ciljanja ili tehnike isporuke oglasa i koji se već počeo prikazivati. Ništa se ne zapisuje.

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Nijedan oglas ne odgovara tom identifikatoru PA-ID ili vam još nije vidljiv. Pročitajte gornji odjeljak prije nego što zaključite da je identifikator pogrešan.

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}

{
  "error": "Advertisement not found"
}

GET /advertisement-full/{PAID}

{
  "error": "Advertisement not found or not yet confirmed"
}

429 RATE_LIMITED

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

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

Verzioniranje i povlačenje

Ovo je verzija API-ja v1 i svaki odgovor to navodi u zaglavlju X-API-Version. Promjene koje narušavaju kompatibilnost objavljuju se na novoj putanji umjesto da mijenjaju ovu. Krajnja točka v1 neće biti isključena bez zaglavlja Deprecation poslanog najmanje 90 dana unaprijed, u skladu s RFC 8594.

Strojno čitljiva specifikacija

Cjeloviti dokument OpenAPI 3.1 dostupan je na /api/docs. Usmjerite Postman, Swagger UI ili generator klijenta izravno na njega umjesto da prepisujete ovu stranicu.

https://polads.eu/api/docs

Integrirate se kao platforma na strani ponude? Pročitajte dokumentaciju SSP API-ja

Dokumentacija partnerskog API-ja

API s podacima o političkim oglasima za medijske organizacije i izdavače

API v1

Potreban je partnerski token nositelja

U skladu s GDPR-om

Osnovni URL

https://polads.eu/api/v1

Sve krajnje točke zahtijevaju autentifikaciju partnerskim tokenom nositelja

Ograničenje broja zahtjeva

Sve partnerske krajnje točke dijele isto ograničenje broja zahtjeva po tokenu nositelja

GET /advertisement-full/{PAID}

1000 zahtjeva u minuti

GET /advertisement/{PAID}

1000 zahtjeva u minuti

Ograničenje broja zahtjeva primjenjuje se po partnerskom tokenu na svim krajnjim točkama

Uvjeti pristupa

Što partnerski token mora ispunjavati da bi ijedna krajnja točka odgovorila

Plan Pro, provjerava se pri svakom zahtjevu

Opsezi pristupa

Samo partnerski tokeni

Kada krajnja točka vrati 404

Kod 404 nije dokaz da je PA-ID pogrešan

Krajnja točka za potpuni zapis namjerno je drukčija

GET

/advertisement-full/{PAID}

Dohvatite potpune podatke o oglasu, uključujući SVA polja osjetljiva s gledišta GDPR-a (potreban je Bearer token)

Ograničeno na vaše vlastite obavijesti. PA-ID drugog izdavača, samostalno objavljena obavijest bez izdavača i identifikator koji ne postoji svi vraćaju isti kod 404, a odgovor ih ne razlikuje.

⚠️ Upozorenje: podaci osjetljivi s gledišta GDPR-a

Token Bearer

PA-ID

Primjer zahtjeva

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

Odgovor sadržava (NEFILTRIRANO)

Polja oglašivača:

companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country

Polja kampanje:

name, totalValue, medium, isOngoing, startDate, endDate

Oglašivači i voditelji obrade:

Sva polja, uključujući e-poštu, telefone i pune adrese

Prijava mjernih podataka o angažmanu

PUT

/advertisement/{PAID}/metrics

Šaljite podatke o broju prikaza i angažmanu nakon objave za vlastite obavijesti.

Ova krajnja točka zahtijeva ključ s opsegom Čitanje i pisanje. Partnerski API uključen je u plan Pro.

Mjerne podatke možete prijaviti samo za obavijesti objavljene putem vlastitog računa.

Obavijest pripada drugom izdavaču. Ništa se ne zapisuje.

Primjer zahtjeva

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

Dostupna polja

Podatkovna polja koja vraća API, s njihovim vrstama

Osnovne informacije

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Usklađenost i financiranje

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Ciljanje

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Pravni podaci i metapodaci

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

označava neobavezno polje koje može biti bez vrijednosti ili prazno

Primjeri koda

// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();

Odgovori s pogreškom

401 INVALID_TOKEN

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Invalid or revoked partner API token. This endpoint only accepts partner tokens, not SSP tokens.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

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

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

403 PRO_PLAN_REQUIRED

Token je valjan, ali njegov izdavač nema plan Pro. Plan se provjerava prije opsega, pa token samo za čitanje koji pripada izdavaču bez plana Pro vraća pogrešku o planu, a ne o opsegu.

GET /advertisement/{PAID}GET /advertisement-full/{PAID}PUT /advertisement/{PAID}/metrics

{
  "error": "The Pro plan is required to use the partner API.",
  "code": "PRO_PLAN_REQUIRED"
}

403 INSUFFICIENT_SCOPE

Token je valjan i ima plan Pro, ali mu nedostaje opseg metrics:write potreban za prijavu mjernih podataka.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Obavijest pripada drugom izdavaču. Ništa se ne zapisuje.

PUT /advertisement/{PAID}/metrics

{
  "error": "This advertisement belongs to a different publisher.",
  "code": "FORBIDDEN"
}

400 INVALID_METRICS

Tijelo zahtjeva nije valjan JSON ili dva broja nedostaju, negativna su ili nisu cijeli brojevi. Odgovor navodi što nije prošlo provjeru.

PUT /advertisement/{PAID}/metrics

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

PUT /advertisement/{PAID}/metrics

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

409 METRICS_NOT_APPLICABLE

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Nijedan oglas ne odgovara tom identifikatoru PA-ID ili vam još nije vidljiv. Pročitajte gornji odjeljak prije nego što zaključite da je identifikator pogrešan.

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}

{
  "error": "Advertisement not found"
}

GET /advertisement-full/{PAID}

{
  "error": "Advertisement not found or not yet confirmed"
}

429 RATE_LIMITED

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

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

Verzioniranje i povlačenje

Strojno čitljiva specifikacija

Cjeloviti dokument OpenAPI 3.1 dostupan je na /api/docs. Usmjerite Postman, Swagger UI ili generator klijenta izravno na njega umjesto da prepisujete ovu stranicu.

https://polads.eu/api/docs

Integrirate se kao platforma na strani ponude? Pročitajte dokumentaciju SSP API-ja