Documentazione API SSP
API della piattaforma lato offerta (SSP) per le piattaforme pubblicitarie programmatiche
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 richieste al minuto
Limite di frequenza applicato a ciascun token SSP
PUT /online-advertisement/{PAID}/metrics
1.000 richieste al minuto
Le richieste vengono conteggiate per ciascun token SSP, separatamente dall’endpoint delle etichette, quindi la comunicazione delle metriche non consuma mai le tue richieste di etichette
/online-advertisement/{PAID}📊 Formato compatto dell’etichetta
Questo endpoint restituisce un’etichetta di trasparenza compatta e conforme alla normativa UE, adatta a essere visualizzata accanto ai messaggi pubblicitari online. Funziona solo per i messaggi pubblicitari con mezzo = "online".
Richiesta di esempio
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Esempio di risposta
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Campi della risposta
Esempio di utilizzo
Visualizza l'etichetta sulla tua piattaforma:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsIl tuo token SSP deve disporre del permesso metrics:write. Un amministratore lo attiva sul token che già utilizzi, quindi non viene rilasciato alcun nuovo token.
Invia i totali cumulativi dalla pubblicazione dell’avviso, mai la variazione rispetto al tuo ultimo invio. Ogni invio sostituisce i dati precedenti, quindi inviare di nuovo gli stessi totali non cambia nulla.
Puoi comunicare i dati di qualsiasi avviso pubblicato, a prescindere dall’editore a cui appartiene. I dati compaiono nel relativo avviso di trasparenza pubblico, con la data dell’ultima comunicazione.
Richiesta di esempio
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}'Campi della richiesta
Entrambi i campi sono obbligatori e ciascuno deve essere un numero intero compreso tra 0 e 2147483647.
Esempio di risposta
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Risposte di errore di questo endpoint
401 INVALID_TOKEN
L’intestazione Authorization è assente, oppure il token è sconosciuto, revocato o è un token partner. In entrambi i casi viene restituito il codice 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
Il token è valido, ma non gli è stato concesso il permesso metrics:write. Chiedi al tuo amministratore di attivarlo.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Nessun avviso pubblicato corrisponde a questo PA-ID. Come per l’endpoint delle etichette, restituisce 404 anche un avviso non ancora approvato dal suo editore o la cui data di inizio della pubblicazione non è ancora arrivata.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
L’avviso non rientra nell’ambito per il quale sono definite le metriche di interazione. La nota 15 dell’allegato II riguarda gli avvisi online o nativi che hanno utilizzato tecniche di targeting o tecniche di consegna del messaggio pubblicitario e la cui diffusione è iniziata. Nessun dato viene registrato.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
Il corpo della richiesta non è un JSON valido, oppure i due conteggi mancano, sono negativi o non sono numeri interi. La risposta indica quali controlli non sono stati superati.
{
"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 limite per token è stato superato. Questa risposta include le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Formato dell'intestazione
Authorization: Bearer YOUR_SSP_TOKENFormato del token
Stringa esadecimale di 64 caratteri (entropia a 256 bit)
Gestione dei token
I token SSP sono gestiti esclusivamente dagli amministratori di sistema. Contatta il tuo amministratore per ottenere un token.
Non si applica alcun piano di abbonamento
Un token SSP è rilasciato a un integratore e non a un editore, quindi non è associato ad alcun account editore e non c’è alcun piano da verificare. A differenza dell’API partner, qui nulla dipende da un abbonamento. Un token partner è rifiutato su questo endpoint con 401, e un token SSP è rifiutato allo stesso modo sugli endpoint partner.
Quando l’endpoint restituisce 404
L’avviso viene individuato applicando la stessa regola di visibilità del registro pubblico. Un avviso non ancora confermato, non ancora approvato dal suo editore o la cui data di inizio pubblicazione è ancora futura restituisce 404. Un 404 non dimostra quindi che un PA-ID sia errato.
L’endpoint qui sopra restituisce il TESTO dell’etichetta su una sola riga, per un’etichetta disegnata dalla tua piattaforma. Il contrassegno restituisce un avviso interattivo già composto, da collocare accanto al messaggio pubblicitario in un iframe. Entrambi descrivono lo stesso avviso di trasparenza.
Un URL per ogni versione
I comandi della dimostrazione corrispondono uno a uno a questi parametri, quindi puoi scegliere nella pagina dimostrativa e copiare l’URL che vedi.
# Contrassegno d’angolo, solo il simbolo
GET https://polads.eu/badge/{PA-ID}
# Contrassegno d’angolo con la dicitura visibile
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Striscia dell’etichetta sempre visibile
GET https://polads.eu/badge/{PA-ID}?layout=labelCosa fa ciascun parametro e cosa comporta ometterlo
layout=label seleziona la striscia. Se lo ometti, si ottiene il contrassegno d’angolo. variant=labelled fa mostrare la dicitura al contrassegno chiuso. Se lo ometti, resta solo il simbolo. w e h dichiarano lo spazio in cui si trova il contrassegno e determinano come si adatta quando lo spazio è ridotto. Se li ometti, il contrassegno presume di avere spazio sufficiente, il che è corretto per i formati standard.
hover=0 serve alla dimostrazione, non alla tua pagina
Impone la versione per dispositivi senza puntatore, così la dimostrazione può mostrare la versione tattile in un browser su computer. Il contrassegno reale rileva da sé il tipo di dispositivo. Se fissi questo valore nel codice, invii la versione sbagliata a ogni visitatore il cui dispositivo non corrisponde.
Il gestore dell’evento di ridimensionamento è obbligatorio
Il contrassegno d’angolo si carica a 32 per 32 per coprire il meno possibile la creatività, poi chiede spazio alla pagina ospitante quando si apre. Senza il gestore dell’evento non può aprirsi affatto. La striscia dell’etichetta si adatta in modo più graduale e viene tagliata solo a larghezze ridotte.
Disponibile solo per un avviso pubblicato
Il contrassegno viene fornito quando l’avviso è confermato, approvato dall’editore e la data di inizio pubblicazione è stata raggiunta. Un PA-ID sotto embargo o non approvato restituisce 404 per scelta progettuale, non per un errore.
Apri la dimostrazione interattiva e copia il codice di incorporamento
401 Non autorizzato
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Richiesta non valida
L’annuncio è stato trovato, ma il suo mezzo non è online. La risposta restituisce il valore reale del mezzo, per esempio print. Un PA-ID mancante o sconosciuto restituisce invece 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Non trovato
{
"error": "Advertisement not found"
}429 Limite di richieste superato
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Questa è la versione v1 dell'API e ogni risposta lo indica nell'intestazione X-API-Version. Le modifiche non retrocompatibili vengono pubblicate sotto un nuovo percorso, senza modificare questo. Un endpoint v1 non verrà disattivato senza un'intestazione Deprecation inviata con almeno 90 giorni di anticipo, secondo la RFC 8594.
Specifica leggibile da una macchina
Il documento OpenAPI 3.1 completo è disponibile su /api/docs. Punta Postman, Swagger UI o un generatore di client direttamente su di esso anziché ricopiare questa pagina.
https://polads.eu/api/docs