SSP API-dokumentáció
Kínálati oldali platformok API-ja programmatikus hirdetési platformok számára
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10 000 kérés percenként
A kérésszám-korlát SSP-tokenenként érvényes
PUT /online-advertisement/{PAID}/metrics
1000 kérés percenként
SSP-tokenenként, a címkevégponttól elkülönítve számítjuk, így a mutatók jelentése soha nem használja fel a címkekérésekre szánt keretét
/online-advertisement/{PAID}📊 Kompakt címkeformátum
Ez a végpont kompakt, az uniós előírásoknak megfelelő átláthatósági címkét ad vissza, amely online hirdetések mellett jeleníthető meg. Csak a medium = "online" értékű hirdetéseknél működik.
Példakérés
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Válaszpélda
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Válaszmezők
Használati példa
Jelenítse meg a címkét a saját platformján:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsAz SSP-tokenjének metrics:write engedélyre van szüksége. Ezt egy rendszergazda kapcsolja be az Ön által már használt tokenre, így nem adunk ki új tokent.
A közlemény közzététele óta göngyölített összesített értékeket küldje, soha ne a legutóbbi beküldése óta bekövetkezett változást. Minden beküldés felülírja a korábbi adatokat, így ugyanazon összesített értékek ismételt elküldése semmin sem változtat.
Bármely közzétett közleményhez jelenthet adatokat, függetlenül attól, melyik kiadóhoz tartozik. Az adatok a hozzá tartozó nyilvános átláthatósági közleményben jelennek meg, a legutóbbi jelentés dátumával együtt.
Példakérés
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}'Kérésmezők
Mindkét mező kötelező, és mindkettő 0 és 2147483647 közötti egész szám.
Válaszpélda
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}A végpont hibaválaszai
401 INVALID_TOKEN
Hiányzik az Authorization fejléc, vagy a token ismeretlen, visszavont vagy partnertoken. Mindkét esetben INVALID_TOKEN kód érkezik.
{
"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
A token érvényes, de nem kapta meg a metrics:write engedélyt. Kérje meg a rendszergazdáját, hogy kapcsolja be.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
A megadott PA-ID egyetlen közzétett közleménynek sem felel meg. A címkevégponthoz hasonlóan 404-es kód érkezik akkor is, ha a közleményt a kiadója még nem hagyta jóvá, vagy ha a közzététel kezdőnapja még a jövőben van.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
A közlemény kívül esik azon a körön, amelyre az interakciós mutatók vonatkoznak. A II. melléklet 15. megjegyzése olyan online vagy natív közleményre terjed ki, amely célzott hirdetési technikákat vagy reklámeljuttatási technikákat alkalmazott, és amelynek megjelenítése már megkezdődött. Nem történik adatrögzítés.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
A kérés törzse nem érvényes JSON, vagy a két számérték hiányzik, negatív vagy nem egész szám. A válasz felsorolja, mi nem felelt meg.
{
"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
A kérések száma túllépte a tokenenkénti korlátot. A válasz tartalmazza az X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejlécet.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Fejlécformátum
Authorization: Bearer YOUR_SSP_TOKENTokenformátum
64 karakteres hexadecimális karakterlánc (256 bites entrópia)
Tokenkezelés
Az SSP-tokeneket kizárólag a rendszergazdák kezelik. Token igényléséhez forduljon a rendszergazdájához.
Nem vonatkozik rá előfizetési csomag
Az SSP-tokent integrátor kapja, nem kiadó, ezért nem tartozik hozzá kiadói fiók, és nincs ellenőrizendő csomag. A partner API-val ellentétben itt semmi sem függ előfizetéstől. Ez a végpont a partnertokent 401-es kóddal elutasítja, és a partnervégpontok ugyanígy elutasítják az SSP-tokent.
Mikor ad vissza a végpont 404-et
A közleményt ugyanazzal a láthatósági szabállyal keressük ki, mint a nyilvános nyilvántartásban. 404-et ad vissza az a közlemény, amelyet még nem erősítettek meg, amelyet a kiadója még nem hagyott jóvá, vagy amelynek közzétételi kezdő dátuma még a jövőben van. A 404 tehát nem bizonyítja, hogy a PA-ID hibás.
A fenti végpont az egysoros címke szövegét adja vissza olyan címkéhez, amelyet a saját platformja jelenít meg. A jelvény kész, interaktív közleményt ad vissza, amelyet beágyazott keretként (iframe) helyez el a hirdetés mellett. Mindkettő ugyanazt az átláthatósági közleményt írja le.
Változatonként egy URL
A bemutató kezelőelemei egy az egyben megfelelnek ezeknek a paramétereknek, így a bemutatóoldalon kiválaszthatja a kívánt változatot, és kimásolhatja a megjelenő URL-t.
# Sarokjelvény, csak a jelzés
GET https://polads.eu/badge/{PA-ID}
# Sarokjelvény felirattal
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Mindig látható címkesáv
GET https://polads.eu/badge/{PA-ID}?layout=labelMire szolgálnak az egyes paraméterek, és mi történik, ha kihagyja őket
A layout=label a sávot választja ki. Ha kihagyja, a sarokjelvény jelenik meg. A variant=labelled hatására a zárt jelvény a feliratát is mutatja. Ha kihagyja, csak a jelzés látszik. A w és a h megadja a helyet, amelyben a jelvény elhelyezkedik, és meghatározza, hogyan alkalmazkodik szűk helyen. Ha kihagyja őket, a jelvény abból indul ki, hogy elegendő helye van, ami a szabványos formátumoknál helytálló.
A hover=0 a bemutatóhoz készült, ne használja a saját oldalán
Kikényszeríti az egérmutató nélküli elrendezést, hogy a bemutató asztali böngészőben is megmutathassa az érintőképernyős változatot. A valódi jelvény maga vizsgálja meg az eszközt. Ha rögzíti az értéket, minden olyan látogatónak rossz változatot küld, akinek az eszköze ettől eltér.
Az átméretezési eseményfigyelő kötelező
A sarokjelvény 32-szer 32-es méretben töltődik be, hogy a lehető legkevesebbet takarja el a kreatívból, majd megnyitáskor helyet kér a befogadó oldaltól. Az eseményfigyelő nélkül egyáltalán nem tud megnyílni. A címkesáv kíméletesebben alkalmazkodik, és csak keskeny szélességnél vágódik le.
Csak közzétett közleményhez érhető el
A jelvényt akkor szolgáljuk ki, amikor a közleményt megerősítették, a kiadó jóváhagyta, és a közzététel kezdő dátuma már elmúlt. A közzétételi tilalom alatt álló vagy jóvá nem hagyott PA-ID szándékosan, nem hiba miatt ad 404-et.
Nyissa meg az interaktív bemutatót, és másolja ki a beágyazási kódot
401 Jogosulatlan
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Hibás kérés
A hirdetés megvan, de a médiuma nem online. A válasz a tényleges médiumértéket adja vissza, például print. A hiányzó vagy ismeretlen PA-ID helyette 404-et ad.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Nem található
{
"error": "Advertisement not found"
}429 Kéréskorlát túllépve
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Ez az API v1-es verziója, és ezt minden válasz jelzi az X-API-Version fejlécben. A visszafelé nem kompatibilis változások új útvonalon jelennek meg, ez az útvonal nem változik. Egy v1-es végpontot csak akkor kapcsolunk ki, ha legalább 90 nappal előtte Deprecation fejlécet küldünk, az RFC 8594 szerint.
Géppel olvasható specifikáció
A teljes OpenAPI 3.1 dokumentum a /api/docs címen érhető el. Irányítsa a Postmant, a Swagger UI-t vagy egy klienskódgenerátort közvetlenül oda, ahelyett, hogy ezt az oldalt másolná át.
https://polads.eu/api/docs