Dokumentácia API pre SSP

API platformy na strane ponuky pre programatické reklamné platformy

API v1

Vyžaduje sa token SSP typu Bearer

Vysoká priepustnosť

Základná adresa URL

https://polads.eu/api/v1

Obmedzenie počtu požiadaviek

Vysoká priepustnosť pre programatické platformy

GET /online-advertisement/{PAID}

10 000 požiadaviek za minútu

Limit počtu požiadaviek sa uplatňuje na každý token SSP

PUT /online-advertisement/{PAID}/metrics

1 000 požiadaviek za minútu

Počíta sa pre každý token SSP oddelene od koncového bodu pre označenie, takže nahlasovanie metrík nikdy nevyčerpá váš limit požiadaviek na označenie

GET

/online-advertisement/{PAID}

Získanie formátovaného označenia transparentnosti pre online reklamy

📊 Kompaktný formát označenia

Tento koncový bod vracia kompaktné označenie transparentnosti v súlade s predpismi EÚ, vhodné na zobrazenie vedľa online reklám. Funguje len pre reklamy, ktorých médium je "online".

Token Bearer SSP

PA-ID

Príklad požiadavky

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

Príklad odpovede

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

Polia odpovede

text

string

Formátovaný text označenia

link

string

URL stránky transparentnosti

PAID

string

Identifikátor politickej reklamy

Príklad použitia

Zobrazte označenie na svojej platforme:

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

Nahlasovanie metrík interakcií

PUT

/online-advertisement/{PAID}/metrics

Nahlasovanie kumulatívnych počtov zobrazení a interakcií zverejneného oznámenia, ktoré ste doručili

Váš token SSP potrebuje oprávnenie metrics:write. Správca ho zapne pre token, ktorý už používate, takže sa nevydáva žiadny nový token.

Posielajte vždy priebežné súčty od zverejnenia oznámenia, nikdy zmenu od svojho posledného odoslania. Každé odoslanie nahradí predchádzajúce údaje, takže opätovné odoslanie rovnakých súčtov nič nezmení.

Údaje môžete nahlásiť pri akomkoľvek zverejnenom oznámení bez ohľadu na to, ktorému vydavateľovi patrí. Objavia sa v jeho verejnom oznámení o transparentnosti spolu s dátumom, kedy boli naposledy nahlásené.

Príklad požiadavky

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}'

Polia požiadavky

viewsCount

integer

Počet zobrazení reklamy od zverejnenia

engagementsCount

integer

Počet interakcií s reklamou v podobe kliknutí, označení „páči sa mi to“ a komentárov od zverejnenia

Obe polia sú povinné a každé musí byť celé číslo od 0 do 2147483647.

Príklad odpovede

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

Chybové odpovede tohto koncového bodu

401 INVALID_TOKEN

Chýba hlavička Authorization alebo je token neznámy, odvolaný či ide o partnerský token. V oboch prípadoch sa vracia kód 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 platný, ale nebolo mu udelené oprávnenie metrics:write. Požiadajte svojho správcu, aby ho zapol.

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

404 NOT_FOUND

Tomuto PA-ID nezodpovedá žiadne zverejnené oznámenie. Rovnako ako pri koncovom bode pre označenie vráti 404 aj oznámenie, ktoré jeho vydavateľ ešte neschválil alebo ktorého dátum začiatku zverejnenia ešte nenastal.

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

409 METRICS_NOT_APPLICABLE

Oznámenie nepatrí do rozsahu, pre ktorý sú metriky interakcií vymedzené. Poznámka 15 v prílohe II sa vzťahuje na online alebo natívne oznámenie, pri ktorom sa použili techniky cielenia alebo techniky dodávania reklamy a ktoré sa už začalo zobrazovať. Nič sa nezapisuje.

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

400 INVALID_METRICS

Telo požiadavky nie je platný JSON alebo niektorý z dvoch počtov chýba, je záporný alebo nie je celé číslo. Odpoveď uvádza, čo neprešlo kontrolou.

{
  "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

Limit pre token bol prekročený. Táto odpoveď obsahuje hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset.

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

Autentifikácia

Formát hlavičky

Authorization: Bearer YOUR_SSP_TOKEN

Formát tokenu

64-znakový hexadecimálny reťazec (256-bitová entropia)

Správa tokenov

Tokeny SSP spravujú iba správcovia systému. Ak chcete získať token, obráťte sa na svojho správcu.

Požiadavky na prístup

Neuplatňuje sa žiadny plán predplatného

Token SSP sa vydáva integrátorovi, nie vydavateľovi, takže nie je viazaný na žiadny účet vydavateľa a neoveruje sa žiadny plán. Na rozdiel od partnerského API tu nič nezávisí od predplatného. Partnerský token tento koncový bod odmietne s kódom 401 a token SSP rovnako odmietnu partnerské koncové body.

Kedy koncový bod vráti 404

Oznámenie sa vyhľadáva podľa rovnakého pravidla viditeľnosti ako vo verejnom registri. Pre oznámenie, ktoré ešte nie je potvrdené, ktoré jeho vydavateľ ešte neschválil alebo ktorého dátum začiatku zverejnenia ešte nenastal, koncový bod vráti 404. Kód 404 preto nie je dôkazom, že PA-ID je nesprávne.

Odznak transparentnosti

Tie isté informácie, vykreslené pre práve zobrazovanú reklamu

Koncový bod vyššie vracia jednoriadkový TEXT označenia pre prípad, že označenie vykresľuje vaša vlastná platforma. Odznak vracia vykreslené interaktívne oznámenie, ktoré umiestnite vedľa reklamy ako prvok iframe. Obidve opisujú to isté oznámenie o transparentnosti.

Jedna adresa URL pre každú verziu

Každý ovládací prvok ukážky zodpovedá práve jednému z týchto parametrov, takže si môžete vybrať na stránke ukážky a skopírovať adresu URL, ktorú vidíte.

# Rohový odznak, iba značka
GET https://polads.eu/badge/{PA-ID}

# Rohový odznak so zobrazeným textom
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Stále viditeľný pás s označením
GET https://polads.eu/badge/{PA-ID}?layout=label

Čo robí každý parameter a čo znamená jeho vynechanie

layout=label vyberie pás s označením. Ak ho vynecháte, zobrazí sa rohový odznak. variant=labelled zobrazí text na zatvorenom odznaku. Ak ho vynecháte, zobrazí sa len samotná značka. w a h udávajú rozmery miesta, v ktorom je odznak umiestnený, a určujú, ako sa odznak prispôsobí v stiesnenom priestore. Ak ich vynecháte, odznak predpokladá, že má dostatok miesta, čo je pre štandardné formáty správne.

hover=0 je určený pre ukážku, nie pre vašu stránku

Vynúti rozloženie pre zariadenia bez ukazovateľa myši, aby ukážka mohla zobraziť dotykovú verziu v prehliadači na počítači. Skutočný odznak si typ zariadenia zistí sám. Ak hodnotu napevno nastavíte, pošlete nesprávnu verziu každému návštevníkovi, ktorého zariadenie je iného typu.

Poslucháč zmeny veľkosti je nevyhnutný

Rohový odznak sa načíta vo veľkosti 32 krát 32, aby zakryl čo najmenšiu časť kreatívy, a keď sa otvára, požiada hostiteľskú stránku o miesto. Bez poslucháča sa nemôže otvoriť vôbec. Pás s označením sa v stiesnenom priestore prispôsobuje miernejšie a oreže sa len pri malých šírkach.

Dostupné len pre zverejnené oznámenie

Odznak sa poskytuje, keď je oznámenie potvrdené, schválené vydavateľom a nastal dátum začiatku jeho zverejnenia. PA-ID pod embargom alebo bez schválenia odpovedá kódom 404 zámerne, nie v dôsledku chyby.

Otvoriť interaktívnu ukážku a skopírovať kód na vloženie

Chybové odpovede

Každá chyba vracia telo JSON s chybovou správou a každá odpoveď obsahuje hlavičku X-API-Version. Koncový bod pre označenie nevracia pole so strojovo čitateľným kódom, riaďte sa preto jeho stavovým kódom HTTP, nie telom odpovede. Chyby koncového bodu pre metriky kód obsahujú a sú uvedené vyššie pri tomto koncovom bode.

401 Neoprávnené

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

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

400 Chybná požiadavka

Inzerát sa našiel, ale jeho médium nie je online. Odpoveď vracia skutočnú hodnotu média, napríklad print. Chýbajúce alebo neznáme PA-ID vráti namiesto toho 404.

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

404 Nenájdené

{
  "error": "Advertisement not found"
}

429 Prekročený limit počtu požiadaviek

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

Verziovanie a ukončovanie podpory

Toto je verzia API v1 a každá odpoveď to uvádza v hlavičke X-API-Version. Zmeny narúšajúce kompatibilitu sa vydávajú pod novou cestou, táto cesta sa nemení. Koncový bod v1 nebude vypnutý bez hlavičky Deprecation odoslanej najmenej 90 dní vopred, v súlade s RFC 8594.

Strojovo čitateľná špecifikácia

Úplný dokument OpenAPI 3.1 je dostupný na adrese /api/docs. Nasmerujte naň priamo Postman, Swagger UI alebo generátor klienta, namiesto toho, aby ste túto stránku prepisovali.

https://polads.eu/api/docs

Integrujete sa ako mediálny alebo vydavateľský partner? Prečítajte si dokumentáciu partnerského API

Dokumentácia API pre SSP

API platformy na strane ponuky pre programatické reklamné platformy

API v1

Vyžaduje sa token SSP typu Bearer

Vysoká priepustnosť

Základná adresa URL

https://polads.eu/api/v1

Obmedzenie počtu požiadaviek

Vysoká priepustnosť pre programatické platformy

GET /online-advertisement/{PAID}

10 000 požiadaviek za minútu

Limit počtu požiadaviek sa uplatňuje na každý token SSP

PUT /online-advertisement/{PAID}/metrics

1 000 požiadaviek za minútu

Počíta sa pre každý token SSP oddelene od koncového bodu pre označenie, takže nahlasovanie metrík nikdy nevyčerpá váš limit požiadaviek na označenie

GET

/online-advertisement/{PAID}

Získanie formátovaného označenia transparentnosti pre online reklamy

📊 Kompaktný formát označenia

Tento koncový bod vracia kompaktné označenie transparentnosti v súlade s predpismi EÚ, vhodné na zobrazenie vedľa online reklám. Funguje len pre reklamy, ktorých médium je "online".

Token Bearer SSP

PA-ID

Príklad požiadavky

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

Príklad odpovede

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

Polia odpovede

text

string

Formátovaný text označenia

link

string

URL stránky transparentnosti

PAID

string

Identifikátor politickej reklamy

Príklad použitia

Zobrazte označenie na svojej platforme:

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

Nahlasovanie metrík interakcií

PUT

/online-advertisement/{PAID}/metrics

Nahlasovanie kumulatívnych počtov zobrazení a interakcií zverejneného oznámenia, ktoré ste doručili

Váš token SSP potrebuje oprávnenie metrics:write. Správca ho zapne pre token, ktorý už používate, takže sa nevydáva žiadny nový token.

Príklad požiadavky

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}'

Polia požiadavky

viewsCount

integer

Počet zobrazení reklamy od zverejnenia

engagementsCount

integer

Počet interakcií s reklamou v podobe kliknutí, označení „páči sa mi to“ a komentárov od zverejnenia

Obe polia sú povinné a každé musí byť celé číslo od 0 do 2147483647.

Príklad odpovede

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

Chybové odpovede tohto koncového bodu

401 INVALID_TOKEN

Chýba hlavička Authorization alebo je token neznámy, odvolaný či ide o partnerský token. V oboch prípadoch sa vracia kód 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 platný, ale nebolo mu udelené oprávnenie metrics:write. Požiadajte svojho správcu, aby ho zapol.

{
  "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

Telo požiadavky nie je platný JSON alebo niektorý z dvoch počtov chýba, je záporný alebo nie je celé číslo. Odpoveď uvádza, čo neprešlo kontrolou.

{
  "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

Limit pre token bol prekročený. Táto odpoveď obsahuje hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset.

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

Autentifikácia

Formát hlavičky

Authorization: Bearer YOUR_SSP_TOKEN

Formát tokenu

64-znakový hexadecimálny reťazec (256-bitová entropia)

Správa tokenov

Tokeny SSP spravujú iba správcovia systému. Ak chcete získať token, obráťte sa na svojho správcu.

Požiadavky na prístup

Neuplatňuje sa žiadny plán predplatného

Kedy koncový bod vráti 404

Odznak transparentnosti

Tie isté informácie, vykreslené pre práve zobrazovanú reklamu

Jedna adresa URL pre každú verziu

Každý ovládací prvok ukážky zodpovedá práve jednému z týchto parametrov, takže si môžete vybrať na stránke ukážky a skopírovať adresu URL, ktorú vidíte.

# Rohový odznak, iba značka
GET https://polads.eu/badge/{PA-ID}

# Rohový odznak so zobrazeným textom
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Stále viditeľný pás s označením
GET https://polads.eu/badge/{PA-ID}?layout=label

Čo robí každý parameter a čo znamená jeho vynechanie

hover=0 je určený pre ukážku, nie pre vašu stránku

Poslucháč zmeny veľkosti je nevyhnutný

Dostupné len pre zverejnené oznámenie

Otvoriť interaktívnu ukážku a skopírovať kód na vloženie

Chybové odpovede

401 Neoprávnené

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

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

400 Chybná požiadavka

Inzerát sa našiel, ale jeho médium nie je online. Odpoveď vracia skutočnú hodnotu média, napríklad print. Chýbajúce alebo neznáme PA-ID vráti namiesto toho 404.

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

404 Nenájdené

{
  "error": "Advertisement not found"
}

429 Prekročený limit počtu požiadaviek

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

Verziovanie a ukončovanie podpory

Strojovo čitateľná špecifikácia

Úplný dokument OpenAPI 3.1 je dostupný na adrese /api/docs. Nasmerujte naň priamo Postman, Swagger UI alebo generátor klienta, namiesto toho, aby ste túto stránku prepisovali.

https://polads.eu/api/docs

Integrujete sa ako mediálny alebo vydavateľský partner? Prečítajte si dokumentáciu partnerského API