API s podatki o političnih oglasih za partnerske medije in izdajatelje
https://polads.eu/api/v1Vse končne točke zahtevajo preverjanje pristnosti s partnerskim žetonom Bearer
GET /advertisement-full/{PAID}
1000 zahtev na minuto
GET /advertisement/{PAID}
1000 zahtev na minuto
Omejitev velja za vsak partnerski žeton posebej, in sicer za vse končne točke skupaj
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, ne pa le enkrat ob ustvarjanju žetona, zato potekla naročnina onemogoči dostop že ob naslednjem klicu z odgovorom 403 PRO_PLAN_REQUIRED, podaljšanje naročnine pa dostop 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 dostopa sta ločeni poverilnici in ne dve ravni dovoljenj v okviru iste poverilnice.
Končna točka 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.
/advertisement-full/{PAID}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.
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 subjekti, ki imajo nad njimi končni nadzor:
Vsa polja, vključno z e-poštnimi naslovi, telefoni in polnimi naslovi
/advertisement/{PAID}/metricsTa končna točka zahteva ključ z ravnjo dostopa 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}'Osnovne informacije
Skladnost in financiranje
Ciljanje
Pravni podatki in metapodatki
// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();401 INVALID_TOKEN
Poverilnici Bearer ne ustreza noben aktiven žeton ali pa je bil žeton preklican. Tudi ob manjkajoči ali napačno oblikovani glavi Authorization je odziv 401, vendar ga s to kodo označi le končna točka metrics. Enak odziv prejme tudi žeton SSP na partnerski končni točki.
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. Paket se preveri, preden se preveri obseg, zato žeton samo za branje, ki pripada izdajatelju brez paketa Pro, vrne napako zaradi paketa in ne zaradi obsega.
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 obsega metrics:write, ki je potreben 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 števili manjkata, sta negativni ali nista celi števili. V odzivu je navedeno, 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 nativno obvestilo, pri katerem so bile uporabljene tehnike ciljanja ali tehnike prikazovanja oglasov in katerega prikazovanje se je že začelo. Ničesar 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 identifikatorju PA-ID ne ustreza nobeno obvestilo ali pa vam obvestilo š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"
}To je različica v1 vmesnika API, kar vsak odziv navaja v glavi X-API-Version. Nezdružljive spremembe so objavljene pod novo potjo, obstoječa pot pa se ne spreminja. 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