Dokumentacija API za SSP
API platforme na strani ponudbe za platforme programatičnega oglaševanja
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 zahtev na minuto
Omejitev števila zahtev velja za posamezen žeton SSP
PUT /online-advertisement/{PAID}/metrics
1000 zahtev na minuto
Šteje se za vsak žeton SSP posebej in ločeno od končne točke za oznako, zato poročanje o meritvah nikoli ne porabi vaših zahtev za oznako
/online-advertisement/{PAID}📊 Kompaktna oblika oznake
Ta končna točka vrne kompaktno oznako preglednosti, ki je skladna s predpisi EU in primerna za prikaz ob spletnih oglasih. Deluje samo za oglase, pri katerih je medij = "online".
Primer zahteve
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Primer odziva
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Polja odziva
Primer uporabe
Prikažite oznako na svoji platformi:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsVaš žeton SSP potrebuje dovoljenje metrics:write. Skrbnik ga vklopi za žeton, ki ga že uporabljate, zato se nov žeton ne izda.
Pošiljajte sprotne skupne vsote od objave obvestila, nikoli pa razlike od zadnjega pošiljanja. Vsako pošiljanje nadomesti prejšnje podatke, zato ponovno pošiljanje enakih vsot ničesar ne spremeni.
Podatke lahko sporočite za katero koli objavljeno obvestilo, ne glede na to, kateremu izdajatelju pripada. Podatki se prikažejo v njegovem javnem obvestilu o preglednosti skupaj z datumom, ko so bili nazadnje sporočeni.
Primer zahteve
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 zahteve
Obe polji sta obvezni, vsako je celo število od 0 do 2147483647.
Primer odziva
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Odzivi z napako, ki jih vrne ta končna točka
401 INVALID_TOKEN
Glava Authorization manjka ali pa je žeton neznan, preklican ali partnerski. V obeh primerih se vrne koda 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
Žeton je veljaven, vendar mu dovoljenje metrics:write ni bilo dodeljeno. Prosite skrbnika, naj ga vklopi.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Temu PA-ID ne ustreza nobeno objavljeno obvestilo. Tako kot pri končni točki za oznako tudi obvestilo, ki ga njegov izdajatelj še ni odobril ali katerega datum začetka objave je še v prihodnosti, vrne kodo 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
Obvestilo ne spada na področje, za katero so opredeljene meritve angažiranosti. Opomba 15 Priloge II zajema spletno ali nativno obvestilo, pri katerem so bile uporabljene tehnike ciljanja ali tehnike prikazovanja oglasov in katerega prikazovanje se je že začelo. Ničesar se ne zapiše.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
Telo zahteve ni veljaven JSON ali pa števili manjkata, sta negativni ali nista celi števili. V odzivu je navedeno, kaj ni uspelo.
{
"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
Omejitev števila zahtev na žeton je bila presežena. Odziv vsebuje glave X-RateLimit-Limit, X-RateLimit-Remaining in X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Oblika glave
Authorization: Bearer YOUR_SSP_TOKENOblika žetona
64-mestni šestnajstiški niz (256-bitna entropija)
Upravljanje žetonov
Žetone SSP upravljajo samo sistemski skrbniki. Za pridobitev žetona se obrnite na svojega skrbnika.
Naročniški paket tu ne velja
Žeton SSP se izda integratorju in ne izdajatelju, zato ni povezan z nobenim računom izdajatelja in ni paketa, ki bi ga bilo treba preveriti. Za razliko od partnerskega vmesnika API tukaj nič ni odvisno od naročnine. Partnerski žeton je na tej končni točki zavrnjen s kodo 401, žeton SSP pa je na enak način zavrnjen na partnerskih končnih točkah.
Kdaj končna točka vrne 404
Obvestilo se poišče po istem pravilu vidnosti kot v javnem registru. Obvestilo, ki še ni potrjeno, ki ga njegov izdajatelj še ni odobril ali katerega datum začetka objave je še v prihodnosti, vrne 404. Koda 404 torej ni dokaz, da je PA-ID napačen.
Zgornja končna točka vrne enovrstično BESEDILO oznake za oznako, ki jo izriše vaša lastna platforma. Oznaka preglednosti vrne izrisano, interaktivno obvestilo, ki ga kot vgrajeni okvir postavite ob oglas. Obe opisujeta isto obvestilo o preglednosti.
En URL za vsako različico
Vsak upravljalni element v predstavitvi ustreza natanko enemu od teh parametrov, zato lahko izbirate na predstavitveni strani in kopirate prikazani URL.
# Kotna oznaka, samo znak
GET https://polads.eu/badge/{PA-ID}
# Kotna oznaka z besedilom
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Vedno viden trak z oznako
GET https://polads.eu/badge/{PA-ID}?layout=labelKaj počne vsak parameter in kaj pomeni, če ga izpustite
layout=label izbere trak. Če ga izpustite, se prikaže kotna oznaka. variant=labelled na zaprti oznaki prikaže besedilo. Če ga izpustite, se prikaže samo znak. w in h določata prostor, v katerem je oznaka, in izbereta, kako se oznaka prilagodi v tesnem prostoru. Če ju izpustite, oznaka predpostavi, da ima dovolj prostora, kar je pravilno za standardne formate.
hover=0 je za predstavitev, ne za vašo stran
Vsili postavitev brez kazalca, da lahko predstavitev v namiznem brskalniku pokaže različico za zaslone na dotik. Prava oznaka napravo preveri sama. Če vrednost trdno nastavite, pošljete napačno različico vsakemu obiskovalcu, katerega naprava se s tem ne ujema.
Poslušalec spremembe velikosti je obvezen
Kotna oznaka se naloži v velikosti 32 krat 32, da prekrije čim manj oglasnega gradiva, ob odprtju pa gostiteljsko stran zaprosi za prostor. Brez poslušalca se sploh ne more odpreti. Trak z oznako se prilagodi bolj postopno in se obreže le pri majhnih širinah.
Na voljo le za objavljeno obvestilo
Oznaka se prikaže, ko je obvestilo potrjeno, ko ga je izdajatelj odobril in ko je minil datum začetka objave. PA-ID pod embargom ali brez odobritve namenoma vrne 404, to ni posledica napake.
Odprite interaktivno predstavitev in kopirajte kodo za vgradnjo
401 Nepooblaščeno
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Neveljavna zahteva
Oglas je bil najden, vendar njegov medij ni online. Odziv vrne dejansko vrednost medija, na primer print. Manjkajoč ali neznan PA-ID namesto tega vrne 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Ni najdeno
{
"error": "Advertisement not found"
}429 Presežena omejitev števila zahtev
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}To je različica API v1, kar vsak odziv navede v glavi X-API-Version. Nezdružljive spremembe se objavijo na novi poti, ta pa ostane nespremenjena. Končna točka v1 ne bo izklopljena, ne da bi bila vsaj 90 dni prej poslana glava Deprecation, skladno z RFC 8594.
Strojno berljiva specifikacija
Celoten dokument OpenAPI 3.1 je na voljo na /api/docs. Postman, Swagger UI ali generator odjemalcev usmerite neposredno nanj, namesto da prepisujete to stran.
https://polads.eu/api/docs