Partneri API dokumentatsioon

Poliitreklaamide andmete API meedia- ja avaldajapartneritele

API v1

Nõutav partneri Bearer-luba

GDPR-i nõuetele vastav

Baas-URL

https://polads.eu/api/v1

Kõik lõpp-punktid nõuavad autentimist partneri Bearer-loaga

Päringute piiramine

Kõik partneri lõpp-punktid kasutavad iga Bearer-loa kohta ühist päringupiirangut

GET /advertisement-full/{PAID}

1000 päringut minutis

GET /advertisement/{PAID}

1000 päringut minutis

Päringupiirangut rakendatakse partneri loa kohta kõigi lõpp-punktide peale kokku

Juurdepääsunõuded

Mis peab partneri loal olema, enne kui ükski lõpp-punkt vastab

Pro pakett, kontrollitakse uuesti igal päringul

Partneri API kuulub Pro paketti nii lugemise kui ka kirjutamise puhul. Eraldi API lisateenust ei ole vaja osta. Paketti kontrollitakse iga päringu juures, mitte ei salvestata loa loomisel, seega peatab aegunud tellimus juurdepääsu kohe järgmisel päringul vastusega 403 PRO_PLAN_REQUIRED ja pikendamine taastab selle sama kiiresti.

Õiguste ulatused

Iga partneri luba võimaldab lugeda. Kaasamismõõdikute esitamiseks on lisaks vaja õiguste ulatust metrics:write. Õiguste ulatused valitakse loa loomisel ja neid ei saa hiljem muuta: nende muutmiseks tühistage luba ja looge uus.

Ainult partneri load

Need lõpp-punktid lükkavad SSP loa tagasi koodiga 401 ja SSP lõpp-punkt lükkab partneri loa tagasi samamoodi. Need kaks taset on eraldi volitused, mitte ühe volituse kaks õigustaset.

Millal lõpp-punkt tagastab koodi 404

Kood 404 ei tõenda, et PA-ID oleks vale

GET /advertisement/{PAID} leiab kuulutuse sama nähtavusreegli järgi nagu avalik register. Kuulutus, mis ei ole veel kinnitatud, mida selle avaldaja ei ole veel heaks kiitnud või mille avaldamise alguskuupäev on alles tulevikus, tagastab siin koodi 404 täpselt samamoodi nagu registris. Sama kehtib SSP lõpp-punkti kohta.

Täieliku kirje lõpp-punkt on meelega teistsugune

GET /advertisement-full/{PAID} on piiratud teie enda kuulutustega, seega vastab see ka kuulutuse kohta, mille alguskuupäev pole veel saabunud. Teie olete see avaldaja, kes peab selle kuulutuse enne avaldamist üle vaatama, nii et selle teie eest varjamine muudaks kogu mõtte olematuks.

GET

/advertisement-full/{PAID}

Hankige täielikud reklaamiandmed, sealhulgas KÕIK IKÜMi kohaselt tundlikud väljad (vajalik on Bearer-luba)

Piiratud teie enda kuulutustega. Teise avaldaja PA-ID, ilma avaldajata ise avaldatud kuulutus ja olematu identifikaator tagastavad kõik sama koodi 404 ning vastus neid ei erista.

⚠️ Hoiatus: IKÜMi kohaselt tundlikud andmed

See lõpp-punkt tagastab KÕIK väljad, sealhulgas e-posti aadressid, telefoninumbrid ja täielikud aadressid. Kasutage seda lõpp-punkti ainult siis, kui teil on õigustatud ärivajadus ja nõuetekohased andmetöötluslepingud on sõlmitud.

Bearer-luba

PA-ID

Päringu näide

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

Vastus sisaldab (FILTREERIMATA)

Reklaamija väljad:

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

Kampaania väljad:

name, totalValue, medium, isOngoing, startDate, endDate

Reklaamijad ja vastutavad töötlejad:

Kõik väljad, sealhulgas e-posti aadressid, telefoninumbrid ja täisaadressid

Kaasatusmõõdikute esitamine

PUT

/advertisement/{PAID}/metrics

Saatke oma kuulutuste kohta pärast avaldamist kogutud vaatamiste ja kaasatuse arvud.

See lõpp-punkt nõuab võtit, millel on ulatus Lugemine ja kirjutamine. Partneri API sisaldub Pro paketis.

Saate mõõdikuid esitada ainult oma konto kaudu avaldatud kuulutuste kohta.

Kuulutus kuulub teisele avaldajale. Midagi ei kirjutata.

Päringu näide

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

Saadaolevad väljad

API tagastatavad andmeväljad koos nende tüüpidega

Põhiteave

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Vastavus ja rahastamine

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Suunamine

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Õiguslik teave ja metaandmed

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

tähistab valikulist välja, mis võib olla null või tühi

Koodinäited

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

Veavastused

Iga viga tagastab JSON-keha koos veateatega ja iga vastus sisaldab päist X-API-Version. Masinloetav kood lisatakse kehtetu loa ja paketi tõttu tehtud keeldumistele ning metrics-lõpp-punkti enda valideerimisvigadele. Puuduva Authorization-päise, lugemise lõpp-punkti 404 või 429 ja mis tahes serveri sisevea korral tagastatakse ainult teade.

401 INVALID_TOKEN

Ükski aktiivne luba ei vasta Bearer-mandaadile või on luba tühistatud. Ka puuduva või vigase Authorization-päise korral on vastus 401, kuid selle koodiga märgistab seda ainult metrics-lõpp-punkt. SSP luba partneri lõpp-punktis saab sama vastuse.

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

Luba on kehtiv, kuid selle avaldaja ei kasuta Pro-paketti. Seda kontrollitakse enne õiguste ulatust, seega annab Pro-paketita avaldajale kuuluv ainult lugemisõigusega luba vea paketi, mitte õiguste ulatuse kohta.

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

Luba on kehtiv ja kuulub Pro-paketti, kuid sellel puudub mõõdikute esitamiseks vajalik õiguste ulatus metrics:write.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Kuulutus kuulub teisele avaldajale. Midagi ei kirjutata.

PUT /advertisement/{PAID}/metrics

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

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.

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

Läbipaistvusteade jääb väljapoole kohaldamisala, mille jaoks kaasamismõõ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.

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Ükski läbipaistvusteade ei vasta sellele PA-ID-le või ei ole see teile veel nähtav. Enne kui eeldate, et identifikaator on vale, lugege ülalolevat jaotist.

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

Loa kohta kehtiv päringupiirang on ületatud. Vastus sisaldab päiseid X-RateLimit-Limit, X-RateLimit-Remaining ja 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"
}

Versioonimine ja kasutuselt kõrvaldamine

See on API versioon v1 ja iga vastus näitab seda päises X-API-Version. Ühilduvust rikkuvad muudatused avaldatakse uue tee all, praegust teed ei muudeta. Versiooni v1 lõpp-punkti ei lülitata välja, ilma et vähemalt 90 päeva varem oleks saadetud päis Deprecation, kooskõlas standardiga 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 liidestate süsteemi pakkumispoolse platvormina? Lugege SSP API dokumentatsiooni

Partneri API dokumentatsioon

Poliitreklaamide andmete API meedia- ja avaldajapartneritele

API v1

Nõutav partneri Bearer-luba

GDPR-i nõuetele vastav

Baas-URL

https://polads.eu/api/v1

Kõik lõpp-punktid nõuavad autentimist partneri Bearer-loaga

Päringute piiramine

Kõik partneri lõpp-punktid kasutavad iga Bearer-loa kohta ühist päringupiirangut

GET /advertisement-full/{PAID}

1000 päringut minutis

GET /advertisement/{PAID}

1000 päringut minutis

Päringupiirangut rakendatakse partneri loa kohta kõigi lõpp-punktide peale kokku

Juurdepääsunõuded

Mis peab partneri loal olema, enne kui ükski lõpp-punkt vastab

Pro pakett, kontrollitakse uuesti igal päringul

Õiguste ulatused

Ainult partneri load

Need lõpp-punktid lükkavad SSP loa tagasi koodiga 401 ja SSP lõpp-punkt lükkab partneri loa tagasi samamoodi. Need kaks taset on eraldi volitused, mitte ühe volituse kaks õigustaset.

Millal lõpp-punkt tagastab koodi 404

Kood 404 ei tõenda, et PA-ID oleks vale

Täieliku kirje lõpp-punkt on meelega teistsugune

GET

/advertisement-full/{PAID}

Hankige täielikud reklaamiandmed, sealhulgas KÕIK IKÜMi kohaselt tundlikud väljad (vajalik on Bearer-luba)

Piiratud teie enda kuulutustega. Teise avaldaja PA-ID, ilma avaldajata ise avaldatud kuulutus ja olematu identifikaator tagastavad kõik sama koodi 404 ning vastus neid ei erista.

⚠️ Hoiatus: IKÜMi kohaselt tundlikud andmed

Bearer-luba

PA-ID

Päringu näide

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

Vastus sisaldab (FILTREERIMATA)

Reklaamija väljad:

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

Kampaania väljad:

name, totalValue, medium, isOngoing, startDate, endDate

Reklaamijad ja vastutavad töötlejad:

Kõik väljad, sealhulgas e-posti aadressid, telefoninumbrid ja täisaadressid

Kaasatusmõõdikute esitamine

PUT

/advertisement/{PAID}/metrics

Saatke oma kuulutuste kohta pärast avaldamist kogutud vaatamiste ja kaasatuse arvud.

See lõpp-punkt nõuab võtit, millel on ulatus Lugemine ja kirjutamine. Partneri API sisaldub Pro paketis.

Saate mõõdikuid esitada ainult oma konto kaudu avaldatud kuulutuste kohta.

Kuulutus kuulub teisele avaldajale. Midagi ei kirjutata.

Päringu näide

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

Saadaolevad väljad

API tagastatavad andmeväljad koos nende tüüpidega

Põhiteave

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Vastavus ja rahastamine

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Suunamine

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Õiguslik teave ja metaandmed

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

tähistab valikulist välja, mis võib olla null või tühi

Koodinäited

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

Veavastused

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

Luba on kehtiv ja kuulub Pro-paketti, kuid sellel puudub mõõdikute esitamiseks vajalik õiguste ulatus metrics:write.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Kuulutus kuulub teisele avaldajale. Midagi ei kirjutata.

PUT /advertisement/{PAID}/metrics

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

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.

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

Ükski läbipaistvusteade ei vasta sellele PA-ID-le või ei ole see teile veel nähtav. Enne kui eeldate, et identifikaator on vale, lugege ülalolevat jaotist.

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

Loa kohta kehtiv päringupiirang on ületatud. Vastus sisaldab päiseid X-RateLimit-Limit, X-RateLimit-Remaining ja 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"
}

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 liidestate süsteemi pakkumispoolse platvormina? Lugege SSP API dokumentatsiooni