Documentación de la API SSP
API de plataforma del lado de la oferta para plataformas de publicidad programática
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10.000 solicitudes por minuto
Límite de solicitudes aplicado por token SSP
PUT /online-advertisement/{PAID}/metrics
1000 solicitudes por minuto
Se contabilizan por token SSP, aparte del punto final de etiquetas, por lo que comunicar métricas nunca consume su cupo de solicitudes de etiquetas
/online-advertisement/{PAID}📊 Formato de etiqueta compacta
Este punto final devuelve una etiqueta de transparencia compacta, conforme con la normativa de la UE, adecuada para mostrarse junto a anuncios en línea. Solo funciona con anuncios cuyo medio sea medium = "online".
Solicitud de ejemplo
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Ejemplo de respuesta
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Campos de la respuesta
Ejemplo de uso
Muestre la etiqueta en su plataforma:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsSu token SSP necesita el permiso metrics:write. Un administrador lo activa en el token que ya utiliza, por lo que no se emite ningún token nuevo.
Envíe los totales acumulados desde la publicación del aviso, nunca la variación desde su último envío. Cada envío sustituye las cifras anteriores, por lo que volver a enviar los mismos totales no cambia nada.
Puede comunicar las cifras de cualquier aviso publicado, sea cual sea el editor al que pertenezca. Las cifras aparecen en su aviso de transparencia público, junto con la fecha de su última comunicación.
Solicitud de ejemplo
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}'Campos de la solicitud
Ambos campos son obligatorios y cada uno debe ser un número entero entre 0 y 2147483647.
Ejemplo de respuesta
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Respuestas de error de este punto final
401 INVALID_TOKEN
Falta la cabecera Authorization, o el token es desconocido, está revocado o es un token de socio. En ambos casos se devuelve el código 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
El token es válido, pero no se le ha concedido el permiso metrics:write. Pida a su administrador que lo active.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Ningún aviso publicado coincide con ese PA-ID. Al igual que en el punto final de etiquetas, un aviso que su editor aún no ha aprobado, o cuya fecha de inicio de publicación todavía no ha llegado, también devuelve 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
El aviso queda fuera del ámbito para el que se definen las métricas de interacción. La nota 15 del anexo II abarca un aviso en línea o nativo que haya utilizado técnicas de segmentación o técnicas de entrega de anuncios y cuya difusión ya haya comenzado. No se escribe nada.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
El cuerpo de la solicitud no es un JSON válido, o las dos cifras faltan, son negativas o no son números enteros. La respuesta indica qué ha fallado.
{
"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
Se ha superado el límite por token. La respuesta incluye las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Formato de la cabecera
Authorization: Bearer YOUR_SSP_TOKENFormato del token
Cadena hexadecimal de 64 caracteres (entropía de 256 bits)
Gestión de tokens
Los tokens SSP solo los gestionan los administradores del sistema. Póngase en contacto con su administrador para obtener un token.
No se aplica ningún plan de suscripción
Un token SSP se emite a un integrador y no a un editor, por lo que no está vinculado a ninguna cuenta de editor y no hay ningún plan que comprobar. A diferencia de la API de socios, aquí nada depende de una suscripción. Un token de socio se rechaza en este punto final con 401, y un token SSP se rechaza del mismo modo en los puntos finales de socios.
Cuándo devuelve 404 el punto final
El aviso se resuelve con la misma regla de visibilidad que el registro público. Un aviso que aún no está confirmado, que su editor aún no ha aprobado o cuya fecha de inicio de publicación todavía no ha llegado devuelve 404. Por tanto, un 404 no prueba que un PA-ID sea incorrecto.
El punto final anterior devuelve el TEXTO de la etiqueta en una sola línea, para una etiqueta que dibuja su propia plataforma. El distintivo devuelve un aviso interactivo ya representado, que usted coloca junto al anuncio como iframe. Ambos describen el mismo aviso de transparencia.
Una URL por versión
Los controles de la demostración se corresponden uno a uno con estos parámetros, así que puede elegir en la página de demostración y copiar la URL que ve.
# Distintivo de esquina, solo la marca
GET https://polads.eu/badge/{PA-ID}
# Distintivo de esquina con su texto
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Franja de etiqueta siempre visible
GET https://polads.eu/badge/{PA-ID}?layout=labelQué hace cada parámetro y qué significa omitirlo
layout=label selecciona la franja. Si lo omite, se muestra el distintivo de esquina. variant=labelled hace que el distintivo cerrado muestre su texto. Si lo omite, solo aparece la marca. w y h declaran el espacio en el que se sitúa el distintivo y determinan cómo se adapta cuando hay poco sitio. Si los omite, el distintivo supone que dispone de espacio, lo cual es correcto para los formatos estándar.
hover=0 es para la demostración, no para su página
Fuerza la presentación sin puntero para que la demostración muestre la versión táctil en un navegador de escritorio. El distintivo real comprueba el dispositivo por sí mismo. Si fija este valor en el código, enviará la versión equivocada a todos los visitantes cuyo dispositivo no coincida.
El agente de escucha del cambio de tamaño es obligatorio
El distintivo de esquina se carga a 32 por 32 para tapar lo menos posible de la creatividad y, al abrirse, pide espacio a la página anfitriona. Sin el agente de escucha no puede abrirse en absoluto. La franja de etiqueta se adapta con más suavidad y solo se recorta en anchuras estrechas.
Disponible solo para un aviso publicado
El distintivo se sirve una vez que el aviso está confirmado, aprobado por el editor y ha pasado su fecha de inicio de publicación. Un PA-ID bajo embargo o sin aprobar responde 404 por diseño, no por un fallo.
Abrir la demostración interactiva y copiar el código de inserción
401 No autorizado
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Solicitud incorrecta
Se encontró el anuncio, pero su medio no es online. La respuesta devuelve el valor real del medio, por ejemplo print. Un PA-ID ausente o desconocido devuelve 404 en su lugar.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 No encontrado
{
"error": "Advertisement not found"
}429 Límite de solicitudes excedido
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Esta es la versión v1 de la API, y cada respuesta lo indica en una cabecera X-API-Version. Los cambios incompatibles se publican en una ruta nueva en lugar de modificar esta. Un punto final v1 no se desactivará sin una cabecera Deprecation enviada con al menos 90 días de antelación, conforme a la RFC 8594.
Especificación legible por máquina
El documento OpenAPI 3.1 completo se sirve en /api/docs. Dirija Postman, Swagger UI o un generador de clientes directamente a él en lugar de transcribir esta página.
https://polads.eu/api/docs