Dokumentace SSP API

API platformy na straně nabídky pro platformy programatické reklamy

API v1

Vyžaduje se token SSP typu Bearer

Vysoká propustnost

Základní adresa URL

https://polads.eu/api/v1

Omezení počtu požadavků

Vysoká propustnost pro programatické platformy

GET /online-advertisement/{PAID}

10 000 požadavků za minutu

Limit počtu požadavků se uplatňuje pro každý token SSP zvlášť

PUT /online-advertisement/{PAID}/metrics

1 000 požadavků za minutu

Počítá se zvlášť pro každý token SSP a odděleně od koncového bodu pro štítek, takže hlášení metrik nikdy nespotřebuje váš limit požadavků na štítek

GET

/online-advertisement/{PAID}

Získejte formátovaný štítek transparentnosti pro online reklamy

📊 Kompaktní formát štítku

Tento koncový bod vrací kompaktní štítek transparentnosti v souladu s předpisy EU, vhodný k zobrazení vedle online reklam. Funguje pouze pro reklamy s médiem = "online".

Token Bearer SSP

PA-ID

Příklad požadavku

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

Příklad odpovědi

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

Pole odpovědi

text

string

Formátovaný text štítku

link

string

URL stránky transparentnosti

PAID

string

Identifikátor politické reklamy

Příklad použití

Zobrazte štítek na své platformě:

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

Nahlásit metriky interakcí

PUT

/online-advertisement/{PAID}/metrics

Nahlaste kumulativní počty zobrazení a interakcí u zveřejněného oznámení, které jste doručili

Váš token SSP potřebuje oprávnění metrics:write. Administrátor je zapne pro token, který již používáte, takže se žádný nový token nevydává.

Odesílejte vždy průběžné součty od zveřejnění oznámení, nikdy změnu od svého posledního odeslání. Každé odeslání nahradí předchozí údaje, takže opětovné odeslání stejných součtů nic nezmění.

Údaje můžete nahlásit u jakéhokoli zveřejněného oznámení bez ohledu na to, kterému vydavateli patří. Objeví se v jeho veřejném oznámení o transparentnosti spolu s datem, kdy byly naposledy nahlášeny.

Příklad požadavku

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

Pole požadavku

viewsCount

integer

Počet zobrazení reklamy od zveřejnění

engagementsCount

integer

Počet interakcí s reklamou ve formě kliknutí, označení „líbí se mi“ a komentářů od zveřejnění

Obě pole jsou povinná a každé musí obsahovat celé číslo od 0 do 2147483647.

Příklad odpovědi

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

Chybové odpovědi tohoto koncového bodu

401 INVALID_TOKEN

Chybí hlavička Authorization nebo je token neznámý, odvolaný či se jedná o partnerský token. V obou případech se vrací 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 nebylo mu uděleno oprávnění metrics:write. Požádejte svého správce, aby je zapnul.

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

404 NOT_FOUND

Tomuto PA-ID neodpovídá žádné zveřejněné oznámení. Stejně jako u koncového bodu pro štítek vrací 404 také oznámení, které jeho vydavatel dosud neschválil nebo jehož datum zahájení zveřejnění dosud nenastalo.

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

409 METRICS_NOT_APPLICABLE

Oznámení nespadá do rozsahu, pro který jsou metriky interakcí definovány. Poznámka 15 přílohy II se vztahuje na online nebo nativní oznámení, u něhož byly použity techniky cílení nebo techniky doručování reklamních sdělení a jehož zobrazování již začalo. Nic se nezapisuje.

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

400 INVALID_METRICS

Tělo požadavku není platný JSON, nebo některý z obou počtů chybí, je záporný či není celé číslo. Odpověď uvádí, co neproš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

Byl překročen limit pro daný token. Odpověď 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"
}

Ověření

Formát hlavičky

Authorization: Bearer YOUR_SSP_TOKEN

Formát tokenu

64znakový hexadecimální řetězec (256bitová entropie)

Správa tokenů

Tokeny SSP spravují pouze systémoví administrátoři. Chcete-li získat token, obraťte se na svého administrátora.

Požadavky na přístup

Neuplatňuje se žádný tarif předplatného

Token SSP se vydává integrátorovi, nikoli vydavateli, proto k němu nepatří žádný účet vydavatele a není žádný tarif k ověření. Na rozdíl od partnerského API zde nic nezávisí na předplatném. Partnerský token je na tomto koncovém bodě odmítnut s kódem 401 a token SSP je stejným způsobem odmítnut na partnerských koncových bodech.

Kdy koncový bod vrací 404

Oznámení se vyhledává podle stejného pravidla viditelnosti jako ve veřejném rejstříku. Oznámení, které dosud není potvrzeno, které jeho vydavatel dosud neschválil nebo jehož datum zahájení zveřejnění je teprve v budoucnosti, vrací 404. Kód 404 proto není důkazem, že je PA-ID chybné.

Odznak transparentnosti

Tytéž informace, vykreslené pro právě zobrazovanou reklamu

Koncový bod výše vrací jednořádkový TEXT štítku pro štítek, který vykresluje vaše vlastní platforma. Odznak vrací vykreslené interaktivní oznámení, které umístíte vedle reklamy do vloženého rámu (iframe). Obojí popisuje totéž oznámení o transparentnosti.

Jedna adresa URL pro každou verzi

Ovládací prvky ukázky odpovídají těmto parametrům jedna ku jedné, takže můžete volbu provést na stránce ukázky a zkopírovat adresu URL, kterou uvidíte.

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

# Rohový odznak s popisem
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Trvale viditelný pruh s označením
GET https://polads.eu/badge/{PA-ID}?layout=label

Co jednotlivé parametry dělají a co znamená jejich vynechání

layout=label vybere pruh. Bez něj se zobrazí rohový odznak. variant=labelled zobrazí na zavřeném odznaku jeho popis. Bez něj zůstane jen značka. w a h udávají místo, do kterého je odznak vložen, a určují, jak se zjednoduší v omezeném prostoru. Pokud je vynecháte, odznak předpokládá, že má dost místa, což je pro standardní formáty správné.

hover=0 patří k ukázce, ne na vaši stránku

Vynutí rozvržení bez najetí myší, aby ukázka mohla zobrazit dotykovou verzi v prohlížeči na počítači. Skutečný odznak si zařízení ověří sám. Pokud hodnotu napevno nastavíte, zobrazíte nesprávnou verzi každému návštěvníkovi, jehož zařízení tomu neodpovídá.

Posluchač změny velikosti je povinný

Rohový odznak se načte ve velikosti 32 krát 32, aby co nejméně zakrýval reklamní motiv, a při otevření požádá hostitelskou stránku o místo. Bez posluchače se vůbec nemůže otevřít. Pruh se štítkem se při nedostatku místa chová šetrněji a ořízne se jen při malé šířce.

Dostupné pouze pro zveřejněné oznámení

Odznak se poskytuje, jakmile je oznámení potvrzeno, schváleno vydavatelem a nastalo datum zahájení jeho zveřejnění. PA-ID pod embargem nebo bez schválení vrací 404 záměrně, nikoli v důsledku chyby.

Otevřít interaktivní ukázku a zkopírovat kód pro vložení

Chybové odpovědi

Každá chyba vrací tělo JSON s chybovou zprávou a každá odpověď obsahuje hlavičku X-API-Version. Koncový bod pro štítek nevrací žádné pole se strojově čitelným kódem, řiďte se proto jeho stavovým kódem HTTP, nikoli obsahem těla. Chyby koncového bodu pro metriky kód obsahují a jsou uvedeny výše u tohoto koncového bodu.

401 Neoprávněné

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

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

400 Chybný požadavek

Inzerát byl nalezen, ale jeho médium není online. Odpověď vrací skutečnou hodnotu média, například print. Chybějící nebo neznámé PA-ID vrací místo toho 404.

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

404 Nenalezeno

{
  "error": "Advertisement not found"
}

429 Překročen limit počtu požadavků

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

Verzování a ukončování podpory

Toto je verze API v1 a každá odpověď to uvádí v hlavičce X-API-Version. Nekompatibilní změny se zavádějí pod novou cestou, tato cesta se nemění. Koncový bod v1 nebude vypnut bez hlavičky Deprecation odeslané nejméně 90 dní předem, v souladu s RFC 8594.

Strojově čitelná specifikace

Úplný dokument OpenAPI 3.1 je k dispozici na /api/docs. Nasměrujte na něj přímo Postman, Swagger UI nebo generátor klienta, místo abyste tuto stránku opisovali.

https://polads.eu/api/docs

Provádíte integraci jako mediální nebo vydavatelský partner? Přečtěte si dokumentaci partnerského API

Dokumentace SSP API

API platformy na straně nabídky pro platformy programatické reklamy

API v1

Vyžaduje se token SSP typu Bearer

Vysoká propustnost

Základní adresa URL

https://polads.eu/api/v1

Omezení počtu požadavků

Vysoká propustnost pro programatické platformy

GET /online-advertisement/{PAID}

10 000 požadavků za minutu

Limit počtu požadavků se uplatňuje pro každý token SSP zvlášť

PUT /online-advertisement/{PAID}/metrics

1 000 požadavků za minutu

Počítá se zvlášť pro každý token SSP a odděleně od koncového bodu pro štítek, takže hlášení metrik nikdy nespotřebuje váš limit požadavků na štítek

GET

/online-advertisement/{PAID}

Získejte formátovaný štítek transparentnosti pro online reklamy

📊 Kompaktní formát štítku

Tento koncový bod vrací kompaktní štítek transparentnosti v souladu s předpisy EU, vhodný k zobrazení vedle online reklam. Funguje pouze pro reklamy s médiem = "online".

Token Bearer SSP

PA-ID

Příklad požadavku

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

Příklad odpovědi

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

Pole odpovědi

text

string

Formátovaný text štítku

link

string

URL stránky transparentnosti

PAID

string

Identifikátor politické reklamy

Příklad použití

Zobrazte štítek na své platformě:

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

Nahlásit metriky interakcí

PUT

/online-advertisement/{PAID}/metrics

Nahlaste kumulativní počty zobrazení a interakcí u zveřejněného oznámení, které jste doručili

Váš token SSP potřebuje oprávnění metrics:write. Administrátor je zapne pro token, který již používáte, takže se žádný nový token nevydává.

Příklad požadavku

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

Pole požadavku

viewsCount

integer

Počet zobrazení reklamy od zveřejnění

engagementsCount

integer

Počet interakcí s reklamou ve formě kliknutí, označení „líbí se mi“ a komentářů od zveřejnění

Obě pole jsou povinná a každé musí obsahovat celé číslo od 0 do 2147483647.

Příklad odpovědi

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

Chybové odpovědi tohoto koncového bodu

401 INVALID_TOKEN

Chybí hlavička Authorization nebo je token neznámý, odvolaný či se jedná o partnerský token. V obou případech se vrací 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 nebylo mu uděleno oprávnění metrics:write. Požádejte svého správce, aby je zapnul.

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

Tělo požadavku není platný JSON, nebo některý z obou počtů chybí, je záporný či není celé číslo. Odpověď uvádí, co neproš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

Byl překročen limit pro daný token. Odpověď 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"
}

Ověření

Formát hlavičky

Authorization: Bearer YOUR_SSP_TOKEN

Formát tokenu

64znakový hexadecimální řetězec (256bitová entropie)

Správa tokenů

Tokeny SSP spravují pouze systémoví administrátoři. Chcete-li získat token, obraťte se na svého administrátora.

Požadavky na přístup

Neuplatňuje se žádný tarif předplatného

Kdy koncový bod vrací 404

Odznak transparentnosti

Tytéž informace, vykreslené pro právě zobrazovanou reklamu

Jedna adresa URL pro každou verzi

Ovládací prvky ukázky odpovídají těmto parametrům jedna ku jedné, takže můžete volbu provést na stránce ukázky a zkopírovat adresu URL, kterou uvidíte.

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

# Rohový odznak s popisem
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Trvale viditelný pruh s označením
GET https://polads.eu/badge/{PA-ID}?layout=label

Co jednotlivé parametry dělají a co znamená jejich vynechání

hover=0 patří k ukázce, ne na vaši stránku

Posluchač změny velikosti je povinný

Dostupné pouze pro zveřejněné oznámení

Otevřít interaktivní ukázku a zkopírovat kód pro vložení

Chybové odpovědi

401 Neoprávněné

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

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

400 Chybný požadavek

Inzerát byl nalezen, ale jeho médium není online. Odpověď vrací skutečnou hodnotu média, například print. Chybějící nebo neznámé PA-ID vrací místo toho 404.

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

404 Nenalezeno

{
  "error": "Advertisement not found"
}

429 Překročen limit počtu požadavků

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

Verzování a ukončování podpory

Strojově čitelná specifikace

Úplný dokument OpenAPI 3.1 je k dispozici na /api/docs. Nasměrujte na něj přímo Postman, Swagger UI nebo generátor klienta, místo abyste tuto stránku opisovali.

https://polads.eu/api/docs

Provádíte integraci jako mediální nebo vydavatelský partner? Přečtěte si dokumentaci partnerského API