SSP API dokumentācija

Piedāvājuma puses platformas API programmatiskās reklāmas platformām

API v1

Nepieciešama SSP uzrādītāja pilnvara

Augsta caurlaidspēja

Pamata URL

https://polads.eu/api/v1

Pieprasījumu biežuma ierobežojums

Augsta caurlaidspēja programmatiskās reklāmas platformām

GET /online-advertisement/{PAID}

10 000 pieprasījumu minūtē

Pieprasījumu biežuma ierobežojums tiek piemērots katrai SSP pilnvarai

PUT /online-advertisement/{PAID}/metrics

1000 pieprasījumu minūtē

Pieprasījumus skaita katrai SSP pilnvarai atsevišķi un neatkarīgi no marķējuma galapunkta, tāpēc rādītāju ziņošana nekad neizlieto jūsu marķējuma pieprasījumus

GET

/online-advertisement/{PAID}

Iegūstiet formatētu pārredzamības marķējumu tiešsaistes reklāmām

📊 Kompakts marķējuma formāts

Šis galapunkts atgriež kompaktu, ES prasībām atbilstošu pārredzamības marķējumu, kas piemērots rādīšanai blakus tiešsaistes reklāmām. Darbojas tikai reklāmām, kurām medijs = "online".

SSP Bearer pilnvara

PA-ID

Pieprasījuma piemērs

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

Atbildes piemērs

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

Atbildes lauki

text

string

Formatēts marķējuma teksts

link

string

Pārredzamības lapas URL

PAID

string

Politiskās reklāmas identifikators

Lietošanas piemērs

Parādiet marķējumu savā platformā:

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

Iesaistes rādītāju ziņošana

PUT

/online-advertisement/{PAID}/metrics

Ziņojiet kumulatīvo skatījumu un mijiedarbību skaitu publicētam paziņojumam, kuru esat piegādājis

Jūsu SSP pilnvarai nepieciešama atļauja metrics:write. Administrators to ieslēdz pilnvarai, kuru jau izmantojat, tāpēc jauna pilnvara netiek izsniegta.

Sūtiet kopsummas, kas uzkrātas kopš paziņojuma publicēšanas, nevis izmaiņas kopš pēdējās sūtīšanas. Katra sūtīšana aizstāj iepriekšējos skaitļus, tāpēc to pašu kopsummu atkārtota nosūtīšana neko nemaina.

Varat ziņot par jebkuru publicētu paziņojumu neatkarīgi no tā, kuram izdevējam tas pieder. Skaitļi tiek parādīti tā publiskajā pārredzamības paziņojumā kopā ar datumu, kad par tiem pēdējoreiz ziņots.

Pieprasījuma piemērs

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

Pieprasījuma lauki

viewsCount

integer

Reklāmas skatījumu skaits kopš publicēšanas

engagementsCount

integer

Mijiedarbību ar reklāmu (klikšķu, atzīmju "Patīk" un komentāru) skaits kopš publicēšanas

Abi lauki ir obligāti, katrs ir vesels skaitlis no 0 līdz 2147483647.

Atbildes piemērs

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

Šī galapunkta kļūdu atbildes

401 INVALID_TOKEN

Trūkst Authorization galvenes, vai arī pilnvara ir nezināma, atsaukta vai ir partnera pilnvara. Abos gadījumos tiek atgriezts kods 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

Pilnvara ir derīga, taču tai nav piešķirta atļauja metrics:write. Lūdziet savam administratoram to ieslēgt.

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

404 NOT_FOUND

Šim PA-ID neatbilst neviens publicēts paziņojums. Tāpat kā marķējuma galapunktā, 404 atgriež arī paziņojums, ko izdevējs vēl nav apstiprinājis vai kura publicēšanas sākuma datums vēl ir nākotnē.

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

409 METRICS_NOT_APPLICABLE

Paziņojums neietilpst jomā, kurai ir noteikti iesaistes rādītāji. II pielikuma 15. piezīme attiecas uz tiešsaistes vai natīvās reklāmas paziņojumu, kurā izmantotas mērķorientēšanas metodes vai reklāmas piegādes metodes un kura izplatīšana jau ir sākusies. Nekas netiek ierakstīts.

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

400 INVALID_METRICS

Pieprasījuma pamatteksts nav derīgs JSON, vai arī abi skaitļi nav norādīti, ir negatīvi vai nav veseli skaitļi. Atbildē ir norādīts, kas neatbilst prasībām.

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

Ir pārsniegts vienai pilnvarai noteiktais ierobežojums. Atbildē ir galvenes X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset.

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

Autentifikācija

Galvenes formāts

Authorization: Bearer YOUR_SSP_TOKEN

Pilnvaras formāts

64 rakstzīmju heksadecimāla virkne (256 bitu entropija)

Pilnvaru pārvaldība

SSP pilnvaras pārvalda tikai sistēmas administratori. Lai iegūtu pilnvaru, sazinieties ar savu administratoru.

Piekļuves prasības

Abonēšanas plāns netiek piemērots

SSP pilnvaru izsniedz integratoram, nevis izdevējam, tāpēc tā nav piesaistīta izdevēja kontam un nav plāna, ko pārbaudīt. Atšķirībā no partneru API šeit nekas nav atkarīgs no abonementa. Partnera pilnvara šajā galapunktā tiek noraidīta ar kodu 401, un SSP pilnvara tāpat tiek noraidīta partneru galapunktos.

Kad galapunkts atgriež 404

Paziņojuma pieejamību nosaka tas pats redzamības noteikums, kas attiecas uz publisko reģistru. Paziņojums, kas vēl nav apstiprināts, ko izdevējs vēl nav akceptējis vai kura publicēšanas sākuma datums vēl ir nākotnē, atgriež 404. Tādēļ kods 404 nepierāda, ka PA-ID ir nepareizs.

Pārredzamības zīme

Tā pati informācija, attēlota rādāmai reklāmai

Iepriekš minētais galapunkts atgriež vienas rindas marķējuma TEKSTU marķējumam, ko attēlo jūsu pašu platforma. Zīme atgriež gatavu, interaktīvu paziņojumu, ko iegultā rāmī novietojat blakus reklāmai. Abi apraksta vienu un to pašu pārredzamības paziņojumu.

Viens URL katrai versijai

Demonstrācijas vadīklas atbilst šiem parametriem viens pret vienu, tāpēc varat izvēlēties demonstrācijas lapā un nokopēt redzamo adresi.

# Stūra zīme, tikai simbols
GET https://polads.eu/badge/{PA-ID}

# Stūra zīme ar uzrakstu
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Pastāvīgi redzama marķējuma josla
GET https://polads.eu/badge/{PA-ID}?layout=label

Ko dara katrs parametrs un ko nozīmē, ja to izlaiž

layout=label izvēlas joslu. Ja to izlaižat, tiek rādīta stūra zīme. variant=labelled liek aizvērtajai zīmei rādīt uzrakstu. Ja to izlaižat, tiek rādīts tikai simbols. w un h norāda vietu, kurā zīme atrodas, un nosaka, kā tā vienkāršojas šaurā vietā. Ja tos izlaižat, zīme pieņem, ka vietas pietiek, un tas ir pareizi standarta formātiem.

hover=0 ir domāts demonstrācijai, nevis jūsu lapai

Tas piespiedu kārtā ieslēdz izkārtojumu bez kursora, lai demonstrācija datora pārlūkā varētu parādīt skārienekrāna versiju. Īstā zīme ierīci pārbauda pati. Ja šo vērtību nostiprināsiet kodā, katrs apmeklētājs, kura ierīce neatbilst šim pieņēmumam, saņems nepareizo versiju.

Izmēra maiņas klausītājs ir obligāts

Stūra zīme ielādējas 32 reiz 32 izmērā, lai pēc iespējas mazāk aizsegtu reklāmas materiālu, un, atveroties, lūdz mitinātājlapai vietu. Bez klausītāja tā vispār nevar atvērties. Marķējuma josla šaurā vietā vienkāršojas saudzīgāk un tiek apgriezta tikai nelielos platumos.

Pieejama tikai publicētam paziņojumam

Zīme tiek piegādāta, kad paziņojums ir apstiprināts, izdevējs to ir parakstījis un ir pienācis tā publicēšanas sākuma datums. PA-ID, uz kuru attiecas embargo vai kas nav parakstīts, apzināti atgriež 404, un tā nav kļūda.

Atveriet interaktīvo demonstrāciju un kopējiet iegulšanas kodu

Kļūdu atbildes

Katra kļūda atgriež JSON pamattekstu ar kļūdas ziņojumu, un katra atbilde satur galveni X-API-Version. Marķējuma galapunkts neatgriež mašīnlasāma koda lauku, tāpēc vadieties pēc tā HTTP statusa, nevis pēc pamatteksta. Rādītāju galapunkta kļūdām tomēr ir kods, un tās ir uzskaitītas augstāk pie paša galapunkta.

401 Nesankcionēts

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

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

400 Nederīgs pieprasījums

Sludinājums tika atrasts, bet tā medijs nav online. Atbilde atgriež faktisko medija vērtību, piemēram, print. Trūkstošs vai nezināms PA-ID atgriež 404.

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

404 Nav atrasts

{
  "error": "Advertisement not found"
}

429 Pārsniegts pieprasījumu limits

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

Versiju pārvaldība un izņemšana no lietošanas

Šī ir API versija v1, un katra atbilde to norāda galvenē X-API-Version. Saderību lauzošas izmaiņas tiek ieviestas jaunā ceļā, nevis mainot šo. Versijas v1 galapunkts netiks izslēgts, ja vismaz 90 dienas iepriekš nebūs sniegta galvene Deprecation saskaņā ar RFC 8594.

Mašīnlasāma specifikācija

Pilns OpenAPI 3.1 dokuments ir pieejams adresē /api/docs. Norādiet šo adresi tieši rīkam Postman, Swagger UI vai klienta ģeneratoram, nevis pārrakstiet šo lapu.

https://polads.eu/api/docs

Vai integrējaties kā mediju vai izdevēju partneris? Izlasiet partneru API dokumentāciju

SSP API dokumentācija

Piedāvājuma puses platformas API programmatiskās reklāmas platformām

API v1

Nepieciešama SSP uzrādītāja pilnvara

Augsta caurlaidspēja

Pamata URL

https://polads.eu/api/v1

Pieprasījumu biežuma ierobežojums

Augsta caurlaidspēja programmatiskās reklāmas platformām

GET /online-advertisement/{PAID}

10 000 pieprasījumu minūtē

Pieprasījumu biežuma ierobežojums tiek piemērots katrai SSP pilnvarai

PUT /online-advertisement/{PAID}/metrics

1000 pieprasījumu minūtē

Pieprasījumus skaita katrai SSP pilnvarai atsevišķi un neatkarīgi no marķējuma galapunkta, tāpēc rādītāju ziņošana nekad neizlieto jūsu marķējuma pieprasījumus

GET

/online-advertisement/{PAID}

Iegūstiet formatētu pārredzamības marķējumu tiešsaistes reklāmām

📊 Kompakts marķējuma formāts

SSP Bearer pilnvara

PA-ID

Pieprasījuma piemērs

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

Atbildes piemērs

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

Atbildes lauki

text

string

Formatēts marķējuma teksts

link

string

Pārredzamības lapas URL

PAID

string

Politiskās reklāmas identifikators

Lietošanas piemērs

Parādiet marķējumu savā platformā:

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

Iesaistes rādītāju ziņošana

PUT

/online-advertisement/{PAID}/metrics

Ziņojiet kumulatīvo skatījumu un mijiedarbību skaitu publicētam paziņojumam, kuru esat piegādājis

Jūsu SSP pilnvarai nepieciešama atļauja metrics:write. Administrators to ieslēdz pilnvarai, kuru jau izmantojat, tāpēc jauna pilnvara netiek izsniegta.

Pieprasījuma piemērs

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

Pieprasījuma lauki

viewsCount

integer

Reklāmas skatījumu skaits kopš publicēšanas

engagementsCount

integer

Mijiedarbību ar reklāmu (klikšķu, atzīmju "Patīk" un komentāru) skaits kopš publicēšanas

Abi lauki ir obligāti, katrs ir vesels skaitlis no 0 līdz 2147483647.

Atbildes piemērs

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

Šī galapunkta kļūdu atbildes

401 INVALID_TOKEN

Trūkst Authorization galvenes, vai arī pilnvara ir nezināma, atsaukta vai ir partnera pilnvara. Abos gadījumos tiek atgriezts kods 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

Pilnvara ir derīga, taču tai nav piešķirta atļauja metrics:write. Lūdziet savam administratoram to ieslēgt.

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

Pieprasījuma pamatteksts nav derīgs JSON, vai arī abi skaitļi nav norādīti, ir negatīvi vai nav veseli skaitļi. Atbildē ir norādīts, kas neatbilst prasībām.

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

Ir pārsniegts vienai pilnvarai noteiktais ierobežojums. Atbildē ir galvenes X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset.

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

Autentifikācija

Galvenes formāts

Authorization: Bearer YOUR_SSP_TOKEN

Pilnvaras formāts

64 rakstzīmju heksadecimāla virkne (256 bitu entropija)

Pilnvaru pārvaldība

SSP pilnvaras pārvalda tikai sistēmas administratori. Lai iegūtu pilnvaru, sazinieties ar savu administratoru.

Piekļuves prasības

Abonēšanas plāns netiek piemērots

Kad galapunkts atgriež 404

Pārredzamības zīme

Tā pati informācija, attēlota rādāmai reklāmai

Viens URL katrai versijai

Demonstrācijas vadīklas atbilst šiem parametriem viens pret vienu, tāpēc varat izvēlēties demonstrācijas lapā un nokopēt redzamo adresi.

# Stūra zīme, tikai simbols
GET https://polads.eu/badge/{PA-ID}

# Stūra zīme ar uzrakstu
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Pastāvīgi redzama marķējuma josla
GET https://polads.eu/badge/{PA-ID}?layout=label

Ko dara katrs parametrs un ko nozīmē, ja to izlaiž

hover=0 ir domāts demonstrācijai, nevis jūsu lapai

Izmēra maiņas klausītājs ir obligāts

Pieejama tikai publicētam paziņojumam

Atveriet interaktīvo demonstrāciju un kopējiet iegulšanas kodu

Kļūdu atbildes

401 Nesankcionēts

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

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

400 Nederīgs pieprasījums

Sludinājums tika atrasts, bet tā medijs nav online. Atbilde atgriež faktisko medija vērtību, piemēram, print. Trūkstošs vai nezināms PA-ID atgriež 404.

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

404 Nav atrasts

{
  "error": "Advertisement not found"
}

429 Pārsniegts pieprasījumu limits

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

Versiju pārvaldība un izņemšana no lietošanas

Mašīnlasāma specifikācija

Pilns OpenAPI 3.1 dokuments ir pieejams adresē /api/docs. Norādiet šo adresi tieši rīkam Postman, Swagger UI vai klienta ģeneratoram, nevis pārrakstiet šo lapu.

https://polads.eu/api/docs

Vai integrējaties kā mediju vai izdevēju partneris? Izlasiet partneru API dokumentāciju