Documentazione dell'API partner
API di dati sui messaggi di pubblicità politica per partner dei media ed editori
https://polads.eu/api/v1Tutti gli endpoint richiedono l'autenticazione con il token Bearer del partner
GET /advertisement-full/{PAID}
1.000 richieste al minuto
GET /advertisement/{PAID}
1.000 richieste al minuto
Il limite di frequenza si applica a ciascun token partner su tutti gli endpoint
Piano Pro, verificato a ogni richiesta
L’API partner fa parte del piano Pro, sia in lettura sia in scrittura. Non esiste un componente aggiuntivo API da acquistare separatamente. Il piano viene verificato a ogni singola richiesta anziché registrato alla creazione del token, quindi un abbonamento scaduto interrompe l’accesso già alla chiamata successiva con 403 PRO_PLAN_REQUIRED, e il rinnovo lo ripristina con la stessa immediatezza.
Ambiti
Ogni token partner può leggere. Per segnalare le metriche di coinvolgimento è inoltre necessario l’ambito metrics:write. Gli ambiti si scelgono al momento della generazione del token e non possono essere modificati in seguito: per cambiarli occorre revocare il token e generarne uno nuovo.
Solo token partner
Questi endpoint rifiutano un token SSP con 401, e l’endpoint SSP rifiuta allo stesso modo un token partner. I due livelli sono credenziali distinte, non due livelli di autorizzazione della stessa credenziale.
GET /advertisement/{PAID} individua l’avviso di trasparenza 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 qui esattamente come nel registro. Lo stesso vale per l’endpoint SSP.
L’endpoint del record completo è volutamente diverso
GET /advertisement-full/{PAID} è limitato ai vostri annunci, quindi risponde anche per un annuncio che non ha ancora raggiunto la data di inizio. Siete voi l’editore che deve esaminare quell’annuncio prima della pubblicazione: negarvelo vanificherebbe lo scopo.
/advertisement-full/{PAID}Limitato ai vostri annunci. Il PA-ID di un altro editore, un annuncio autopubblicato senza editore e un identificatore inesistente restituiscono tutti lo stesso 404, e la risposta non li distingue.
⚠️ Avviso: dati sensibili ai fini del GDPR
Questo endpoint restituisce TUTTI i campi, inclusi indirizzi e-mail, numeri di telefono e indirizzi completi. Utilizza questo endpoint solo se hai un’esigenza aziendale legittima e se disponi di adeguati accordi sul trattamento dei dati.
curl -X GET "https://polads.eu/api/v1/advertisement-full/ABC12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Campi dell’inserzionista:
companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country
Campi della campagna:
name, totalValue, medium, isOngoing, startDate, endDate
Inserzionisti ed entità controllanti:
Tutti i campi, inclusi e-mail, telefoni e indirizzi completi
/advertisement/{PAID}/metricsQuesto endpoint richiede una chiave con l’ambito Lettura e scrittura. L’API partner è inclusa nel piano Pro.
Puoi comunicare le metriche solo per gli annunci pubblicati tramite il tuo account.
L’annuncio appartiene a un altro editore. Non viene scritto nulla.
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}'Informazioni di base
Conformità e finanziamento
Targeting
Informazioni legali e metadati
// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();401 INVALID_TOKEN
Nessun token attivo corrisponde alla credenziale Bearer, oppure il token è stato revocato. Anche un’intestazione Authorization mancante o malformata riceve la risposta 401, ma solo l’endpoint delle metriche la contrassegna con questo codice. Un token SSP usato su un endpoint partner riceve la stessa risposta.
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
Il token è valido ma il suo editore non ha il piano Pro. Questo controllo precede quello dell’ambito, quindi un token di sola lettura di un editore senza piano Pro segnala il piano e non l’ambito.
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
Il token è valido e ha il piano Pro, ma non dispone dell’ambito metrics:write necessario per segnalare le metriche.
PUT /advertisement/{PAID}/metrics{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}403 FORBIDDEN
L’annuncio appartiene a un altro editore. Non viene scritto nulla.
PUT /advertisement/{PAID}/metrics{
"error": "This advertisement belongs to a different publisher.",
"code": "FORBIDDEN"
}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.
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’avviso non rientra nell’ambito per cui sono definite le metriche di coinvolgimento. La nota 15 dell’allegato II riguarda un avviso online o nativo che ha utilizzato tecniche di targeting o tecniche di consegna del messaggio pubblicitario e la cui diffusione è iniziata. Non viene scritto nulla.
PUT /advertisement/{PAID}/metrics{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}404 NOT_FOUND
Nessun avviso corrisponde a quel PA-ID, oppure non è ancora visibile per te. Consulta la sezione precedente prima di supporre che l’identificatore sia errato.
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 limite per token è stato superato. Questa risposta include le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e 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"
}Questa è la versione v1 dell’API e ogni risposta lo indica nell’intestazione X-API-Version. Le modifiche non retrocompatibili vengono pubblicate su un nuovo percorso anziché modificare quello attuale. Un endpoint v1 non verrà disattivato senza un’intestazione Deprecation inviata almeno 90 giorni prima, 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 a questo indirizzo anziché ricopiare questa pagina.
https://polads.eu/api/docs