Dokumentazzjoni tal-API SSP
API ta’ pjattaforma tan-naħa tal-provvista għal pjattaformi ta’ reklamar programmatiku
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10,000 talba kull minuta
Il-limitu tar-rata jiġi applikat għal kull token SSP
PUT /online-advertisement/{PAID}/metrics
1,000 talba kull minuta
Jingħaddu għal kull token SSP, separatament mill-endpoint tat-tikketti, għalhekk ir-rappurtar tal-metriċi qatt ma jnaqqas mill-kwota tat-talbiet tiegħek għat-tikketti
/online-advertisement/{PAID}📊 Format kompatt tat-tikketta
Dan l-endpoint jirritorna tikketta ta' trasparenza kompatta u konformi mar-regoli tal-UE, adattata biex tintwera ħdejn reklami online. Jaħdem biss għal reklami li l-mezz tagħhom huwa "online".
Eżempju ta' talba
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Eżempju ta' tweġiba
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Oqsma tat-tweġiba
Eżempju ta' użu
Uri t-tikketta fuq il-pjattaforma tiegħek:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsIt-token SSP tiegħek jeħtieġ il-permess metrics:write. Amministratur jattivah fuq it-token li diġà qed tuża, għalhekk ma jinħareġ l-ebda token ġdid.
Ibgħat it-totali kumulattivi minn meta ġie ppubblikat l-avviż, qatt mhux il-bidla mill-aħħar trażmissjoni tiegħek. Kull trażmissjoni tissostitwixxi ċ-ċifri ta’ qabilha, għalhekk jekk terġa’ tibgħat l-istess totali ma jinbidel xejn.
Tista’ tirrapporta kwalunkwe avviż ippubblikat, ikun x’ikun il-pubblikatur li jappartjeni għalih. Iċ-ċifri jidhru fl-avviż ta’ trasparenza pubbliku tiegħu, flimkien mad-data meta ġew irrappurtati l-aħħar darba.
Eżempju ta' talba
curl -X PUT "https://polads.eu/api/v1/online-advertisement/ABC12/metrics" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"viewsCount": 15000, "engagementsCount": 320}'Oqsma tat-talba
Iż-żewġ oqsma huma obbligatorji, u kull wieħed irid ikun numru sħiħ minn 0 sa 2147483647.
Eżempju ta' tweġiba
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Tweġibiet ta' żball minn dan l-endpoint
401 INVALID_TOKEN
L-intestatura Authorization nieqsa, jew it-token mhux magħruf, ġie revokat jew huwa token ta’ sieħeb. Fiż-żewġ każijiet, it-tweġiba ġġorr il-kodiċi INVALID_TOKEN.
{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>",
"code": "INVALID_TOKEN"
}{
"error": "Invalid or revoked SSP API token.",
"code": "INVALID_TOKEN"
}403 INSUFFICIENT_SCOPE
It-token huwa validu iżda ma ngħatax il-permess metrics:write. Itlob lill-amministratur tiegħek biex jattivah.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
L-ebda avviż ippubblikat ma jaqbel ma’ dak il-PA-ID. Bħal fl-endpoint tat-tikketti, avviż li l-pubblikatur tiegħu għadu ma approvahx, jew li d-data tal-bidu tal-pubblikazzjoni tiegħu għadha fil-futur, jirritorna wkoll 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}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.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}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.
{
"error": "Invalid engagement metrics",
"code": "INVALID_METRICS",
"issues": [
{
"path": "viewsCount",
"message": "Too small: expected number to be >=0"
}
]
}{
"error": "Invalid request body",
"code": "INVALID_METRICS"
}429 RATE_LIMITED
Il-limitu għal kull token inqabeż. It-tweġiba ġġorr X-RateLimit-Limit, X-RateLimit-Remaining u X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Format tal-intestatura
Authorization: Bearer YOUR_SSP_TOKENFormat tat-token
Sekwenza eżadeċimali ta’ 64 karattru (entropija ta’ 256 bit)
Ġestjoni tat-tokens
It-tokens SSP jiġu ġestiti biss mill-amministraturi tas-sistema. Ikkuntattja lill-amministratur tiegħek biex tikseb token.
L-ebda pjan ta’ abbonament ma japplika
Token SSP jinħareġ lil integratur u mhux lil pubblikatur, għalhekk ma jappartjeni għall-ebda kont ta’ pubblikatur u m’hemm l-ebda pjan x’jiġi vverifikat. B’differenza mill-API tas-sħab, hawn xejn ma jiddependi minn abbonament. Token ta’ sieħeb jiġi rrifjutat f’dan l-endpoint b’401, u token SSP jiġi rrifjutat bl-istess mod fl-endpoints tas-sħab.
Meta l-endpoint jirritorna 404
L-avviż jiġi determinat bl-istess regola ta’ viżibilità bħar-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. Għalhekk 404 mhuwiex prova li PA-ID huwa żbaljat.
L-endpoint ta’ hawn fuq jirritorna t-TEST tat-tikketta fuq linja waħda, għal tikketta li tpinġi l-pjattaforma tiegħek stess. Il-marka tirritorna avviż interattiv lest, li tqiegħed ħdejn ir-reklam f’qafas. It-tnejn jiddeskrivu l-istess avviż ta’ trasparenza.
URL wieħed għal kull verżjoni
Il-kontrolli tad-dimostrazzjoni jaqblu ma’ dawn il-parametri wieħed b’wieħed, għalhekk tista’ tagħżel fil-paġna tad-dimostrazzjoni u tikkopja l-URL li tara.
# Marka tal-kantuniera, is-simbolu biss
GET https://polads.eu/badge/{PA-ID}
# Marka tal-kantuniera bil-kliem tagħha
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Strixxa tat-tikketta li tidher dejjem
GET https://polads.eu/badge/{PA-ID}?layout=labelX’jagħmel kull parametru, u xi jfisser jekk tħallih barra
layout=label jagħżel l-istrixxa. Jekk tħallih barra, tieħu l-marka tal-kantuniera. variant=labelled iġiegħel lill-marka magħluqa turi l-kliem tagħha. Jekk tħallih barra, tieħu s-simbolu waħdu. w u h jiddikjaraw l-ispazju fejn tinsab il-marka u jagħżlu kif tadatta f’spazju dejjaq. Jekk tħallihom barra, il-marka tassumi li għandha biżżejjed spazju, u dan huwa korrett għall-formati standard.
hover=0 huwa għad-dimostrazzjoni, mhux għall-paġna tiegħek
Jġiegħel it-tqassim għal apparati mingħajr maws, biex id-dimostrazzjoni tkun tista’ turi l-verżjoni għall-iskrin tal-mess fuq kompjuter. Il-marka vera tivverifika l-apparat waħedha. Jekk tiffissah fil-kodiċi, tibgħat il-verżjoni żbaljata lil kull viżitatur li l-apparat tiegħu ma jaqbilx.
Is-semmiegħ tal-bidla fid-daqs huwa meħtieġ
Il-marka tal-kantuniera titgħabba f’32 b’32 biex tkopri l-inqas possibbli mill-kontenut tar-reklam, imbagħad titlob spazju lill-paġna ospitanti meta tinfetaħ. Mingħajr is-semmiegħ ma tistax tinfetaħ xejn. L-istrixxa tat-tikketta tadatta b’mod aktar ġentili, u tinqata’ biss f’wisgħat dojoq.
Disponibbli biss għal avviż ippubblikat
Il-marka tiġi pprovduta ladarba l-avviż ikun ikkonfermat, approvat mill-pubblikatur u tkun għaddiet id-data tal-bidu tal-pubblikazzjoni tiegħu. PA-ID taħt embargo jew mhux approvat iwieġeb 404 apposta, mhux minħabba xi żball.
Iftaħ id-dimostrazzjoni interattiva u kkopja l-kodiċi għall-inkorporazzjoni
401 Mhux awtorizzat
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Talba invalida
Ir-reklam instab, iżda l-mezz tiegħu mhuwiex online. It-tweġiba tirritorna l-valur reali tal-mezz, pereżempju print. PA-ID nieqes jew mhux magħruf minflok jirritorna 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Ma nstabx
{
"error": "Advertisement not found"
}429 Inqabeż il-limitu tar-rata
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Din hija l-verżjoni API v1, u kull tweġiba tgħid dan f'intestatura X-API-Version. Bidliet li jkissru l-kompatibbiltà joħorġu taħt mogħdija ġdida minflok ma jibdlu din. Punt finali v1 mhux se jintefa 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. Ipponta lil Postman, Swagger UI jew ġeneratur ta' klijenti direttament lejh minflok ma tikkopja din il-paġna.
https://polads.eu/api/docs