Dokumentacija partnerskega API-ja

API s podatki o političnih oglasih za partnerske medije in izdajatelje

API v1

Potreben je partnerski nosilni žeton

Skladno z GDPR

Osnovni URL

https://polads.eu/api/v1

Vse končne točke zahtevajo preverjanje pristnosti s partnerskim nosilnim žetonom

Omejitev števila zahtev

Vse partnerske končne točke imajo skupno omejitev števila zahtev na nosilni žeton

GET /advertisement-full/{PAID}

1,000 zahtev na minuto

GET /advertisement/{PAID}

1,000 zahtev na minuto

Omejitev se uveljavlja za posamezni partnerski žeton v vseh končnih točkah

Zahteve za dostop

Kaj mora vsebovati partnerski žeton, preden se katera koli končna točka odzove

Paket Pro, preverjen ob vsaki zahtevi

Partnerski API je del paketa Pro, tako za branje kot za pisanje. Ločenega dodatka za API ni treba kupiti. Paket se preveri ob vsaki posamezni zahtevi in se ne zabeleži le ob ustvarjanju žetona, zato potekla naročnina ustavi dostop že ob naslednjem klicu z odgovorom 403 PRO_PLAN_REQUIRED, podaljšanje pa ga prav tako takoj obnovi.

Obsegi dostopa

Vsak partnerski žeton omogoča branje. Za poročanje o meritvah angažiranosti je dodatno potreben obseg metrics:write. Obsegi se izberejo ob ustvarjanju žetona in jih pozneje ni mogoče urediti: če jih želite spremeniti, žeton prekličite in ustvarite novega.

Samo partnerski žetoni

Te končne točke zavrnejo žeton SSP s kodo 401, končna točka SSP pa na enak način zavrne partnerski žeton. Ravni sta ločeni poverilnici in ne dve ravni dovoljenj iste poverilnice.

Kdaj končna točka vrne 404

Koda 404 ni dokaz, da je PA-ID napačen

GET /advertisement/{PAID} obvestilo poišče po istem pravilu vidnosti kot javni register. Obvestilo, ki še ni potrjeno, ki ga njegov izdajatelj še ni odobril ali katerega datum začetka objave je še v prihodnosti, tu vrne 404 natanko tako kot v registru. Enako velja za končno točko SSP.

Končna točka s celotnim zapisom namenoma deluje drugače

Končna točka GET /advertisement-full/{PAID} je omejena na vaša lastna obvestila, zato odgovori tudi za obvestilo, ki še ni doseglo datuma začetka. Vi ste izdajatelj, ki mora to obvestilo pregledati, preden je objavljeno, zato bi bilo nesmiselno, da bi vam ga prikrili.

GET

/advertisement-full/{PAID}

Pridobite celotne podatke o oglasu, vključno z VSEMI polji, občutljivimi z vidika GDPR (zahteva žeton Bearer)

Omejeno na vaša lastna obvestila. PA-ID drugega izdajatelja, samostojno objavljeno obvestilo brez izdajatelja in identifikator, ki ne obstaja, vsi vrnejo isto kodo 404, odziv pa jih med seboj ne razlikuje.

⚠️ Opozorilo: podatki, občutljivi z vidika GDPR

Ta končna točka vrne VSA polja, vključno z e-poštnimi naslovi, telefonskimi številkami in celotnimi naslovi. To končno točko uporabljajte le, če imate upravičeno poslovno potrebo in sklenjene ustrezne pogodbe o obdelavi podatkov.

Žeton Bearer

PA-ID

Primer zahteve

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

Odziv vključuje (NEFILTRIRANO)

Polja oglaševalca:

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

Polja kampanje:

name, totalValue, medium, isOngoing, startDate, endDate

Oglaševalci in upravljavci:

Vsa polja, vključno z e-poštnimi naslovi, telefoni in polnimi naslovi

Poročanje o meritvah angažiranosti

PUT

/advertisement/{PAID}/metrics

Po objavi pošljite število ogledov in interakcij za svoja obvestila o preglednosti.

Ta končna točka zahteva ključ z obsegom Branje in pisanje. Partnerski API je vključen v paket Pro.

Meritve lahko sporočate le za obvestila, objavljena prek vašega lastnega računa.

Obvestilo pripada drugemu izdajatelju. Nič se ne zapiše.

Primer zahteve

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

Razpoložljiva polja

Podatkovna polja, ki jih vrne API, in njihovi podatkovni tipi

Osnovne informacije

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Skladnost in financiranje

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Ciljanje

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Pravni podatki in metapodatki

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

označuje neobvezno polje, ki je lahko brez vrednosti ali prazno

Primeri kode

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

Odzivi ob napakah

Vsaka napaka vrne telo JSON s sporočilom o napaki, vsak odziv pa vsebuje glavo X-API-Version. Strojno berljiva koda spremlja zavrnitve zaradi neveljavnega žetona in zaradi paketa ter napake preverjanja, ki jih vrne sama končna točka metrics. Manjkajoča glava Authorization, napaka 404 ali 429 s končne točke za branje in vsaka notranja napaka strežnika vsebujejo samo sporočilo.

401 INVALID_TOKEN

Poverilnici Bearer ne ustreza noben aktiven žeton ali pa je bil žeton preklican. Manjkajoča ali napačno oblikovana glava Authorization prav tako vrne 401, vendar jo s to kodo označi le končna točka metrics. Žeton SSP na partnerski končni točki prejme enak odziv.

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

Žeton je veljaven, vendar njegov izdajatelj nima paketa Pro. To se preveri pred ravnjo dostopa, zato žeton samo za branje, ki pripada izdajatelju brez paketa Pro, vrne napako zaradi paketa in ne zaradi ravni dostopa.

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

Žeton je veljaven in ima paket Pro, vendar nima ravni dostopa metrics:write, ki je potrebna za poročanje o meritvah.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Obvestilo pripada drugemu izdajatelju. Nič se ne zapiše.

PUT /advertisement/{PAID}/metrics

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

400 INVALID_METRICS

Telo zahteve ni veljaven JSON ali pa obe števili manjkata, sta negativni ali nista celi števili. Odziv navede, kaj ni uspelo.

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

Obvestilo ne spada na področje, za katero so opredeljene meritve angažiranosti. Opomba 15 Priloge II zajema spletno ali izvorno obvestilo, pri katerem so bile uporabljene tehnike ciljanja ali tehnike prikazovanja oglasov in pri katerem se je prikazovanje oglasa že začelo. Nič se ne zapiše.

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Temu PA-ID ne ustreza nobeno obvestilo ali pa vam še ni vidno. Preden sklepate, da je identifikator napačen, preberite zgornji razdelek.

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

Omejitev števila zahtev na žeton je bila presežena. Odziv vsebuje glave X-RateLimit-Limit, X-RateLimit-Remaining in 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"
}

Različice in opuščanje

To je različica API v1 in vsak odziv to navaja v glavi X-API-Version. Nezdružljive spremembe so objavljene na novi poti, ta pot pa ostane nespremenjena. Končna točka v1 ne bo izklopljena, ne da bi bila vsaj 90 dni prej poslana glava Deprecation v skladu z RFC 8594.

Strojno berljiva specifikacija

Celoten dokument OpenAPI 3.1 je na voljo na /api/docs. Namesto prepisovanja te strani usmerite Postman, Swagger UI ali generator odjemalcev neposredno nanj.

https://polads.eu/api/docs

Se povezujete kot platforma na strani ponudbe (SSP)? Preberite dokumentacijo za API SSP

Dokumentacija partnerskega API-ja

API s podatki o političnih oglasih za partnerske medije in izdajatelje

API v1

Potreben je partnerski nosilni žeton

Skladno z GDPR

Osnovni URL

https://polads.eu/api/v1

Vse končne točke zahtevajo preverjanje pristnosti s partnerskim nosilnim žetonom

Omejitev števila zahtev

Vse partnerske končne točke imajo skupno omejitev števila zahtev na nosilni žeton

GET /advertisement-full/{PAID}

1,000 zahtev na minuto

GET /advertisement/{PAID}

1,000 zahtev na minuto

Omejitev se uveljavlja za posamezni partnerski žeton v vseh končnih točkah

Zahteve za dostop

Kaj mora vsebovati partnerski žeton, preden se katera koli končna točka odzove

Paket Pro, preverjen ob vsaki zahtevi

Obsegi dostopa

Samo partnerski žetoni

Te končne točke zavrnejo žeton SSP s kodo 401, končna točka SSP pa na enak način zavrne partnerski žeton. Ravni sta ločeni poverilnici in ne dve ravni dovoljenj iste poverilnice.

Kdaj končna točka vrne 404

Koda 404 ni dokaz, da je PA-ID napačen

Končna točka s celotnim zapisom namenoma deluje drugače

GET

/advertisement-full/{PAID}

Pridobite celotne podatke o oglasu, vključno z VSEMI polji, občutljivimi z vidika GDPR (zahteva žeton Bearer)

⚠️ Opozorilo: podatki, občutljivi z vidika GDPR

Žeton Bearer

PA-ID

Primer zahteve

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

Odziv vključuje (NEFILTRIRANO)

Polja oglaševalca:

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

Polja kampanje:

name, totalValue, medium, isOngoing, startDate, endDate

Oglaševalci in upravljavci:

Vsa polja, vključno z e-poštnimi naslovi, telefoni in polnimi naslovi

Poročanje o meritvah angažiranosti

PUT

/advertisement/{PAID}/metrics

Po objavi pošljite število ogledov in interakcij za svoja obvestila o preglednosti.

Ta končna točka zahteva ključ z obsegom Branje in pisanje. Partnerski API je vključen v paket Pro.

Meritve lahko sporočate le za obvestila, objavljena prek vašega lastnega računa.

Obvestilo pripada drugemu izdajatelju. Nič se ne zapiše.

Primer zahteve

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

Razpoložljiva polja

Podatkovna polja, ki jih vrne API, in njihovi podatkovni tipi

Osnovne informacije

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Skladnost in financiranje

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Ciljanje

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Pravni podatki in metapodatki

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

označuje neobvezno polje, ki je lahko brez vrednosti ali prazno

Primeri kode

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

Odzivi ob napakah

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

Žeton je veljaven in ima paket Pro, vendar nima ravni dostopa metrics:write, ki je potrebna za poročanje o meritvah.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Obvestilo pripada drugemu izdajatelju. Nič se ne zapiše.

PUT /advertisement/{PAID}/metrics

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

400 INVALID_METRICS

Telo zahteve ni veljaven JSON ali pa obe števili manjkata, sta negativni ali nista celi števili. Odziv navede, kaj ni uspelo.

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

Temu PA-ID ne ustreza nobeno obvestilo ali pa vam še ni vidno. Preden sklepate, da je identifikator napačen, preberite zgornji razdelek.

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

Omejitev števila zahtev na žeton je bila presežena. Odziv vsebuje glave X-RateLimit-Limit, X-RateLimit-Remaining in 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"
}

Različice in opuščanje

Strojno berljiva specifikacija

Celoten dokument OpenAPI 3.1 je na voljo na /api/docs. Namesto prepisovanja te strani usmerite Postman, Swagger UI ali generator odjemalcev neposredno nanj.

https://polads.eu/api/docs

Se povezujete kot platforma na strani ponudbe (SSP)? Preberite dokumentacijo za API SSP