Dokumentácia partnerského rozhrania API

Rozhranie API s údajmi o politických reklamných oznámeniach pre partnerov z radov médií a vydavateľov

API v1

Vyžaduje sa partnerský token Bearer

V súlade s GDPR

Základná adresa URL

https://polads.eu/api/v1

Všetky koncové body vyžadujú overenie partnerským tokenom Bearer

Obmedzenie počtu požiadaviek

Všetky partnerské koncové body majú spoločný limit počtu požiadaviek na jeden token Bearer

GET /advertisement-full/{PAID}

1 000 požiadaviek za minútu

GET /advertisement/{PAID}

1 000 požiadaviek za minútu

Limit počtu požiadaviek sa uplatňuje na každý partnerský token vo všetkých koncových bodoch

Požiadavky na prístup

Čo musí partnerský token spĺňať, aby koncový bod odpovedal

Plán Pro, overovaný pri každej požiadavke

Partnerské API je súčasťou plánu Pro, a to pri čítaní aj pri zápise. Samostatný doplnok API sa nekupuje. Plán sa overuje pri každej jednotlivej požiadavke, nezaznamenáva sa pri vytvorení tokenu, takže po skončení predplatného sa prístup zastaví hneď pri nasledujúcom volaní s kódom 403 PRO_PLAN_REQUIRED a po jeho obnovení sa rovnako okamžite obnoví.

Rozsahy oprávnení

Každý partnerský token môže čítať. Hlásenie metrík zapojenia si navyše vyžaduje rozsah metrics:write. Rozsahy sa určujú pri vytvorení tokenu a neskôr ich nemožno upraviť: ak ich chcete zmeniť, token odvolajte a vytvorte nový.

Iba partnerské tokeny

Tieto koncové body odmietnu token SSP s kódom 401 a koncový bod SSP rovnako odmietne partnerský token. Ide o dva samostatné druhy prihlasovacích údajov, nie o dve úrovne oprávnení v rámci jedného.

Kedy koncový bod vráti 404

Kód 404 nie je dôkazom, že je PA-ID nesprávne

GET /advertisement/{PAID} vyhľadá oznámenie podľa rovnakého pravidla viditeľnosti ako verejný register. Oznámenie, ktoré ešte nie je potvrdené, ktoré jeho vydavateľ ešte neschválil alebo ktorého dátum začiatku zverejnenia je ešte v budúcnosti, tu vráti 404 presne tak ako v registri. To isté platí pre koncový bod SSP.

Koncový bod s úplným záznamom sa zámerne správa inak

GET /advertisement-full/{PAID} je obmedzený na vaše vlastné oznámenia, a preto odpovie aj pri oznámení, ktoré ešte nedosiahlo dátum začiatku zverejnenia. Ste vydavateľ, ktorý musí toto oznámenie preveriť ešte pred jeho zverejnením, takže zadržať ho pred vami by nemalo zmysel.

GET

/advertisement-full/{PAID}

Získajte úplné údaje o politickom reklamnom oznámení vrátane VŠETKÝCH polí citlivých z hľadiska GDPR (vyžaduje sa token Bearer)

Obmedzené na vaše vlastné oznámenia. PA-ID iného vydavateľa, oznámenie zverejnené vlastnými silami bez vydavateľa aj neexistujúci identifikátor vrátia rovnaký kód 404 a odpoveď ich od seba nerozlišuje.

⚠️ Upozornenie: údaje citlivé z hľadiska GDPR

Tento koncový bod vracia VŠETKY polia vrátane e-mailových adries, telefónnych čísel a úplných adries. Používajte ho iba vtedy, ak máte oprávnenú obchodnú potrebu a uzavreté príslušné zmluvy o spracúvaní údajov.

Token Bearer

PA-ID

Príklad požiadavky

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

Odpoveď obsahuje (NEFILTROVANÉ ÚDAJE)

Polia inzerenta:

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

Polia kampane:

name, totalValue, medium, isOngoing, startDate, endDate

Inzerenti a prevádzkovatelia:

Všetky polia vrátane e-mailov, telefónov a úplných adries

Nahlasovanie metrík interakcií

PUT

/advertisement/{PAID}/metrics

Odosielajte počty zobrazení a interakcií zaznamenané po zverejnení vašich vlastných inzerátov.

Tento koncový bod vyžaduje kľúč s rozsahom Čítanie a zápis. Partnerské API je súčasťou plánu Pro.

Metriky môžete nahlasovať iba pri inzerátoch zverejnených prostredníctvom vášho vlastného účtu.

Inzerát patrí inému vydavateľovi. Nič sa nezapisuje.

Príklad požiadavky

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

Dostupné polia

Dátové polia vrátené rozhraním API s ich typmi

Základné informácie

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Súlad a financovanie

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Cielenie

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Právne údaje a metadáta

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

označuje voliteľné pole, ktoré môže mať hodnotu null alebo byť prázdne

Príklady kódu

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

Chybové odpovede

Každá chyba vracia telo JSON s chybovou správou a každá odpoveď obsahuje hlavičku X-API-Version. Strojovo čitateľný kód sprevádza odmietnutia z dôvodu neplatného tokenu a plánu, ako aj vlastné chyby validácie koncového bodu metrics. Chýbajúca hlavička Authorization, chyba 404 alebo 429 z koncového bodu na čítanie a akákoľvek interná chyba servera obsahujú iba správu.

401 INVALID_TOKEN

Povereniu Bearer nezodpovedá žiadny aktívny token, alebo bol token odvolaný. Chýbajúca alebo chybne formátovaná hlavička Authorization tiež vracia 401, ale týmto kódom ju označuje iba koncový bod metrics. Token SSP na partnerskom koncovom bode dostane rovnakú odpoveď.

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

Token je platný, ale jeho vydavateľ nemá plán Pro. Overuje sa to pred rozsahom oprávnení, takže token len na čítanie, ktorý patrí vydavateľovi bez plánu Pro, vráti chybu plánu, a nie rozsahu oprávnení.

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

Token je platný a má plán Pro, ale chýba mu rozsah oprávnení metrics:write potrebný na nahlasovanie metrík.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Inzerát patrí inému vydavateľovi. Nič sa nezapisuje.

PUT /advertisement/{PAID}/metrics

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

400 INVALID_METRICS

Telo požiadavky nie je platný JSON alebo niektorý z dvoch počtov chýba, je záporný alebo nie je celé číslo. Odpoveď uvádza, čo neprešlo kontrolou.

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

Oznámenie nepatrí do rozsahu, pre ktorý sú metriky zapojenia vymedzené. Poznámka 15 v prílohe II sa vzťahuje na online alebo natívne oznámenie, pri ktorom sa použili techniky cielenia alebo techniky dodávania reklamy a ktoré sa už začalo zobrazovať. Nič sa nezapisuje.

PUT /advertisement/{PAID}/metrics

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

404 NOT_FOUND

Tomuto PA-ID nezodpovedá žiadne oznámenie alebo pre vás ešte nie je viditeľné. Skôr než usúdite, že identifikátor je nesprávny, prečítajte si oddiel vyššie.

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

Limit pre token bol prekročený. Táto odpoveď obsahuje hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a 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"
}

Verziovanie a ukončovanie podpory

Toto je verzia API v1 a každá odpoveď to uvádza v hlavičke X-API-Version. Nekompatibilné zmeny sa zavádzajú pod novou cestou a táto cesta sa nemení. Koncový bod v1 sa nevypne bez toho, aby to najmenej 90 dní vopred ohlásila hlavička Deprecation v súlade s RFC 8594.

Strojovo čitateľná špecifikácia

Úplný dokument OpenAPI 3.1 je k dispozícii na /api/docs. Namiesto prepisovania tejto stránky naň priamo nasmerujte Postman, Swagger UI alebo generátor klienta.

https://polads.eu/api/docs

Integrujete sa ako platforma na strane ponuky (SSP)? Prečítajte si dokumentáciu k API pre SSP

Dokumentácia partnerského rozhrania API

Rozhranie API s údajmi o politických reklamných oznámeniach pre partnerov z radov médií a vydavateľov

API v1

Vyžaduje sa partnerský token Bearer

V súlade s GDPR

Základná adresa URL

https://polads.eu/api/v1

Všetky koncové body vyžadujú overenie partnerským tokenom Bearer

Obmedzenie počtu požiadaviek

Všetky partnerské koncové body majú spoločný limit počtu požiadaviek na jeden token Bearer

GET /advertisement-full/{PAID}

1 000 požiadaviek za minútu

GET /advertisement/{PAID}

1 000 požiadaviek za minútu

Limit počtu požiadaviek sa uplatňuje na každý partnerský token vo všetkých koncových bodoch

Požiadavky na prístup

Čo musí partnerský token spĺňať, aby koncový bod odpovedal

Plán Pro, overovaný pri každej požiadavke

Rozsahy oprávnení

Iba partnerské tokeny

Kedy koncový bod vráti 404

Kód 404 nie je dôkazom, že je PA-ID nesprávne

Koncový bod s úplným záznamom sa zámerne správa inak

GET

/advertisement-full/{PAID}

Získajte úplné údaje o politickom reklamnom oznámení vrátane VŠETKÝCH polí citlivých z hľadiska GDPR (vyžaduje sa token Bearer)

⚠️ Upozornenie: údaje citlivé z hľadiska GDPR

Token Bearer

PA-ID

Príklad požiadavky

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

Odpoveď obsahuje (NEFILTROVANÉ ÚDAJE)

Polia inzerenta:

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

Polia kampane:

name, totalValue, medium, isOngoing, startDate, endDate

Inzerenti a prevádzkovatelia:

Všetky polia vrátane e-mailov, telefónov a úplných adries

Nahlasovanie metrík interakcií

PUT

/advertisement/{PAID}/metrics

Odosielajte počty zobrazení a interakcií zaznamenané po zverejnení vašich vlastných inzerátov.

Tento koncový bod vyžaduje kľúč s rozsahom Čítanie a zápis. Partnerské API je súčasťou plánu Pro.

Metriky môžete nahlasovať iba pri inzerátoch zverejnených prostredníctvom vášho vlastného účtu.

Inzerát patrí inému vydavateľovi. Nič sa nezapisuje.

Príklad požiadavky

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

Dostupné polia

Dátové polia vrátené rozhraním API s ich typmi

Základné informácie

advertiserName

string

isAdvertiserInEU

boolean

campaignName

string

messageDescription

string

campaignMedium

string?

tilknytning

string?

Súlad a financovanie

isIntendedToInfluenceElection

boolean

isSponsoredContent

boolean

isPublicFunding

boolean

isFundingFromEU

boolean

totalAmount

string

adPayer

string?

Cielenie

isTargetingBasedOnPersonalData

boolean

targetingCriteria

string?

isSpecialDataCategoryUsed

boolean

specialDataDetails

string?

Právne údaje a metadáta

isCompliantWithEURegulations

boolean

hasRightToPlaceAdInEU

boolean

whichElection

string?

whoPaysForAd

string?

string

itemId

string

string?

označuje voliteľné pole, ktoré môže mať hodnotu null alebo byť prázdne

Príklady kódu

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

Chybové odpovede

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

Token je platný a má plán Pro, ale chýba mu rozsah oprávnení metrics:write potrebný na nahlasovanie metrík.

PUT /advertisement/{PAID}/metrics

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

403 FORBIDDEN

Inzerát patrí inému vydavateľovi. Nič sa nezapisuje.

PUT /advertisement/{PAID}/metrics

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

400 INVALID_METRICS

Telo požiadavky nie je platný JSON alebo niektorý z dvoch počtov chýba, je záporný alebo nie je celé číslo. Odpoveď uvádza, čo neprešlo kontrolou.

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

Tomuto PA-ID nezodpovedá žiadne oznámenie alebo pre vás ešte nie je viditeľné. Skôr než usúdite, že identifikátor je nesprávny, prečítajte si oddiel vyššie.

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

Limit pre token bol prekročený. Táto odpoveď obsahuje hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a 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"
}

Verziovanie a ukončovanie podpory

Strojovo čitateľná špecifikácia

Úplný dokument OpenAPI 3.1 je k dispozícii na /api/docs. Namiesto prepisovania tejto stránky naň priamo nasmerujte Postman, Swagger UI alebo generátor klienta.

https://polads.eu/api/docs

Integrujete sa ako platforma na strane ponuky (SSP)? Prečítajte si dokumentáciu k API pre SSP