SSP API-dokumentatsioon

Pakkumispoolse platvormi API programmaatilistele reklaamiplatvormidele

API v1

Nõutav SSP Bearer-luba

Suur läbilaskevõime

Baas-URL

https://polads.eu/api/v1

Päringusageduse piiramine

Suur läbilaskevõime programmaatiliste platvormide jaoks

GET /online-advertisement/{PAID}

10 000 päringut minutis

Päringupiirangut rakendatakse iga SSP loa kohta eraldi

PUT /online-advertisement/{PAID}/metrics

1000 päringut minutis

Arvestatakse iga SSP loa kohta märgise lõpp-punktist eraldi, nii et mõõdikute esitamine ei kuluta kunagi teie märgisepäringuid

GET

/online-advertisement/{PAID}

Hankige veebireklaamide jaoks vormindatud läbipaistvusmärgis

📊 Kompaktne märgisevorming

See lõpp-punkt tagastab kompaktse, EL-i nõuetele vastava läbipaistvusmärgise, mis sobib kuvamiseks veebireklaamide kõrval. Töötab ainult reklaamide puhul, mille meedium = "online".

SSP Bearer-luba

PA-ID

Päringu näide

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

Vastuse näide

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

Vastuse väljad

text

string

Vormindatud sildi tekst

link

string

Läbipaistvuse lehe URL

PAID

string

Poliitreklaami tunnus

Kasutusnäide

Kuvage märgis oma platvormil:

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

Kaasatusmõõdikute esitamine

PUT

/online-advertisement/{PAID}/metrics

Esitage kumulatiivne vaatamiste ja interaktsioonide arv avaldatud teate kohta, mille olete edastanud

Teie SSP-loal peab olema õigus metrics:write. Administraator lülitab selle sisse loal, mida te juba kasutate, seega uut luba ei väljastata.

Saatke jooksvad kogusummad alates teate avaldamisest, mitte kunagi muutust alates teie viimasest edastusest. Iga edastus asendab varasemad arvud, seega samade kogusummade uuesti saatmine ei muuda midagi.

Saate arvud esitada iga avaldatud teate kohta, olenemata sellest, millisele avaldajale see kuulub. Arvud kuvatakse selle avalikus läbipaistvusteates koos kuupäevaga, millal need viimati esitati.

Päringu näide

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

Päringu väljad

viewsCount

integer

Reklaami vaatamiste arv alates avaldamisest

engagementsCount

integer

Reklaamiga seotud interaktsioonide (klõpsud, meeldimised ja kommentaarid) arv alates avaldamisest

Mõlemad väljad on kohustuslikud ja kumbki peab olema täisarv vahemikus 0 kuni 2147483647.

Vastuse näide

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

Selle lõpp-punkti veavastused

401 INVALID_TOKEN

Authorization-päis puudub või luba on tundmatu, tühistatud või partneri luba. Mõlemal juhul on kood 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

Luba on kehtiv, kuid sellele ei ole antud õigust metrics:write. Paluge administraatoril see sisse lülitada.

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

404 NOT_FOUND

Ükski avaldatud teade ei vasta sellele PA-ID-le. Nagu märgise lõpp-punktis, tagastatakse 404 ka siis, kui teate avaldaja pole seda veel heaks kiitnud või selle avaldamise alguskuupäev on alles tulevikus.

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

409 METRICS_NOT_APPLICABLE

Läbipaistvusteade jääb väljapoole kohaldamisala, mille jaoks kaasatusmõõdikud on määratletud. II lisa märkus 15 hõlmab veebipõhist või natiivset läbipaistvusteadet, mille puhul kasutati suunamis- või reklaamiedastusmeetodeid ja mille näitamine on alanud. Andmeid ei salvestata.

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

400 INVALID_METRICS

Päringu keha ei ole kehtiv JSON või kaks arvu puuduvad, on negatiivsed või ei ole täisarvud. Vastuses on loetletud, mis kontrolli ei läbinud.

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

Loa kohta kehtiv päringupiirang on ületatud. Vastus sisaldab päiseid 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"
}

Autentimine

Päise vorming

Authorization: Bearer YOUR_SSP_TOKEN

Loa vorming

64-märgiline kuueteistkümnendsõne (256-bitine entroopia)

Lubade haldamine

SSP-lube haldavad ainult süsteemiadministraatorid. Loa saamiseks võtke ühendust oma administraatoriga.

Juurdepääsunõuded

Ükski tellimuspakett ei kohaldu

SSP-luba antakse liidestajale, mitte avaldajale, seega ei kuulu see ühegi avaldajakonto juurde ja kontrollitavat paketti pole. Erinevalt partneri API-st ei sõltu siin miski tellimusest. Partneri luba lükatakse selles lõpp-punktis tagasi koodiga 401 ja SSP-luba lükatakse partneri lõpp-punktides samamoodi tagasi.

Millal lõpp-punkt tagastab 404

Teadet otsitakse sama nähtavusreegli järgi nagu avalikus registris. Kui teade pole veel kinnitatud, avaldaja pole seda veel heaks kiitnud või selle avaldamise alguskuupäev on alles tulevikus, tagastatakse 404. Seega ei tõenda vastus 404, et PA-ID on vale.

Läbipaistvusmärk

Sama teave, kuvatuna näidatava reklaami juures

Ülal olev lõpp-punkt tagastab üherealise sildi TEKSTI sildi jaoks, mille kuvab teie enda platvorm. Märk tagastab valmis kuvatud interaktiivse teate, mille paigutate reklaami kõrvale iframe-raamina. Mõlemad kirjeldavad sama läbipaistvusteadet.

Üks URL iga versiooni kohta

Näidise juhtnupud vastavad neile parameetritele üks-ühele, nii et saate teha valiku näidislehel ja kopeerida sealt nähtava URL-i.

# Nurgamärk, ainult sümbol
GET https://polads.eu/badge/{PA-ID}

# Nurgamärk koos tekstiga
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Alati nähtav sildiriba
GET https://polads.eu/badge/{PA-ID}?layout=label

Mida iga parameeter teeb ja mida tähendab selle ärajätmine

layout=label valib sildiriba. Kui selle ära jätate, kuvatakse nurgamärk. variant=labelled paneb suletud märgi näitama oma teksti. Kui selle ära jätate, kuvatakse ainult sümbol. w ja h määravad ala, kuhu märk paigutub, ja valivad, kuidas see kitsas ruumis lihtsustub. Kui need ära jätate, eeldab märk, et ruumi on piisavalt, mis on standardvormingute puhul õige.

hover=0 on näidise jaoks, mitte teie lehe jaoks

See jõustab hõljumiseta paigutuse, et näidis saaks lauaarvuti brauseris näidata puuteseadme versiooni. Päris märk tuvastab seadme ise. Kui määrate selle väärtuse jäigalt, saadate vale versiooni igale külastajale, kelle seade on teistsugune.

Suuruse muutmise kuulaja on kohustuslik

Nurgamärk laaditakse mõõtmetes 32 korda 32, et katta reklaamimaterjalist võimalikult vähe, ja avanemisel küsib see seda sisaldavalt lehelt ruumi. Ilma kuulajata ei saa see üldse avaneda. Sildiriba lihtsustub sujuvamalt ja seda kärbitakse ainult kitsastel laiustel.

Saadaval ainult avaldatud teate puhul

Märk tehakse kättesaadavaks, kui teade on kinnitatud, avaldaja on selle heaks kiitnud ja avaldamise alguskuupäev on möödunud. Embargo all oleva või heaks kiitmata PA-ID puhul tagastatakse 404 teadlikult, mitte vea tõttu.

Avage interaktiivne näidis ja kopeerige manustamiskood

Veavastused

Iga viga tagastab JSON-keha koos veateatega ja iga vastus sisaldab päist X-API-Version. Sildi lõpp-punkt ei tagasta masinloetavat koodivälja, seega tuginege selle HTTP olekukoodile, mitte kehale. Mõõdikute lõpp-punkti vead sisaldavad aga koodi ja on loetletud ülal selle lõpp-punkti juures.

401 Volitamata

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

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

400 Vigane päring

Kuulutus leiti, kuid selle meedium ei ole online. Vastus tagastab meediumi tegeliku väärtuse, näiteks print. Puuduv või tundmatu PA-ID tagastab selle asemel 404.

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

404 Ei leitud

{
  "error": "Advertisement not found"
}

429 Päringute limiit ületatud

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

Versioonimine ja kasutuselt kõrvaldamine

See on API versioon v1 ja iga vastus märgib seda päises X-API-Version. Ühilduvust rikkuvad muudatused avaldatakse uuel teel, mitte selle tee muutmise kaudu. Versiooni v1 lõpp-punkti ei lülitata välja enne, kui vähemalt 90 päeva varem on saadetud päis Deprecation vastavalt standardile RFC 8594.

Masinloetav spetsifikatsioon

Täielik OpenAPI 3.1 dokument on saadaval aadressil /api/docs. Suunake Postman, Swagger UI või kliendigeneraator otse sellele, selle asemel et seda lehte ümber kirjutada.

https://polads.eu/api/docs

Kas loote liidese meedia- või avaldajapartnerina? Lugege partneri API dokumentatsiooni

SSP API-dokumentatsioon

Pakkumispoolse platvormi API programmaatilistele reklaamiplatvormidele

API v1

Nõutav SSP Bearer-luba

Suur läbilaskevõime

Baas-URL

https://polads.eu/api/v1

Päringusageduse piiramine

Suur läbilaskevõime programmaatiliste platvormide jaoks

GET /online-advertisement/{PAID}

10 000 päringut minutis

Päringupiirangut rakendatakse iga SSP loa kohta eraldi

PUT /online-advertisement/{PAID}/metrics

1000 päringut minutis

Arvestatakse iga SSP loa kohta märgise lõpp-punktist eraldi, nii et mõõdikute esitamine ei kuluta kunagi teie märgisepäringuid

GET

/online-advertisement/{PAID}

Hankige veebireklaamide jaoks vormindatud läbipaistvusmärgis

📊 Kompaktne märgisevorming

See lõpp-punkt tagastab kompaktse, EL-i nõuetele vastava läbipaistvusmärgise, mis sobib kuvamiseks veebireklaamide kõrval. Töötab ainult reklaamide puhul, mille meedium = "online".

SSP Bearer-luba

PA-ID

Päringu näide

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

Vastuse näide

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

Vastuse väljad

text

string

Vormindatud sildi tekst

link

string

Läbipaistvuse lehe URL

PAID

string

Poliitreklaami tunnus

Kasutusnäide

Kuvage märgis oma platvormil:

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

Kaasatusmõõdikute esitamine

PUT

/online-advertisement/{PAID}/metrics

Esitage kumulatiivne vaatamiste ja interaktsioonide arv avaldatud teate kohta, mille olete edastanud

Teie SSP-loal peab olema õigus metrics:write. Administraator lülitab selle sisse loal, mida te juba kasutate, seega uut luba ei väljastata.

Saate arvud esitada iga avaldatud teate kohta, olenemata sellest, millisele avaldajale see kuulub. Arvud kuvatakse selle avalikus läbipaistvusteates koos kuupäevaga, millal need viimati esitati.

Päringu näide

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

Päringu väljad

viewsCount

integer

Reklaami vaatamiste arv alates avaldamisest

engagementsCount

integer

Reklaamiga seotud interaktsioonide (klõpsud, meeldimised ja kommentaarid) arv alates avaldamisest

Mõlemad väljad on kohustuslikud ja kumbki peab olema täisarv vahemikus 0 kuni 2147483647.

Vastuse näide

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

Selle lõpp-punkti veavastused

401 INVALID_TOKEN

Authorization-päis puudub või luba on tundmatu, tühistatud või partneri luba. Mõlemal juhul on kood 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

Luba on kehtiv, kuid sellele ei ole antud õigust metrics:write. Paluge administraatoril see sisse lülitada.

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

Päringu keha ei ole kehtiv JSON või kaks arvu puuduvad, on negatiivsed või ei ole täisarvud. Vastuses on loetletud, mis kontrolli ei läbinud.

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

Loa kohta kehtiv päringupiirang on ületatud. Vastus sisaldab päiseid 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"
}

Autentimine

Päise vorming

Authorization: Bearer YOUR_SSP_TOKEN

Loa vorming

64-märgiline kuueteistkümnendsõne (256-bitine entroopia)

Lubade haldamine

SSP-lube haldavad ainult süsteemiadministraatorid. Loa saamiseks võtke ühendust oma administraatoriga.

Juurdepääsunõuded

Ükski tellimuspakett ei kohaldu

Millal lõpp-punkt tagastab 404

Läbipaistvusmärk

Sama teave, kuvatuna näidatava reklaami juures

Üks URL iga versiooni kohta

Näidise juhtnupud vastavad neile parameetritele üks-ühele, nii et saate teha valiku näidislehel ja kopeerida sealt nähtava URL-i.

# Nurgamärk, ainult sümbol
GET https://polads.eu/badge/{PA-ID}

# Nurgamärk koos tekstiga
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Alati nähtav sildiriba
GET https://polads.eu/badge/{PA-ID}?layout=label

Mida iga parameeter teeb ja mida tähendab selle ärajätmine

hover=0 on näidise jaoks, mitte teie lehe jaoks

Suuruse muutmise kuulaja on kohustuslik

Saadaval ainult avaldatud teate puhul

Avage interaktiivne näidis ja kopeerige manustamiskood

Veavastused

401 Volitamata

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

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

400 Vigane päring

Kuulutus leiti, kuid selle meedium ei ole online. Vastus tagastab meediumi tegeliku väärtuse, näiteks print. Puuduv või tundmatu PA-ID tagastab selle asemel 404.

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

404 Ei leitud

{
  "error": "Advertisement not found"
}

429 Päringute limiit ületatud

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

Versioonimine ja kasutuselt kõrvaldamine

Masinloetav spetsifikatsioon

Täielik OpenAPI 3.1 dokument on saadaval aadressil /api/docs. Suunake Postman, Swagger UI või kliendigeneraator otse sellele, selle asemel et seda lehte ümber kirjutada.

https://polads.eu/api/docs

Kas loote liidese meedia- või avaldajapartnerina? Lugege partneri API dokumentatsiooni