Partneru API dokumentācija

Politisko reklāmu datu API partneriem: plašsaziņas līdzekļiem un izdevējiem

API v1

Nepieciešama partnera Bearer pilnvara

Atbilst GDPR

Pamata URL

https://polads.eu/api/v1

Visiem galapunktiem nepieciešama autentifikācija ar partnera Bearer pilnvaru

Pieprasījumu skaita ierobežojums

Visiem partneru galapunktiem ir kopīgs pieprasījumu skaita ierobežojums katrai Bearer pilnvarai

GET /advertisement-full/{PAID}

1000 pieprasījumu minūtē

GET /advertisement/{PAID}

1000 pieprasījumu minūtē

Pieprasījumu skaita ierobežojums tiek piemērots katrai partnera pilnvarai visiem galapunktiem kopā

Piekļuves prasības

Kādām prasībām jāatbilst partnera pilnvarai, lai jebkurš galapunkts atbildētu

Pro plāns, pārbaudīts katrā pieprasījumā

Partneru API ir daļa no Pro plāna gan lasīšanai, gan rakstīšanai. Atsevišķs API papildinājums nav jāpērk. Plānu pārbauda katrā atsevišķā pieprasījumā, nevis reģistrē pilnvaras izveides brīdī, tāpēc beidzies abonements pārtrauc piekļuvi jau nākamajā izsaukumā ar 403 PRO_PLAN_REQUIRED, un pēc abonementa atjaunošanas piekļuve tikpat ātri atjaunojas.

Piekļuves tvērumi

Ikviena partnera pilnvara var lasīt. Iesaistes rādītāju ziņošanai papildus nepieciešams tvērums metrics:write. Tvērumus izvēlas pilnvaras izveides brīdī, un vēlāk tos rediģēt nevar: lai tos mainītu, atsauciet pilnvaru un izveidojiet jaunu.

Tikai partneru pilnvaras

Šie galapunkti noraida SSP pilnvaru ar kodu 401, un SSP galapunkts tāpat noraida partnera pilnvaru. Abi līmeņi ir atsevišķi akreditācijas dati, nevis divi atļauju līmeņi vieniem un tiem pašiem akreditācijas datiem.

Kad galapunkts atgriež 404

Kods 404 nepierāda, ka PA-ID ir nepareizs

GET /advertisement/{PAID} atrod paziņojumu pēc tā paša redzamības noteikuma, ko izmanto publiskais reģistrs. Paziņojums, kas vēl nav apstiprināts, ko tā izdevējs vēl nav akceptējis vai kura publicēšanas sākuma datums vēl ir nākotnē, šeit atgriež 404 tieši tāpat kā reģistrā. Tas pats attiecas uz SSP galapunktu.

Pilnā ieraksta galapunkts apzināti darbojas citādi

GET /advertisement-full/{PAID} attiecas tikai uz jūsu pašu paziņojumiem, tāpēc tas sniedz atbildi arī par paziņojumu, kura sākuma datums vēl nav pienācis. Jūs esat izdevējs, kuram šis paziņojums jāpārbauda pirms tā publicēšanas, tāpēc tā slēpšana no jums būtu bezjēdzīga.

GET

/advertisement-full/{PAID}

Iegūstiet pilnīgus reklāmas datus, tostarp VISUS VDAR sensitīvos laukus (nepieciešama nesēja pilnvara)

Attiecas tikai uz jūsu pašu paziņojumiem. Cita izdevēja PA-ID, paša publicēts paziņojums bez izdevēja un neesošs identifikators visos gadījumos atgriež vienu un to pašu kodu 404, un atbilde tos neatšķir.

⚠️ Brīdinājums par VDAR sensitīviem datiem

Šis galapunkts atgriež VISUS laukus, tostarp e-pasta adreses, tālruņa numurus un pilnas adreses. Izmantojiet šo galapunktu tikai tad, ja jums ir leģitīma uzņēmējdarbības vajadzība un ir noslēgti atbilstoši datu apstrādes līgumi.

Bearer pilnvara

PA-ID

Pieprasījuma piemērs

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

Atbildē iekļautie dati (NEFILTRĒTI)

Reklāmdevēja lauki:

companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country

Kampaņas lauki:

name, totalValue, medium, isOngoing, startDate, endDate

Reklāmdevēji un pārziņi:

Visi lauki, tostarp e-pasta adreses, tālruņi un pilnas adreses

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

PUT

/advertisement/{PAID}/metrics

Nosūtiet savu sludinājumu skatījumu un iesaistes skaitu pēc to publicēšanas.

Šim galapunktam nepieciešama atslēga ar tvērumu „Lasīšana un rakstīšana”. Partneru API ir iekļauts Pro plānā.

Rādītājus varat ziņot tikai par sludinājumiem, kas publicēti no jūsu konta.

Sludinājums pieder citam izdevējam. Nekas netiek ierakstīts.

Pieprasījuma piemērs

curl -X PUT "https://polads.eu/api/v1/advertisement/ABC12/metrics" \
  -H "Authorization: Bearer YOUR_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"viewsCount": 15000, "engagementsCount": 320}'

Pieejamie lauki

API atgrieztie datu lauki ar to tipiem

Pamatinformācija

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Atbilstība un finansējums

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Mērķorientēšana

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Juridiskā informācija un metadati

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

norāda neobligātu lauku, kuram var nebūt vērtības vai kas var būt tukšs

Koda piemēri

// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();

Kļūdu atbildes

Katra kļūda atgriež JSON pamattekstu ar kļūdas ziņojumu, un katrā atbildē ir galvene X-API-Version. Mašīnlasāms kods ir pievienots atteikumiem nederīgas pilnvaras un plāna dēļ, kā arī paša metrics galapunkta validācijas kļūdām. Ja trūkst Authorization galvenes, lasīšanas galapunkta atbildēs 404 vai 429 un jebkuras iekšējas servera kļūdas gadījumā atbildē ir tikai ziņojums.

401 INVALID_TOKEN

Neviena aktīva pilnvara neatbilst Bearer akreditācijas datiem, vai arī pilnvara ir atsaukta. Ja Authorization galvenes trūkst vai tā ir nepareizi veidota, atbilde arī ir 401, taču ar šo kodu to apzīmē tikai metrics galapunkts. SSP pilnvarai partnera galapunktā atbilde ir tāda pati.

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Invalid or revoked partner API token. This endpoint only accepts partner tokens, not SSP tokens.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid or revoked partner API token.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

403 PRO_PLAN_REQUIRED

Pilnvara ir derīga, bet tās izdevējam nav Pro plāna. Plāns tiek pārbaudīts pirms tvēruma, tāpēc izdevējam bez Pro plāna piederoša tikai lasīšanas pilnvara saņem kļūdu par plānu, nevis par tvērumu.

GET /advertisement/{PAID}GET /advertisement-full/{PAID}PUT /advertisement/{PAID}/metrics

{
  "error": "The Pro plan is required to use the partner API.",
  "code": "PRO_PLAN_REQUIRED"
}

403 INSUFFICIENT_SCOPE

Pilnvara ir derīga un atbilst Pro plānam, taču tai nav rādītāju ziņošanai nepieciešamā tvēruma metrics:write.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Sludinājums pieder citam izdevējam. Nekas netiek ierakstīts.

PUT /advertisement/{PAID}/metrics

{
  "error": "This advertisement belongs to a different publisher.",
  "code": "FORBIDDEN"
}

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.

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid engagement metrics",
  "code": "INVALID_METRICS",
  "issues": [
    {
      "path": "viewsCount",
      "message": "Too small: expected number to be >=0"
    }
  ]
}

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid request body",
  "code": "INVALID_METRICS"
}

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.

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Neviens paziņojums neatbilst šim PA-ID, vai arī tas jums vēl nav redzams. Pirms pieņemat, ka identifikators ir nepareizs, izlasiet iepriekšējo sadaļu.

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}

{
  "error": "Advertisement not found"
}

GET /advertisement-full/{PAID}

{
  "error": "Advertisement not found or not yet confirmed"
}

429 RATE_LIMITED

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

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Rate limit exceeded",
  "limit": 1000,
  "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 pārtraucošas izmaiņas tiek publicētas ar jaunu ceļu, nevis mainot šo. Versijas v1 galapunkts netiks atslēgts, ja vismaz 90 dienas iepriekš nebūs nosūtīta 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 Postman, Swagger UI vai klienta ģeneratorā, nevis pārrakstiet šīs lapas saturu.

https://polads.eu/api/docs

Integrējaties kā piedāvājuma puses platforma? Izlasiet SSP API dokumentāciju

Partneru API dokumentācija

Politisko reklāmu datu API partneriem: plašsaziņas līdzekļiem un izdevējiem

API v1

Nepieciešama partnera Bearer pilnvara

Atbilst GDPR

Pamata URL

https://polads.eu/api/v1

Visiem galapunktiem nepieciešama autentifikācija ar partnera Bearer pilnvaru

Pieprasījumu skaita ierobežojums

Visiem partneru galapunktiem ir kopīgs pieprasījumu skaita ierobežojums katrai Bearer pilnvarai

GET /advertisement-full/{PAID}

1000 pieprasījumu minūtē

GET /advertisement/{PAID}

1000 pieprasījumu minūtē

Pieprasījumu skaita ierobežojums tiek piemērots katrai partnera pilnvarai visiem galapunktiem kopā

Piekļuves prasības

Kādām prasībām jāatbilst partnera pilnvarai, lai jebkurš galapunkts atbildētu

Pro plāns, pārbaudīts katrā pieprasījumā

Piekļuves tvērumi

Tikai partneru pilnvaras

Kad galapunkts atgriež 404

Kods 404 nepierāda, ka PA-ID ir nepareizs

Pilnā ieraksta galapunkts apzināti darbojas citādi

GET

/advertisement-full/{PAID}

Iegūstiet pilnīgus reklāmas datus, tostarp VISUS VDAR sensitīvos laukus (nepieciešama nesēja pilnvara)

⚠️ Brīdinājums par VDAR sensitīviem datiem

Bearer pilnvara

PA-ID

Pieprasījuma piemērs

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

Atbildē iekļautie dati (NEFILTRĒTI)

Reklāmdevēja lauki:

companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country

Kampaņas lauki:

name, totalValue, medium, isOngoing, startDate, endDate

Reklāmdevēji un pārziņi:

Visi lauki, tostarp e-pasta adreses, tālruņi un pilnas adreses

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

PUT

/advertisement/{PAID}/metrics

Nosūtiet savu sludinājumu skatījumu un iesaistes skaitu pēc to publicēšanas.

Šim galapunktam nepieciešama atslēga ar tvērumu „Lasīšana un rakstīšana”. Partneru API ir iekļauts Pro plānā.

Rādītājus varat ziņot tikai par sludinājumiem, kas publicēti no jūsu konta.

Sludinājums pieder citam izdevējam. Nekas netiek ierakstīts.

Pieprasījuma piemērs

curl -X PUT "https://polads.eu/api/v1/advertisement/ABC12/metrics" \
  -H "Authorization: Bearer YOUR_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"viewsCount": 15000, "engagementsCount": 320}'

Pieejamie lauki

API atgrieztie datu lauki ar to tipiem

Pamatinformācija

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Atbilstība un finansējums

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Mērķorientēšana

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Juridiskā informācija un metadati

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

norāda neobligātu lauku, kuram var nebūt vērtības vai kas var būt tukšs

Koda piemēri

// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();

Kļūdu atbildes

401 INVALID_TOKEN

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Invalid or revoked partner API token. This endpoint only accepts partner tokens, not SSP tokens.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid or revoked partner API token.",
  "code": "INVALID_TOKEN"
}

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

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

403 PRO_PLAN_REQUIRED

GET /advertisement/{PAID}GET /advertisement-full/{PAID}PUT /advertisement/{PAID}/metrics

{
  "error": "The Pro plan is required to use the partner API.",
  "code": "PRO_PLAN_REQUIRED"
}

403 INSUFFICIENT_SCOPE

Pilnvara ir derīga un atbilst Pro plānam, taču tai nav rādītāju ziņošanai nepieciešamā tvēruma metrics:write.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Sludinājums pieder citam izdevējam. Nekas netiek ierakstīts.

PUT /advertisement/{PAID}/metrics

{
  "error": "This advertisement belongs to a different publisher.",
  "code": "FORBIDDEN"
}

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.

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid engagement metrics",
  "code": "INVALID_METRICS",
  "issues": [
    {
      "path": "viewsCount",
      "message": "Too small: expected number to be >=0"
    }
  ]
}

PUT /advertisement/{PAID}/metrics

{
  "error": "Invalid request body",
  "code": "INVALID_METRICS"
}

409 METRICS_NOT_APPLICABLE

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Neviens paziņojums neatbilst šim PA-ID, vai arī tas jums vēl nav redzams. Pirms pieņemat, ka identifikators ir nepareizs, izlasiet iepriekšējo sadaļu.

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}

{
  "error": "Advertisement not found"
}

GET /advertisement-full/{PAID}

{
  "error": "Advertisement not found or not yet confirmed"
}

429 RATE_LIMITED

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

PUT /advertisement/{PAID}/metrics

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

GET /advertisement/{PAID}GET /advertisement-full/{PAID}

{
  "error": "Rate limit exceeded",
  "limit": 1000,
  "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 Postman, Swagger UI vai klienta ģeneratorā, nevis pārrakstiet šīs lapas saturu.

https://polads.eu/api/docs

Integrējaties kā piedāvājuma puses platforma? Izlasiet SSP API dokumentāciju