SSP API dokumentacija

Pasiūlos pusės platformos API programinės reklamos platformoms

API v1

Reikalingas SSP Bearer prieigos raktas

Didelis pralaidumas

Pagrindinis URL

https://polads.eu/api/v1

Užklausų dažnio ribojimas

Didelis pralaidumas programinės reklamos platformoms

GET /online-advertisement/{PAID}

10 000 užklausų per minutę

Užklausų dažnio riba taikoma kiekvienam SSP prieigos raktui atskirai

PUT /online-advertisement/{PAID}/metrics

1 000 užklausų per minutę

Užklausos skaičiuojamos kiekvienam SSP prieigos raktui atskirai, nepriklausomai nuo etiketės galinio taško, todėl rodiklių teikimas niekada nesunaudoja jūsų etiketės užklausų

GET

/online-advertisement/{PAID}

Gaukite suformatuotą internetinių reklamos skelbimų skaidrumo etiketę

📊 Kompaktiškas etiketės formatas

Šis galinis taškas grąžina kompaktišką, ES reikalavimus atitinkančią skaidrumo etiketę, tinkamą rodyti šalia internetinių reklamos skelbimų. Veikia tik su reklamos skelbimais, kurių medija = "online".

SSP Bearer prieigos raktas

PA-ID

Užklausos pavyzdys

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

Atsakymo pavyzdys

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

Atsakymo laukai

text

string

Suformatuotas etiketės tekstas

link

string

Skaidrumo puslapio URL

PAID

string

Politinės reklamos identifikatorius

Naudojimo pavyzdys

Parodykite etiketę savo platformoje:

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

Sąveikos rodiklių teikimas

PUT

/online-advertisement/{PAID}/metrics

Teikite paskelbto pranešimo, kurį pateikėte, sukauptus peržiūrų ir sąveikų skaičius

Jūsų SSP prieigos raktui reikia leidimo metrics:write. Administratorius jį įjungia jau naudojamam prieigos raktui, todėl naujas prieigos raktas neišduodamas.

Siųskite sukauptas sumas nuo pranešimo paskelbimo, o ne pokytį nuo paskutinio jūsų siuntimo. Kiekvienas siuntimas pakeičia ankstesnius skaičius, todėl pakartotinai išsiuntus tas pačias sumas niekas nepasikeičia.

Galite teikti rodiklius apie bet kurį paskelbtą pranešimą, nesvarbu, kuriam leidėjui jis priklauso. Skaičiai rodomi jo viešame skaidrumo pranešime kartu su data, kada jie paskutinį kartą buvo pateikti.

Užklausos pavyzdys

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

Užklausos laukai

viewsCount

integer

Reklamos skelbimo peržiūrų skaičius nuo paskelbimo

engagementsCount

integer

Sąveikų su reklamos skelbimu (paspaudimų, patiktukų ir komentarų) skaičius nuo paskelbimo

Abu laukai privalomi, kiekvienas iš jų yra sveikasis skaičius nuo 0 iki 2147483647.

Atsakymo pavyzdys

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

Šio galinio taško klaidų atsakymai

401 INVALID_TOKEN

Nėra Authorization antraštės arba prieigos raktas nežinomas, atšauktas ar yra partnerio prieigos raktas. Abiem atvejais grąžinamas kodas 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

Prieigos raktas galioja, tačiau jam nesuteiktas leidimas metrics:write. Paprašykite administratoriaus jį įjungti.

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

404 NOT_FOUND

Nė vienas paskelbtas pranešimas neatitinka šio PA-ID. Kaip ir etiketės galiniame taške, 404 grąžinamas ir tada, kai pranešimo leidėjas jo dar nepatvirtino arba jo paskelbimo pradžios data dar nesuėjo.

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

409 METRICS_NOT_APPLICABLE

Pranešimas nepatenka į sritį, kuriai apibrėžti sąveikos rodikliai. II priedo 15 pastaba apima internetinį arba natyvųjį pranešimą, kuriame naudoti atrankiojo adresavimo arba reklamos skelbimo pateikimo metodai ir kurio rodymas jau prasidėjo. Niekas neįrašoma.

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

400 INVALID_METRICS

Užklausos turinys nėra tinkamas JSON arba du skaičiai nepateikti, yra neigiami ar nėra sveikieji skaičiai. Atsakyme nurodoma, kas neatitiko reikalavimų.

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

Viršyta vienam prieigos raktui taikoma užklausų dažnio riba. Šiame atsakyme pateikiamos antraštės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset.

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

Autentifikavimas

Antraštės formatas

Authorization: Bearer YOUR_SSP_TOKEN

Prieigos rakto formatas

64 simbolių šešioliktainė eilutė (256 bitų entropija)

Prieigos raktų valdymas

SSP prieigos raktus valdo tik sistemos administratoriai. Norėdami gauti prieigos raktą, susisiekite su administratoriumi.

Prieigos reikalavimai

Netaikomas joks prenumeratos planas

SSP prieigos raktas išduodamas integratoriui, o ne leidėjui, todėl jis nesusietas su jokia leidėjo paskyra ir nėra plano, kurį reikėtų tikrinti. Kitaip nei partnerių API, čia niekas nepriklauso nuo prenumeratos. Partnerio prieigos raktas šiame galiniame taške atmetamas su kodu 401, o SSP prieigos raktas lygiai taip pat atmetamas partnerių galiniuose taškuose.

Kada galinis taškas grąžina 404

Pranešimas nustatomas pagal tą pačią matomumo taisyklę kaip ir viešajame registre. Jei pranešimas dar nepatvirtintas, jo leidėjas dar jo nepasirašė arba jo paskelbimo pradžios data dar nesuėjo, grąžinamas 404. Todėl 404 nėra įrodymas, kad PA-ID yra klaidingas.

Skaidrumo ženklas

Ta pati informacija, atvaizduota rodomam reklamos skelbimui

Aukščiau nurodytas galinis taškas grąžina vienos eilutės etiketės TEKSTĄ, skirtą etiketei, kurią atvaizduoja jūsų pačių platforma. Ženklas grąžina paruoštą interaktyvų pranešimą, kurį įterptiniame rėmelyje patalpinate šalia skelbimo. Abu aprašo tą patį skaidrumo pranešimą.

Po vieną URL kiekvienai versijai

Kiekvienas demonstracijos valdiklis atitinka vieną iš šių parametrų, todėl galite pasirinkti demonstraciniame puslapyje ir nukopijuoti matomą adresą.

# Kampinis ženklas, tik simbolis
GET https://polads.eu/badge/{PA-ID}

# Kampinis ženklas su užrašu
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Nuolat matoma etiketės juosta
GET https://polads.eu/badge/{PA-ID}?layout=label

Ką daro kiekvienas parametras ir ką reiškia jį praleisti

layout=label parenka juostą. Jo nenurodžius rodomas kampinis ženklas. variant=labelled uždarame ženkle parodo jo užrašą. Jo nenurodžius rodomas tik simbolis. w ir h nurodo vietą, kurioje yra ženklas, ir lemia, kaip jis supaprastinamas ankštoje vietoje. Jų nenurodžius ženklas daro prielaidą, kad vietos pakanka, ir tai tinka standartiniams formatams.

hover=0 skirtas demonstracijai, o ne jūsų puslapiui

Jis priverstinai įjungia išdėstymą be užvedimo pele, kad demonstracija galėtų parodyti jutiklinio ekrano versiją kompiuterio naršyklėje. Tikrasis ženklas įrenginį patikrina pats. Įrašę šią reikšmę į kodą, kiekvienam lankytojui, kurio įrenginys jos neatitinka, pateiksite netinkamą versiją.

Dydžio keitimo klausytojas yra privalomas

Kampinis ženklas įkeliamas 32 × 32 dydžio, kad kuo mažiau uždengtų reklaminę medžiagą, o atsidarydamas paprašo talpinančiojo puslapio daugiau vietos. Be klausytojo jis apskritai negali atsidaryti. Etiketės juosta prisitaiko švelniau ir nukerpama tik esant mažam pločiui.

Pasiekiamas tik paskelbtiems pranešimams

Ženklas pateikiamas, kai pranešimas patvirtintas, leidėjo pasirašytas ir sulaukta jo paskelbimo pradžios datos. Embargo taikomo arba leidėjo nepasirašyto PA-ID užklausai grąžinamas 404, ir taip numatyta sąmoningai, o ne dėl klaidos.

Atverkite interaktyvią demonstraciją ir nukopijuokite įterpimo kodą

Klaidų atsakymai

Kiekviena klaida grąžina JSON turinį su klaidos pranešimu, o kiekvienas atsakymas turi antraštę X-API-Version. Etiketės galinis taškas negrąžina kompiuterio nuskaitomo kodo lauko, todėl remkitės jo HTTP būsenos kodu, o ne turiniu. Rodiklių galinio taško klaidos vis dėlto turi kodą ir yra išvardytos aukščiau prie to galinio taško.

401 Neteisėta

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

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

400 Netinkama užklausa

Skelbimas rastas, bet jo medija nėra online. Atsakymas grąžina tikrąją medijos reikšmę, pavyzdžiui print. Trūkstamas ar nežinomas PA-ID vietoj to grąžina 404.

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

404 Nerasta

{
  "error": "Advertisement not found"
}

429 Viršytas užklausų limitas

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

Versijavimas ir atsisakymas

Tai yra API versija v1, ir kiekvienas atsakymas tai nurodo antraštėje X-API-Version. Suderinamumą pažeidžiantys pakeitimai išleidžiami nauju keliu, o šis nekeičiamas. Versijos v1 galinis taškas nebus išjungtas, jei ne vėliau kaip prieš 90 dienų nebus pateikta antraštė Deprecation pagal RFC 8594.

Kompiuterio nuskaitoma specifikacija

Visas OpenAPI 3.1 dokumentas pateikiamas adresu /api/docs. Nukreipkite Postman, Swagger UI ar kliento generatorių tiesiai į jį, užuot perrašinėję šį puslapį.

https://polads.eu/api/docs

Integruojatės kaip žiniasklaidos ar leidėjo partneris? Perskaitykite partnerių API dokumentaciją

SSP API dokumentacija

Pasiūlos pusės platformos API programinės reklamos platformoms

API v1

Reikalingas SSP Bearer prieigos raktas

Didelis pralaidumas

Pagrindinis URL

https://polads.eu/api/v1

Užklausų dažnio ribojimas

Didelis pralaidumas programinės reklamos platformoms

GET /online-advertisement/{PAID}

10 000 užklausų per minutę

Užklausų dažnio riba taikoma kiekvienam SSP prieigos raktui atskirai

PUT /online-advertisement/{PAID}/metrics

1 000 užklausų per minutę

Užklausos skaičiuojamos kiekvienam SSP prieigos raktui atskirai, nepriklausomai nuo etiketės galinio taško, todėl rodiklių teikimas niekada nesunaudoja jūsų etiketės užklausų

GET

/online-advertisement/{PAID}

Gaukite suformatuotą internetinių reklamos skelbimų skaidrumo etiketę

📊 Kompaktiškas etiketės formatas

SSP Bearer prieigos raktas

PA-ID

Užklausos pavyzdys

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

Atsakymo pavyzdys

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

Atsakymo laukai

text

string

Suformatuotas etiketės tekstas

link

string

Skaidrumo puslapio URL

PAID

string

Politinės reklamos identifikatorius

Naudojimo pavyzdys

Parodykite etiketę savo platformoje:

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

Sąveikos rodiklių teikimas

PUT

/online-advertisement/{PAID}/metrics

Teikite paskelbto pranešimo, kurį pateikėte, sukauptus peržiūrų ir sąveikų skaičius

Jūsų SSP prieigos raktui reikia leidimo metrics:write. Administratorius jį įjungia jau naudojamam prieigos raktui, todėl naujas prieigos raktas neišduodamas.

Užklausos pavyzdys

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

Užklausos laukai

viewsCount

integer

Reklamos skelbimo peržiūrų skaičius nuo paskelbimo

engagementsCount

integer

Sąveikų su reklamos skelbimu (paspaudimų, patiktukų ir komentarų) skaičius nuo paskelbimo

Abu laukai privalomi, kiekvienas iš jų yra sveikasis skaičius nuo 0 iki 2147483647.

Atsakymo pavyzdys

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

Šio galinio taško klaidų atsakymai

401 INVALID_TOKEN

Nėra Authorization antraštės arba prieigos raktas nežinomas, atšauktas ar yra partnerio prieigos raktas. Abiem atvejais grąžinamas kodas 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

Prieigos raktas galioja, tačiau jam nesuteiktas leidimas metrics:write. Paprašykite administratoriaus jį įjungti.

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

Užklausos turinys nėra tinkamas JSON arba du skaičiai nepateikti, yra neigiami ar nėra sveikieji skaičiai. Atsakyme nurodoma, kas neatitiko reikalavimų.

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

Viršyta vienam prieigos raktui taikoma užklausų dažnio riba. Šiame atsakyme pateikiamos antraštės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset.

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

Autentifikavimas

Antraštės formatas

Authorization: Bearer YOUR_SSP_TOKEN

Prieigos rakto formatas

64 simbolių šešioliktainė eilutė (256 bitų entropija)

Prieigos raktų valdymas

SSP prieigos raktus valdo tik sistemos administratoriai. Norėdami gauti prieigos raktą, susisiekite su administratoriumi.

Prieigos reikalavimai

Netaikomas joks prenumeratos planas

Kada galinis taškas grąžina 404

Skaidrumo ženklas

Ta pati informacija, atvaizduota rodomam reklamos skelbimui

Po vieną URL kiekvienai versijai

Kiekvienas demonstracijos valdiklis atitinka vieną iš šių parametrų, todėl galite pasirinkti demonstraciniame puslapyje ir nukopijuoti matomą adresą.

# Kampinis ženklas, tik simbolis
GET https://polads.eu/badge/{PA-ID}

# Kampinis ženklas su užrašu
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Nuolat matoma etiketės juosta
GET https://polads.eu/badge/{PA-ID}?layout=label

Ką daro kiekvienas parametras ir ką reiškia jį praleisti

hover=0 skirtas demonstracijai, o ne jūsų puslapiui

Dydžio keitimo klausytojas yra privalomas

Pasiekiamas tik paskelbtiems pranešimams

Atverkite interaktyvią demonstraciją ir nukopijuokite įterpimo kodą

Klaidų atsakymai

401 Neteisėta

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

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

400 Netinkama užklausa

Skelbimas rastas, bet jo medija nėra online. Atsakymas grąžina tikrąją medijos reikšmę, pavyzdžiui print. Trūkstamas ar nežinomas PA-ID vietoj to grąžina 404.

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

404 Nerasta

{
  "error": "Advertisement not found"
}

429 Viršytas užklausų limitas

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

Versijavimas ir atsisakymas

Kompiuterio nuskaitoma specifikacija

Visas OpenAPI 3.1 dokumentas pateikiamas adresu /api/docs. Nukreipkite Postman, Swagger UI ar kliento generatorių tiesiai į jį, užuot perrašinėję šį puslapį.

https://polads.eu/api/docs

Integruojatės kaip žiniasklaidos ar leidėjo partneris? Perskaitykite partnerių API dokumentaciją