Dokumentazzjoni tal-API għas-Sħab
API tad-data dwar ir-reklami politiċi għas-sħab tal-midja u l-pubblikaturi
https://polads.eu/api/v1L-endpoints kollha jeħtieġu awtentikazzjoni b’token Bearer tas-sieħeb
GET /advertisement-full/{PAID}
1,000 talba kull minuta
GET /advertisement/{PAID}
1,000 talba kull minuta
Il-limitu tar-rata huwa infurzat għal kull token tas-sieħeb fl-endpoints kollha
Pjan Pro, ivverifikat ma’ kull talba
L-API tas-sħab hija parti mill-pjan Pro, kemm għall-qari kif ukoll għall-kitba. M’hemmx żieda separata tal-API x’tixtri. Il-pjan jiġi vverifikat ma’ kull talba individwali minflok ma jiġi rreġistrat meta jinħoloq it-token, għalhekk abbonament skadut iwaqqaf l-aċċess mis-sejħa li jmiss stess b’403 PRO_PLAN_REQUIRED, u t-tiġdid jerġa’ jagħtih lura b’mod immedjat bl-istess mod.
Ambiti tal-aċċess
Kull token tas-sieħeb jista’ jaqra. Ir-rappurtar tal-metriċi tal-involviment jeħtieġ ukoll l-ambitu metrics:write. L-ambiti jintgħażlu meta jinħoloq it-token u ma jistgħux jinbidlu wara: biex tibdilhom, irrevoka t-token u oħloq wieħed ġdid.
Tokens tas-sħab biss
Dawn l-endpoints jirrifjutaw token SSP b’401, u l-endpoint SSP jirrifjuta token tas-sieħeb bl-istess mod. Iż-żewġ livelli huma kredenzjali separati, mhux żewġ livelli ta’ permess fuq l-istess kredenzjali.
GET /advertisement/{PAID} isib l-avviż permezz tal-istess regola ta’ viżibbiltà tar-reġistru pubbliku. Avviż li għadu mhux ikkonfermat, li l-pubblikatur tiegħu għadu ma approvahx, jew li d-data tal-bidu tal-pubblikazzjoni tiegħu għadha fil-futur, jirritorna 404 hawn eżattament kif jagħmel fir-reġistru. L-istess japplika għall-endpoint SSP.
L-endpoint tar-rekord sħiħ huwa differenti apposta
GET /advertisement-full/{PAID} huwa limitat għall-avviżi tiegħek stess, għalhekk iwieġeb anki għal avviż li għadu ma laħaqx id-data tal-bidu tiegħu. Inti l-pubblikatur li jrid jeżamina dak l-avviż qabel ma jibda r-reklam, għalhekk li jinżamm minnek ikun imur kontra l-għan tiegħu.
/advertisement-full/{PAID}Limitat għall-avviżi tiegħek stess. Il-PA-ID ta' pubblikatur ieħor, avviż awtopubblikat mingħajr pubblikatur, u identifikatur li ma jeżistix, ilkoll jirritornaw l-istess 404, u t-tweġiba ma tagħmilx distinzjoni bejniethom.
⚠️ Twissija dwar data sensittiva skont il-GDPR
Dan l-endpoint jirritorna l-oqsma KOLLHA, inklużi l-indirizzi tal-email, in-numri tat-telefon u l-indirizzi sħaħ. Uża dan l-endpoint biss jekk għandek ħtieġa kummerċjali leġittima u ftehimiet xierqa dwar l-ipproċessar tad-data fis-seħħ.
curl -X GET "https://polads.eu/api/v1/advertisement-full/ABC12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Oqsma ta' min jirreklama:
companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country
Oqsma tal-kampanja:
name, totalValue, medium, isOngoing, startDate, endDate
Min jirreklama u l-kontrolluri:
Il-kampi kollha, inklużi emails, telefowns u indirizzi sħaħ
/advertisement/{PAID}/metricsDan l-endpoint jeħtieġ ċavetta bl-ambitu Qari u kitba. L-API għall-imsieħba hija inkluża fil-pjan Pro.
Tista' tirrapporta metriċi biss għall-avviżi ppubblikati permezz tal-kont tiegħek stess.
L-avviż jappartjeni lil pubblikatur ieħor. Ma jinkiteb xejn.
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}'Informazzjoni bażika
Konformità u finanzjament
Immirar
Informazzjoni legali u metadata
// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();401 INVALID_TOKEN
L-ebda token attiv ma jaqbel mal-kredenzjal Bearer, jew it-token ġie revokat. Intestatura Authorization nieqsa jew difettuża twieġeb ukoll 401, iżda l-endpoint metrics biss jimmarkaha b’dan il-kodiċi. Token SSP fuq endpoint ta’ sieħeb jirċievi l-istess tweġiba.
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
It-token huwa validu iżda l-pubblikatur tiegħu mhuwiex fuq il-pjan Pro. Dan jiġi vverifikat qabel l-ambitu, għalhekk token ta' qari biss li jappartjeni lil pubblikatur mingħajr il-pjan Pro jirrapporta l-pjan u mhux l-ambitu.
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
It-token huwa validu u fuq il-pjan Pro, iżda m'għandux l-ambitu metrics:write meħtieġ biex jiġu rrappurtati l-metriċi.
PUT /advertisement/{PAID}/metrics{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}403 FORBIDDEN
L-avviż jappartjeni lil pubblikatur ieħor. Ma jinkiteb xejn.
PUT /advertisement/{PAID}/metrics{
"error": "This advertisement belongs to a different publisher.",
"code": "FORBIDDEN"
}400 INVALID_METRICS
Il-korp tat-talba mhuwiex JSON validu, jew iż-żewġ għadd huma nieqsa, negattivi jew mhumiex numri sħaħ. It-tweġiba telenka x'falla.
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-avviż jaqa' barra mill-kamp ta' applikazzjoni li għalih huma definiti l-metriċi ta' involviment. In-nota 15 tal-Anness II tkopri avviż online jew nattiv li uża tekniki tal-immirar jew tekniki tat-twassil tal-messaġġ tar-reklami u li diġà beda jintwera. Ma jinkiteb xejn.
PUT /advertisement/{PAID}/metrics{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}404 NOT_FOUND
L-ebda avviż ma jaqbel ma' dak il-PA-ID, jew għadu mhux viżibbli għalik. Ara t-taqsima ta' hawn fuq qabel ma tassumi li l-identifikatur huwa żbaljat.
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
Il-limitu għal kull token inqabeż. It-tweġiba ġġorr X-RateLimit-Limit, X-RateLimit-Remaining u 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"
}Din hija l-verżjoni v1 tal-API, u kull tweġiba tindika dan f'intestatura X-API-Version. Bidliet li jkissru l-kompatibbiltà joħorġu taħt mogħdija ġdida minflok ma tinbidel din. Endpoint v1 ma jintefiex mingħajr intestatura Deprecation mill-inqas 90 jum qabel, skont RFC 8594.
Speċifikazzjoni li tinqara mill-magni
Id-dokument OpenAPI 3.1 sħiħ huwa disponibbli fuq /api/docs. Idderieġi lil Postman, Swagger UI jew ġeneratur ta' klijenti direttament lejh minflok ma tittraskrivi din il-paġna.
https://polads.eu/api/docs