SSP-rajapinnan dokumentaatio

Tarjontapuolen alustan (SSP) rajapinta ohjelmallisen mainonnan alustoille

Rajapinta v1

SSP:n Bearer-tunnus vaaditaan

Suuri läpäisykyky

Perus-URL-osoite

https://polads.eu/api/v1

Nopeusrajoitus

Suuri läpäisykyky ohjelmallisen mainonnan alustoille

GET /online-advertisement/{PAID}

10 000 pyyntöä minuutissa

Rajoitus koskee kutakin SSP-tunnusta erikseen

PUT /online-advertisement/{PAID}/metrics

1 000 pyyntöä minuutissa

Lasketaan SSP-tunnuskohtaisesti ja erillään merkintäpäätepisteestä, joten lukujen ilmoittaminen ei koskaan kuluta merkintäpyyntöjäsi

GET

/online-advertisement/{PAID}

Hae muotoiltu avoimuusmerkintä verkkomainoksille

📊 Tiivis merkintämuoto

Tämä päätepiste palauttaa tiiviin, EU:n vaatimusten mukaisen avoimuusmerkinnän, joka sopii näytettäväksi verkkomainosten yhteydessä. Toimii vain mainoksille, joilla medium = "online".

SSP-Bearer-tunniste

PA-ID

Esimerkkipyyntö

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

Vastausesimerkki

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

Vastauskentät

text

string

Muotoiltu tunnisteteksti

link

string

Avoimuussivun URL-osoite

PAID

string

Poliittisen mainoksen tunnus

Käyttöesimerkki

Näytä merkintä alustallasi:

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

Ilmoita vuorovaikutusluvut

PUT

/online-advertisement/{PAID}/metrics

Ilmoita toimittamasi julkaistun ilmoituksen kertyneet näyttökerrat ja vuorovaikutukset

SSP-tunnisteesi tarvitsee käyttöoikeuden metrics:write. Järjestelmänvalvoja ottaa sen käyttöön jo käyttämällesi tunnisteelle, joten uutta tunnistetta ei myönnetä.

Lähetä kertyneet kokonaismäärät ilmoituksen julkaisusta lähtien, ei koskaan muutosta edellisen lähetyksesi jälkeen. Jokainen lähetys korvaa sitä edeltäneet luvut, joten samojen kokonaismäärien lähettäminen uudelleen ei muuta mitään.

Voit ilmoittaa luvut mistä tahansa julkaistusta ilmoituksesta riippumatta siitä, mille julkaisijalle se kuuluu. Luvut näkyvät sen julkisessa avoimuusilmoituksessa yhdessä sen päivämäärän kanssa, jolloin ne viimeksi ilmoitettiin.

Esimerkkipyyntö

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

Pyyntökentät

viewsCount

integer

Mainoksen näyttökertojen määrä julkaisusta lähtien

engagementsCount

integer

Mainokseen kohdistuneiden vuorovaikutusten määrä (klikkaukset, tykkäykset ja kommentit) julkaisusta lähtien

Molemmat kentät ovat pakollisia, ja kummankin arvon on oltava kokonaisluku, joka on vähintään 0 ja enintään 2147483647.

Vastausesimerkki

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

Tämän päätepisteen virhevastaukset

401 INVALID_TOKEN

Authorization-otsake puuttuu tai tunnus on tuntematon, mitätöity tai kumppanitunnus. Kummassakin tapauksessa palautetaan koodi 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

Tunnus on kelvollinen, mutta sille ei ole annettu käyttöoikeutta metrics:write. Pyydä järjestelmänvalvojaa ottamaan se käyttöön.

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

404 NOT_FOUND

Mikään julkaistu ilmoitus ei vastaa tätä PA-ID:tä. Kuten merkintäpäätepisteessä, myös ilmoitus, jota sen julkaisija ei ole vielä hyväksynyt tai jonka julkaisun alkamispäivä on vasta tulevaisuudessa, palauttaa koodin 404.

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

409 METRICS_NOT_APPLICABLE

Ilmoitus ei kuulu niiden ilmoitusten piiriin, joille vuorovaikutusluvut on määritelty. Liitteen II huomautus 15 koskee verkossa julkaistua tai natiivia ilmoitusta, jossa on käytetty kohdentamistekniikoita tai mainosten näyttämistekniikoita ja jonka näyttäminen on alkanut. Mitään ei tallenneta.

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

400 INVALID_METRICS

Pyynnön runko ei ole kelvollista JSON-muotoa, tai kaksi määrää puuttuvat, ovat negatiivisia tai eivät ole kokonaislukuja. Vastauksessa luetellaan, mikä ei kelvannut.

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

Tunnuskohtainen pyyntöraja ylittyi. Vastaus sisältää otsakkeet X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset.

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

Todennus

Otsakkeen muoto

Authorization: Bearer YOUR_SSP_TOKEN

Tunnisteen muoto

64-merkkinen heksadesimaalimerkkijono (256-bittinen entropia)

Tunnisteiden hallinta

SSP-tunnisteita hallinnoivat vain järjestelmänvalvojat. Saat tunnisteen ottamalla yhteyttä järjestelmänvalvojaasi.

Käyttöoikeusvaatimukset

Tilausta ei edellytetä

SSP-tunniste myönnetään integroijalle eikä julkaisijalle, joten siihen ei liity julkaisijatiliä eikä tilausta tarvitse tarkistaa. Toisin kuin kumppanirajapinnassa, mikään tässä ei riipu tilauksesta. Kumppanitunniste hylätään tässä päätepisteessä koodilla 401, ja SSP-tunniste hylätään samalla tavalla kumppanipäätepisteissä.

Milloin päätepiste palauttaa koodin 404

Ilmoitus haetaan samalla näkyvyyssäännöllä kuin julkisessa rekisterissä. Jos ilmoitusta ei ole vielä vahvistettu, julkaisija ei ole vielä hyväksynyt sitä tai sen julkaisun alkamispäivä on vasta tulevaisuudessa, päätepiste palauttaa koodin 404. Koodi 404 ei siis todista, että PA-ID olisi väärä.

Avoimuusmerkki

Samat tiedot esitettynä näytettävän mainoksen yhteydessä

Yllä oleva päätepiste palauttaa yksirivisen merkinnän TEKSTIN, kun oma alustasi piirtää merkinnän itse. Merkki palauttaa valmiiksi piirretyn, vuorovaikutteisen ilmoituksen, jonka sijoitat mainoksen viereen iframe-kehyksenä. Molemmat kuvaavat samaa avoimuusilmoitusta.

Yksi URL-osoite versiota kohden

Esittelyn säätimet vastaavat näitä parametreja yksi yhteen, joten voit tehdä valinnan esittelysivulla ja kopioida näkyviin tulevan URL-osoitteen.

# Kulmamerkki, pelkkä symboli
GET https://polads.eu/badge/{PA-ID}

# Kulmamerkki, jossa näkyy teksti
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Jatkuvasti näkyvä merkintäpalkki
GET https://polads.eu/badge/{PA-ID}?layout=label

Mitä kukin parametri tekee ja mitä sen pois jättäminen tarkoittaa

layout=label valitsee merkintäpalkin. Ilman sitä näytetään kulmamerkki. variant=labelled näyttää tekstin suljetussa merkissä. Ilman sitä näytetään pelkkä symboli. w ja h ilmoittavat tilan, jossa merkki sijaitsee, ja määrittävät, miten se pelkistyy ahtaassa tilassa. Jos jätät ne pois, merkki olettaa, että tilaa on riittävästi, mikä pitää paikkansa vakiomuodoissa.

hover=0 on tarkoitettu esittelyyn, ei sivullesi

Se pakottaa kosketuslaitteiden asettelun, jotta esittely voi näyttää kosketusversion työpöytäselaimessa. Oikea merkki tunnistaa laitteen itse. Jos kirjoitat arvon kiinteästi koodiin, lähetät väärän version jokaiselle kävijälle, jonka laite ei vastaa sitä.

Koonmuutoksen kuuntelija on pakollinen

Kulmamerkki latautuu kokoon 32 × 32, jotta se peittää mainoksesta mahdollisimman vähän, ja pyytää isäntäsivulta lisää tilaa avautuessaan. Ilman kuuntelijaa se ei avaudu lainkaan. Merkintäpalkki pelkistyy lievemmin ja rajautuu vain kapeilla leveyksillä.

Saatavilla vain julkaistulle ilmoitukselle

Merkki toimitetaan, kun ilmoitus on vahvistettu, julkaisija on hyväksynyt sen ja sen julkaisun alkamispäivä on mennyt. Julkaisuaikaa odottava tai hyväksymätön PA-ID palauttaa koodin 404 tarkoituksellisesti, ei virheen vuoksi.

Avaa vuorovaikutteinen esittely ja kopioi upotuskoodi

Virhevastaukset

Jokainen virhe palauttaa JSON-rungon, jossa on virheilmoitus, ja jokainen vastaus sisältää X-API-Version-otsakkeen. Merkintäpäätepiste ei palauta koneluettavaa koodikenttää, joten tunnista virhe sen HTTP-tilakoodin eikä rungon perusteella. Lukujen ilmoittamisen päätepisteen virheissä on sen sijaan koodi, ja ne on lueteltu yllä kyseisen päätepisteen kohdalla.

401 Luvaton

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

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

400 Virheellinen pyyntö

Ilmoitus löytyi, mutta sen media ei ole online. Vastaus palauttaa todellisen media-arvon, esimerkiksi print. Puuttuva tai tuntematon PA-ID palauttaa sen sijaan 404.

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

404 Ei löytynyt

{
  "error": "Advertisement not found"
}

429 Pyyntöraja ylitetty

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

Versiointi ja käytöstä poisto

Tämä on rajapinnan versio v1, ja jokainen vastaus ilmoittaa sen X-API-Version-otsakkeessa. Yhteensopivuuden rikkovat muutokset julkaistaan uudessa polussa, eikä tätä polkua muuteta. v1-päätepistettä ei poisteta käytöstä ilman Deprecation-otsaketta vähintään 90 päivää etukäteen RFC 8594:n mukaisesti.

Koneluettava määrittely

Koko OpenAPI 3.1 -dokumentti on saatavilla osoitteessa /api/docs. Ohjaa Postman, Swagger UI tai asiakasgeneraattori suoraan siihen sen sijaan, että kopioisit tämän sivun tiedot käsin.

https://polads.eu/api/docs

Teetkö integraation media- tai julkaisijakumppanina? Lue kumppanirajapinnan dokumentaatio

SSP-rajapinnan dokumentaatio

Tarjontapuolen alustan (SSP) rajapinta ohjelmallisen mainonnan alustoille

Rajapinta v1

SSP:n Bearer-tunnus vaaditaan

Suuri läpäisykyky

Perus-URL-osoite

https://polads.eu/api/v1

Nopeusrajoitus

Suuri läpäisykyky ohjelmallisen mainonnan alustoille

GET /online-advertisement/{PAID}

10 000 pyyntöä minuutissa

Rajoitus koskee kutakin SSP-tunnusta erikseen

PUT /online-advertisement/{PAID}/metrics

1 000 pyyntöä minuutissa

Lasketaan SSP-tunnuskohtaisesti ja erillään merkintäpäätepisteestä, joten lukujen ilmoittaminen ei koskaan kuluta merkintäpyyntöjäsi

GET

/online-advertisement/{PAID}

Hae muotoiltu avoimuusmerkintä verkkomainoksille

📊 Tiivis merkintämuoto

Tämä päätepiste palauttaa tiiviin, EU:n vaatimusten mukaisen avoimuusmerkinnän, joka sopii näytettäväksi verkkomainosten yhteydessä. Toimii vain mainoksille, joilla medium = "online".

SSP-Bearer-tunniste

PA-ID

Esimerkkipyyntö

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

Vastausesimerkki

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

Vastauskentät

text

string

Muotoiltu tunnisteteksti

link

string

Avoimuussivun URL-osoite

PAID

string

Poliittisen mainoksen tunnus

Käyttöesimerkki

Näytä merkintä alustallasi:

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

Ilmoita vuorovaikutusluvut

PUT

/online-advertisement/{PAID}/metrics

Ilmoita toimittamasi julkaistun ilmoituksen kertyneet näyttökerrat ja vuorovaikutukset

SSP-tunnisteesi tarvitsee käyttöoikeuden metrics:write. Järjestelmänvalvoja ottaa sen käyttöön jo käyttämällesi tunnisteelle, joten uutta tunnistetta ei myönnetä.

Esimerkkipyyntö

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

Pyyntökentät

viewsCount

integer

Mainoksen näyttökertojen määrä julkaisusta lähtien

engagementsCount

integer

Mainokseen kohdistuneiden vuorovaikutusten määrä (klikkaukset, tykkäykset ja kommentit) julkaisusta lähtien

Molemmat kentät ovat pakollisia, ja kummankin arvon on oltava kokonaisluku, joka on vähintään 0 ja enintään 2147483647.

Vastausesimerkki

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

Tämän päätepisteen virhevastaukset

401 INVALID_TOKEN

Authorization-otsake puuttuu tai tunnus on tuntematon, mitätöity tai kumppanitunnus. Kummassakin tapauksessa palautetaan koodi 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

Tunnus on kelvollinen, mutta sille ei ole annettu käyttöoikeutta metrics:write. Pyydä järjestelmänvalvojaa ottamaan se käyttöön.

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

Pyynnön runko ei ole kelvollista JSON-muotoa, tai kaksi määrää puuttuvat, ovat negatiivisia tai eivät ole kokonaislukuja. Vastauksessa luetellaan, mikä ei kelvannut.

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

Tunnuskohtainen pyyntöraja ylittyi. Vastaus sisältää otsakkeet X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset.

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

Todennus

Otsakkeen muoto

Authorization: Bearer YOUR_SSP_TOKEN

Tunnisteen muoto

64-merkkinen heksadesimaalimerkkijono (256-bittinen entropia)

Tunnisteiden hallinta

SSP-tunnisteita hallinnoivat vain järjestelmänvalvojat. Saat tunnisteen ottamalla yhteyttä järjestelmänvalvojaasi.

Käyttöoikeusvaatimukset

Tilausta ei edellytetä

Milloin päätepiste palauttaa koodin 404

Avoimuusmerkki

Samat tiedot esitettynä näytettävän mainoksen yhteydessä

Yksi URL-osoite versiota kohden

Esittelyn säätimet vastaavat näitä parametreja yksi yhteen, joten voit tehdä valinnan esittelysivulla ja kopioida näkyviin tulevan URL-osoitteen.

# Kulmamerkki, pelkkä symboli
GET https://polads.eu/badge/{PA-ID}

# Kulmamerkki, jossa näkyy teksti
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Jatkuvasti näkyvä merkintäpalkki
GET https://polads.eu/badge/{PA-ID}?layout=label

Mitä kukin parametri tekee ja mitä sen pois jättäminen tarkoittaa

hover=0 on tarkoitettu esittelyyn, ei sivullesi

Koonmuutoksen kuuntelija on pakollinen

Saatavilla vain julkaistulle ilmoitukselle

Avaa vuorovaikutteinen esittely ja kopioi upotuskoodi

Virhevastaukset

401 Luvaton

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

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

400 Virheellinen pyyntö

Ilmoitus löytyi, mutta sen media ei ole online. Vastaus palauttaa todellisen media-arvon, esimerkiksi print. Puuttuva tai tuntematon PA-ID palauttaa sen sijaan 404.

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

404 Ei löytynyt

{
  "error": "Advertisement not found"
}

429 Pyyntöraja ylitetty

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

Versiointi ja käytöstä poisto

Koneluettava määrittely

Koko OpenAPI 3.1 -dokumentti on saatavilla osoitteessa /api/docs. Ohjaa Postman, Swagger UI tai asiakasgeneraattori suoraan siihen sen sijaan, että kopioisit tämän sivun tiedot käsin.

https://polads.eu/api/docs

Teetkö integraation media- tai julkaisijakumppanina? Lue kumppanirajapinnan dokumentaatio