Documentația API SSP
API pentru platforme de ofertă (SSP), destinat platformelor de publicitate programatică
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 de solicitări pe minut
Limita se aplică pentru fiecare jeton SSP
PUT /online-advertisement/{PAID}/metrics
1.000 de solicitări pe minut
Se contorizează pentru fiecare jeton SSP, separat de punctul final pentru etichete, astfel încât raportarea indicatorilor nu vă consumă niciodată solicitările pentru etichete
/online-advertisement/{PAID}📊 Format compact al etichetei
Acest punct final returnează o etichetă de transparență compactă, conformă cu normele UE, potrivită pentru afișarea alături de materialele publicitare online. Funcționează doar pentru materialele publicitare cu medium = "online".
Exemplu de solicitare
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Exemplu de răspuns
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Câmpurile răspunsului
Exemplu de utilizare
Afișați eticheta pe platforma dumneavoastră:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsJetonul dumneavoastră SSP are nevoie de permisiunea metrics:write. Un administrator o activează pentru jetonul pe care îl folosiți deja, așa că nu se emite niciun jeton nou.
Trimiteți totalurile cumulate de la publicarea notificării, niciodată diferența față de ultima dumneavoastră trimitere. Fiecare trimitere înlocuiește cifrele anterioare, așa că retrimiterea acelorași totaluri nu schimbă nimic.
Puteți raporta orice notificare publicată, indiferent de editorul căruia îi aparține. Cifrele apar în notificarea publică privind transparența, împreună cu data ultimei raportări.
Exemplu de solicitare
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}'Câmpurile solicitării
Ambele câmpuri sunt obligatorii, fiecare fiind un număr întreg de la 0 la 2147483647.
Exemplu de răspuns
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Răspunsuri de eroare ale acestui punct final
401 INVALID_TOKEN
Antetul Authorization lipsește sau jetonul este necunoscut, revocat ori este un jeton de partener. În ambele cazuri se returnează codul 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
Jetonul este valid, dar nu i s-a acordat permisiunea metrics:write. Cereți administratorului dumneavoastră să o activeze.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Nicio notificare publicată nu corespunde acestui PA-ID. La fel ca la punctul final pentru etichete, o notificare pe care editorul său nu a aprobat-o încă sau a cărei dată de începere a publicării este încă în viitor returnează, de asemenea, 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
Notificarea se află în afara domeniului pentru care sunt definiți indicatorii de interacțiune. Nota 15 din anexa II vizează o notificare online sau nativă pentru care s-au folosit tehnici de vizare a unui public-țintă sau tehnici de distribuire a materialelor publicitare și care a început să fie difuzată. Nu se înregistrează nimic.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
Corpul solicitării nu este JSON valid sau cele două valori lipsesc, sunt negative ori nu sunt numere întregi. Răspunsul indică ce nu a trecut verificarea.
{
"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
Limita pentru fiecare jeton a fost depășită. Răspunsul conține antetele X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Formatul antetului
Authorization: Bearer YOUR_SSP_TOKENFormatul jetonului
Șir hexazecimal de 64 de caractere (entropie de 256 de biți)
Gestionarea jetoanelor
Jetoanele SSP sunt gestionate numai de administratorii de sistem. Contactați administratorul dumneavoastră pentru a obține un jeton.
Nu se aplică niciun plan de abonament
Un jeton SSP este emis unui integrator, nu unui editor, deci nu este asociat cu niciun cont de editor și nu există niciun plan de verificat. Spre deosebire de API-ul pentru parteneri, aici nimic nu depinde de un abonament. Un jeton de partener este respins pe acest punct final cu 401, iar un jeton SSP este respins în același mod pe punctele finale pentru parteneri.
Când punctul final returnează 404
Notificarea este identificată după aceeași regulă de vizibilitate ca în registrul public. O notificare care nu este încă confirmată, pe care editorul său nu a aprobat-o încă sau a cărei dată de începere a publicării este încă în viitor returnează 404. Prin urmare, un 404 nu dovedește că un PA-ID este greșit.
Punctul final de mai sus returnează TEXTUL etichetei pe un singur rând, pentru o etichetă pe care o afișează propria dumneavoastră platformă. Insigna returnează o notificare interactivă, gata afișată, pe care o plasați lângă reclamă într-un cadru iframe. Ambele descriu aceeași notificare privind transparența.
Câte un URL pentru fiecare versiune
Comenzile demonstrației corespund unu la unu acestor parametri, așa că puteți alege în pagina de demonstrație și copia adresa pe care o vedeți.
# Insignă de colț, doar semnul
GET https://polads.eu/badge/{PA-ID}
# Insignă de colț cu textul afișat
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Bandă de etichetă vizibilă permanent
GET https://polads.eu/badge/{PA-ID}?layout=labelCe face fiecare parametru și ce înseamnă omiterea lui
layout=label selectează banda de etichetă. Dacă îl omiteți, se afișează insigna de colț. variant=labelled face ca insigna închisă să își afișeze textul. Dacă îl omiteți, rămâne doar semnul. w și h declară spațiul în care se află insigna și stabilesc cum se adaptează aceasta într-un spațiu restrâns. Dacă le omiteți, insigna presupune că are loc suficient, ceea ce este corect pentru formatele standard.
hover=0 este pentru demonstrație, nu pentru pagina dumneavoastră
Impune aspectul destinat dispozitivelor fără cursor, pentru ca demonstrația să poată arăta versiunea tactilă într-un browser de desktop. Insigna reală verifică singură dispozitivul. Dacă fixați această valoare în cod, trimiteți versiunea greșită fiecărui vizitator al cărui dispozitiv nu corespunde.
Ascultătorul de evenimente de redimensionare este obligatoriu
Insigna de colț se încarcă la 32 pe 32 pentru a acoperi cât mai puțin din reclamă, apoi cere spațiu paginii gazdă atunci când se deschide. Fără acest ascultător, nu se poate deschide deloc. Banda de etichetă se adaptează mai ușor și se taie doar la lățimi înguste.
Disponibilă doar pentru o notificare publicată
Insigna este furnizată după ce notificarea este confirmată, aprobată de editor și după ce data de începere a publicării a trecut. Pentru un PA-ID sub embargo sau neaprobat se returnează 404 în mod intenționat, nu din cauza unei erori.
Deschideți demonstrația interactivă și copiați codul de încorporare
401 Neautorizat
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Cerere incorectă
Anunțul a fost găsit, dar mediul său nu este online. Răspunsul returnează valoarea reală a mediului, de exemplu print. Un PA-ID lipsă sau necunoscut returnează în schimb 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Nu a fost găsit
{
"error": "Advertisement not found"
}429 Limita de cereri a fost depășită
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Aceasta este versiunea v1 a API-ului, iar fiecare răspuns o indică în antetul X-API-Version. Modificările incompatibile sunt publicate pe o cale nouă, fără a o schimba pe aceasta. Un punct final v1 nu va fi dezactivat fără un antet Deprecation transmis cu cel puțin 90 de zile înainte, conform RFC 8594.
Specificație care poate fi citită automat
Documentul OpenAPI 3.1 complet este disponibil la /api/docs. Conectați Postman, Swagger UI sau un generator de clienți direct la acesta, în loc să transcrieți această pagină.
https://polads.eu/api/docs