Partnerių API dokumentacija

Politinės reklamos skelbimų duomenų API žiniasklaidos ir leidėjų partneriams

API v1

Reikalingas partnerio nešiklio prieigos raktas

Atitinka BDAR

Pagrindinis URL

https://polads.eu/api/v1

Visiems galiniams taškams reikalingas autentifikavimas partnerio nešiklio prieigos raktu

Užklausų dažnio ribojimas

Visiems partnerių galiniams taškams taikomas tas pats užklausų dažnio limitas vienam nešiklio prieigos raktui

GET /advertisement-full/{PAID}

1,000 užklausų per minutę

GET /advertisement/{PAID}

1,000 užklausų per minutę

Užklausų dažnio limitas taikomas kiekvienam partnerio prieigos raktui, bendrai visiems galiniams taškams

Prieigos reikalavimai

Ką partnerio prieigos raktas turi turėti, kad bet kuris galinis taškas atsakytų

Pro planas, tikrinamas per kiekvieną užklausą

Partnerių API yra Pro plano dalis, tiek skaitymo, tiek rašymo užklausoms. Atskiro API priedo pirkti nereikia. Planas tikrinamas per kiekvieną užklausą, o ne įrašomas kuriant prieigos raktą, todėl pasibaigus prenumeratai prieiga nutraukiama jau kito kreipimosi metu, grąžinant 403 PRO_PLAN_REQUIRED, o atnaujinus prenumeratą ji lygiai taip pat iš karto atkuriama.

Prieigos sritys

Kiekvienas partnerio prieigos raktas gali skaityti duomenis. Norint teikti įsitraukimo rodiklius, papildomai reikia prieigos srities metrics:write. Prieigos sritys pasirenkamos kuriant prieigos raktą ir vėliau jų keisti negalima: norėdami jas pakeisti, atšaukite prieigos raktą ir sukurkite naują.

Tik partnerių prieigos raktai

Šie galiniai taškai atmeta SSP prieigos raktą ir grąžina 401, o SSP galinis taškas lygiai taip pat atmeta partnerio prieigos raktą. Šie du lygiai yra atskiri prisijungimo duomenys, o ne du vienų prisijungimo duomenų leidimų lygiai.

Kada galinis taškas grąžina 404

Kodas 404 dar neįrodo, kad PA-ID yra klaidingas

GET /advertisement/{PAID} skelbimą nustato taikydamas tą pačią matomumo taisyklę kaip ir viešasis registras. Skelbimas, kuris dar nepatvirtintas, kuriam jo leidėjas dar nepritarė arba kurio paskelbimo pradžios data dar nesuėjo, čia grąžina 404 lygiai taip pat, kaip ir registre. Tas pats taikoma SSP galiniam taškui.

Viso įrašo galinis taškas sąmoningai veikia kitaip

GET /advertisement-full/{PAID} apima tik jūsų pačių skelbimus, todėl atsako ir dėl skelbimo, kurio pradžios data dar neatėjo. Jūs esate leidėjas, kuris turi peržiūrėti šį skelbimą prieš jam pasirodant, todėl slėpti jį nuo jūsų būtų beprasmiška.

GET

/advertisement-full/{PAID}

Gaukite visus skelbimo duomenis, įskaitant VISUS BDAR požiūriu jautrius laukus (reikalingas nešiklio prieigos raktas)

Taikoma tik jūsų pačių skelbimams. Kito leidėjo PA-ID, savarankiškai paskelbtas skelbimas be leidėjo ir neegzistuojantis identifikatorius grąžina tą patį kodą 404, o iš atsakymo jų atskirti neįmanoma.

⚠️ Įspėjimas: BDAR požiūriu jautrūs duomenys

Šis galinis taškas pateikia VISUS laukus, įskaitant el. pašto adresus, telefono numerius ir išsamius adresus. Naudokite šį galinį tašką tik tuo atveju, jei turite teisėtą verslo poreikį ir esate sudarę tinkamas duomenų tvarkymo sutartis.

Bearer prieigos raktas

PA-ID

Užklausos pavyzdys

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

Atsakyme pateikiama (NEFILTRUOTA)

Reklamuotojo laukai:

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

Kampanijos laukai:

name, totalValue, medium, isOngoing, startDate, endDate

Reklamuotojai ir duomenų valdytojai:

Visi laukai, įskaitant el. paštą, telefonus ir pilnus adresus

Sąveikos rodiklių teikimas

PUT

/advertisement/{PAID}/metrics

Siųskite savo skelbimų peržiūrų ir sąveikų skaičius po jų paskelbimo.

Šiam galiniam taškui reikia rakto su aprėptimi „Skaitymas ir rašymas“. Partnerių API įtraukta į Pro planą.

Rodiklius galite teikti tik skelbimams, paskelbtiems per savo paskyrą.

Skelbimas priklauso kitam leidėjui. Niekas neįrašoma.

Užklausos pavyzdys

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

Galimi laukai

API grąžinami duomenų laukai su jų tipais

Pagrindinė informacija

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Atitiktis ir finansavimas

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Atrankusis adresavimas

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Teisinė informacija ir metaduomenys

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

nurodo neprivalomą lauką, kuris gali būti be reikšmės arba tuščias

Kodo pavyzdžiai

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

Klaidų atsakymai

Kiekviena klaida grąžina JSON turinį su klaidos pranešimu, o kiekviename atsakyme yra antraštė X-API-Version. Kompiuterio nuskaitomas kodas pateikiamas kartu su atmetimais dėl negaliojančio prieigos rakto ir dėl plano, taip pat su paties metrics galinio taško tikrinimo klaidomis. Kai trūksta Authorization antraštės, kai skaitymo galinis taškas grąžina 404 ar 429 ir kai įvyksta bet kokia vidinė serverio klaida, pateikiamas tik pranešimas.

401 INVALID_TOKEN

Joks aktyvus prieigos raktas neatitinka Bearer prisijungimo duomenų arba prieigos raktas atšauktas. Kai Authorization antraštės nėra arba ji netaisyklinga, taip pat grąžinamas atsakymas 401, tačiau šiuo kodu jį pažymi tik metrics galinis taškas. SSP prieigos raktas, panaudotas partnerio galiniame taške, gauna tokį patį atsakymą.

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

Prieigos raktas galioja, tačiau jo leidėjas neturi Pro plano. Planas tikrinamas prieš aprėptį, todėl tik skaitymo prieigos raktas, priklausantis leidėjui be Pro plano, grąžina klaidą dėl plano, o ne dėl aprėpties.

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

Prieigos raktas galioja ir turi Pro planą, tačiau jam trūksta aprėpties metrics:write, reikalingos rodikliams teikti.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Skelbimas priklauso kitam leidėjui. Niekas neįrašoma.

PUT /advertisement/{PAID}/metrics

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

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ų.

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

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

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Nė vienas skelbimas neatitinka šio PA-ID arba jis jums dar nematomas. Prieš manydami, kad identifikatorius neteisingas, perskaitykite aukščiau esantį skyrių.

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

Viršyta vienam prieigos raktui taikoma užklausų riba. Šiame atsakyme pateikiamos antraštės X-RateLimit-Limit, X-RateLimit-Remaining ir 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"
}

Versijų valdymas ir palaikymo nutraukimas

Tai API versija v1, ir kiekvienas atsakymas tai nurodo antraštėje X-API-Version. Nesuderinami pakeitimai pateikiami nauju keliu, o šis kelias nekeičiamas. Versijos v1 galinis taškas nebus išjungtas, jei bent 90 dienų iki tol nebus pateikta Deprecation antraštė, kaip numatyta RFC 8594.

Kompiuterio nuskaitoma specifikacija

Visas OpenAPI 3.1 dokumentas pateikiamas adresu /api/docs. Užuot perrašę šį puslapį, nukreipkite Postman, Swagger UI ar kliento kodo generatorių tiesiai į jį.

https://polads.eu/api/docs

Integruojatės kaip pasiūlos pusės platforma? Skaitykite SSP API dokumentaciją

Partnerių API dokumentacija

Politinės reklamos skelbimų duomenų API žiniasklaidos ir leidėjų partneriams

API v1

Reikalingas partnerio nešiklio prieigos raktas

Atitinka BDAR

Pagrindinis URL

https://polads.eu/api/v1

Visiems galiniams taškams reikalingas autentifikavimas partnerio nešiklio prieigos raktu

Užklausų dažnio ribojimas

Visiems partnerių galiniams taškams taikomas tas pats užklausų dažnio limitas vienam nešiklio prieigos raktui

GET /advertisement-full/{PAID}

1,000 užklausų per minutę

GET /advertisement/{PAID}

1,000 užklausų per minutę

Užklausų dažnio limitas taikomas kiekvienam partnerio prieigos raktui, bendrai visiems galiniams taškams

Prieigos reikalavimai

Ką partnerio prieigos raktas turi turėti, kad bet kuris galinis taškas atsakytų

Pro planas, tikrinamas per kiekvieną užklausą

Prieigos sritys

Tik partnerių prieigos raktai

Kada galinis taškas grąžina 404

Kodas 404 dar neįrodo, kad PA-ID yra klaidingas

Viso įrašo galinis taškas sąmoningai veikia kitaip

GET

/advertisement-full/{PAID}

Gaukite visus skelbimo duomenis, įskaitant VISUS BDAR požiūriu jautrius laukus (reikalingas nešiklio prieigos raktas)

⚠️ Įspėjimas: BDAR požiūriu jautrūs duomenys

Bearer prieigos raktas

PA-ID

Užklausos pavyzdys

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

Atsakyme pateikiama (NEFILTRUOTA)

Reklamuotojo laukai:

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

Kampanijos laukai:

name, totalValue, medium, isOngoing, startDate, endDate

Reklamuotojai ir duomenų valdytojai:

Visi laukai, įskaitant el. paštą, telefonus ir pilnus adresus

Sąveikos rodiklių teikimas

PUT

/advertisement/{PAID}/metrics

Siųskite savo skelbimų peržiūrų ir sąveikų skaičius po jų paskelbimo.

Šiam galiniam taškui reikia rakto su aprėptimi „Skaitymas ir rašymas“. Partnerių API įtraukta į Pro planą.

Rodiklius galite teikti tik skelbimams, paskelbtiems per savo paskyrą.

Skelbimas priklauso kitam leidėjui. Niekas neįrašoma.

Užklausos pavyzdys

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

Galimi laukai

API grąžinami duomenų laukai su jų tipais

Pagrindinė informacija

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Atitiktis ir finansavimas

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Atrankusis adresavimas

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Teisinė informacija ir metaduomenys

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

nurodo neprivalomą lauką, kuris gali būti be reikšmės arba tuščias

Kodo pavyzdžiai

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

Klaidų atsakymai

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

Prieigos raktas galioja ir turi Pro planą, tačiau jam trūksta aprėpties metrics:write, reikalingos rodikliams teikti.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Skelbimas priklauso kitam leidėjui. Niekas neįrašoma.

PUT /advertisement/{PAID}/metrics

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

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ų.

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

Nė vienas skelbimas neatitinka šio PA-ID arba jis jums dar nematomas. Prieš manydami, kad identifikatorius neteisingas, perskaitykite aukščiau esantį skyrių.

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

Viršyta vienam prieigos raktui taikoma užklausų riba. Šiame atsakyme pateikiamos antraštės X-RateLimit-Limit, X-RateLimit-Remaining ir 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"
}

Versijų valdymas ir palaikymo nutraukimas

Kompiuterio nuskaitoma specifikacija

Visas OpenAPI 3.1 dokumentas pateikiamas adresu /api/docs. Užuot perrašę šį puslapį, nukreipkite Postman, Swagger UI ar kliento kodo generatorių tiesiai į jį.

https://polads.eu/api/docs

Integruojatės kaip pasiūlos pusės platforma? Skaitykite SSP API dokumentaciją