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
/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 agli annunci pubblicitari online. Funziona solo per gli annunci con mezzo = "online".
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Visualizzi l'etichetta sulla sua piattaforma:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>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. Contatti il suo 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 è risolto con 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 riga, per un’etichetta disegnata dalla sua piattaforma. Il contrassegno restituisce un avviso interattivo già composto, che lei colloca accanto all’annuncio 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 può scegliere nella pagina dimostrativa e copiare l'URL che vede.
# Contrassegno d'angolo, solo il segno
GET https://polads.eu/badge/{PA-ID}
# Contrassegno d'angolo con la dicitura
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Striscia con 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 omettete, si ottiene il contrassegno d'angolo. variant=labelled fa mostrare la dicitura al contrassegno chiuso. Se lo omettete, resta solo il segno. w e h dichiarano lo spazio in cui si trova il contrassegno e determinano come si adatta quando lo spazio è ridotto. Se li omettete, il contrassegno presume di avere spazio sufficiente, il che è corretto per i formati standard.
hover=0 serve alla dimostrazione, non alla vostra pagina
Impone la versione senza puntatore affinché la dimostrazione possa mostrare la versione tattile in un browser su computer. Il contrassegno reale rileva da sé il tipo di dispositivo. Se fissate il valore nel codice, inviate la versione sbagliata a ogni visitatore il cui dispositivo è diverso.
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 di identificazione 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 è trascorsa. 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. Puntate Postman, Swagger UI o un generatore di client direttamente su di esso anziché ricopiare questa pagina.
https://polads.eu/api/docs