SSP-API-documentatie
SSP-API (aanbodplatform) voor programmatische advertentieplatforms
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 verzoeken per minuut
De aanvraaglimiet geldt per SSP-token
PUT /online-advertisement/{PAID}/metrics
1.000 verzoeken per minuut
Geteld per SSP-token, los van het label-eindpunt, zodat het melden van cijfers nooit ten koste gaat van uw labelverzoeken
/online-advertisement/{PAID}📊 Compact labelformaat
Dit eindpunt geeft een compact transparantielabel terug dat aan de EU-regels voldoet en geschikt is om naast online advertenties te tonen. Werkt alleen voor advertenties met medium = "online".
Voorbeeldverzoek
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Responsvoorbeeld
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Responsvelden
Gebruiksvoorbeeld
Toon het label op uw platform:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsUw SSP-token heeft het recht metrics:write nodig. Een beheerder schakelt dat in voor het token dat u al gebruikt, dus er wordt geen nieuw token uitgegeven.
Stuur de lopende totalen sinds de publicatie van de transparantieverklaring, nooit de wijziging sinds uw vorige levering. Elke levering vervangt de eerdere cijfers, dus dezelfde totalen opnieuw sturen verandert niets.
U kunt cijfers melden voor elke gepubliceerde transparantieverklaring, ongeacht bij welke uitgever die hoort. De cijfers verschijnen op de openbare transparantieverklaring zelf, met de datum waarop ze het laatst zijn gemeld.
Voorbeeldverzoek
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}'Verzoekvelden
Beide velden zijn verplicht, elk een geheel getal van 0 tot en met 2147483647.
Responsvoorbeeld
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Foutresponsen van dit eindpunt
401 INVALID_TOKEN
De Authorization-header ontbreekt, of het token is onbekend, ingetrokken of een partnertoken. In beide gevallen is de code 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
Het token is geldig, maar heeft het recht metrics:write niet gekregen. Vraag uw beheerder om dat in te schakelen.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Geen enkele gepubliceerde transparantieverklaring komt overeen met dat PA-ID. Net als bij het label-eindpunt geeft een transparantieverklaring ook 404 terug als de uitgever die nog niet heeft goedgekeurd of als de startdatum van publicatie nog in de toekomst ligt.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
De transparantieverklaring valt buiten het toepassingsgebied waarvoor interactiecijfers zijn gedefinieerd. Bijlage II, noot 15, heeft betrekking op een transparantieverklaring voor een online of ingebedde politieke reclameboodschap waarvoor targetingtechnieken of technieken voor de aanlevering van een reclameboodschap zijn gebruikt en waarvan de verspreiding is begonnen. Er wordt niets opgeslagen.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
De inhoud van het verzoek is geen geldige JSON, of de twee aantallen ontbreken, zijn negatief of zijn geen gehele getallen. De respons vermeldt wat er niet klopte.
{
"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
De limiet per token is overschreden. De respons bevat X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Headerformaat
Authorization: Bearer YOUR_SSP_TOKENTokenformaat
Hexadecimale tekenreeks van 64 tekens (256 bits entropie)
Tokenbeheer
SSP-tokens worden uitsluitend door systeembeheerders beheerd. Neem contact op met uw beheerder om een token te verkrijgen.
Er geldt geen abonnement
Een SSP-token wordt uitgegeven aan een integrator en niet aan een uitgever. Er is dus geen uitgeversaccount aan gekoppeld en er valt geen abonnement te controleren. Anders dan bij de partner-API hangt hier niets af van een abonnement. Een partnertoken wordt op dit eindpunt geweigerd met 401, en een SSP-token wordt op dezelfde manier geweigerd op de partnereindpunten.
Wanneer het eindpunt 404 teruggeeft
De transparantieverklaring wordt opgezocht volgens dezelfde zichtbaarheidsregel als het openbare register. Een transparantieverklaring die nog niet is bevestigd, die de uitgever nog niet heeft goedgekeurd of waarvan de begindatum van publicatie nog in de toekomst ligt, geeft 404 terug. Een 404 bewijst dus niet dat een PA-ID onjuist is.
Het eindpunt hierboven geeft de TEKST van het label van één regel terug, voor een label dat uw eigen platform zelf weergeeft. De markering geeft een kant-en-klare, interactieve transparantieverklaring terug die u als iframe naast de advertentie plaatst. Beide beschrijven dezelfde transparantieverklaring.
Eén URL per versie
De bedieningselementen van de demo komen één op één overeen met deze parameters. U kunt dus op de demopagina kiezen en de URL kopiëren die u ziet.
# Hoekmarkering, alleen het merkteken
GET https://polads.eu/badge/{PA-ID}
# Hoekmarkering met tekst
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Altijd zichtbare labelbalk
GET https://polads.eu/badge/{PA-ID}?layout=labelWat elke parameter doet en wat het betekent als u hem weglaat
layout=label kiest de labelbalk. Laat u deze parameter weg, dan krijgt u de hoekmarkering. variant=labelled laat de gesloten markering haar tekst tonen. Laat u deze parameter weg, dan ziet u alleen het merkteken. w en h geven de ruimte op waarin de markering staat en bepalen hoe zij zich aanpast bij weinig ruimte. Laat u ze weg, dan gaat de markering ervan uit dat er ruimte genoeg is, wat klopt voor de standaardformaten.
hover=0 is bedoeld voor de demo, niet voor uw pagina
Deze parameter dwingt de weergave zonder aanwijzer af, zodat de demo de aanraakversie in een desktopbrowser kan tonen. De echte markering controleert het apparaat zelf. Legt u de waarde vast, dan krijgt elke bezoeker van wie het apparaat anders werkt de verkeerde versie.
De luisteraar voor formaatwijzigingen is verplicht
De hoekmarkering laadt op 32 bij 32, zodat zij zo weinig mogelijk van de advertentie bedekt, en vraagt de omringende pagina om ruimte wanneer zij opengaat. Zonder de luisteraar kan zij helemaal niet opengaan. De labelbalk past zich soepeler aan en wordt alleen bij smalle breedtes afgekapt.
Alleen beschikbaar voor een gepubliceerde transparantieverklaring
De markering wordt geleverd zodra de transparantieverklaring is bevestigd, door de uitgever is goedgekeurd en de startdatum van publicatie is verstreken. Een PA-ID onder embargo of zonder goedkeuring geeft bewust 404 terug en niet door een fout.
401 Ongeautoriseerd
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Ongeldig verzoek
De advertentie is gevonden, maar het medium is niet online. De reactie geeft de werkelijke mediumwaarde terug, bijvoorbeeld print. Een ontbrekend of onbekend PA-ID geeft in plaats daarvan 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Niet gevonden
{
"error": "Advertisement not found"
}429 Aanvraaglimiet overschreden
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Dit is API-versie v1, en elke respons vermeldt dat in een kopveld X-API-Version. Incompatibele wijzigingen verschijnen onder een nieuw pad in plaats van dat dit pad wordt gewijzigd. Een v1-eindpunt wordt pas uitgeschakeld nadat er minstens 90 dagen vooraf een Deprecation-kopveld is meegestuurd, conform RFC 8594.
Machineleesbare specificatie
Het volledige OpenAPI 3.1-document staat op /api/docs. Richt Postman, Swagger UI of een clientgenerator daar rechtstreeks op in plaats van deze pagina over te typen.
https://polads.eu/api/docs