Documentación de la API de socios
API de datos de anuncios políticos para medios de comunicación y editores asociados
https://polads.eu/api/v1Todos los puntos de conexión requieren autenticación con un token Bearer de socio
GET /advertisement-full/{PAID}
1000 solicitudes por minuto
GET /advertisement/{PAID}
1000 solicitudes por minuto
El límite de solicitudes se aplica por token de socio en todos los puntos de conexión
Plan Pro, comprobado de nuevo en cada solicitud
La API de socios forma parte del plan Pro, tanto para las lecturas como para las escrituras. No existe ningún complemento de API que deba adquirirse por separado. El plan se comprueba en cada solicitud, en lugar de registrarse al crear el token, por lo que una suscripción vencida bloquea el acceso en la siguiente llamada con 403 PRO_PLAN_REQUIRED, y su renovación lo restablece con la misma inmediatez.
Ámbitos
Todos los tokens de socio pueden leer. Para comunicar métricas de interacción se necesita además el ámbito metrics:write. Los ámbitos se eligen al generar el token y no pueden modificarse después: para cambiarlos, revoque el token y genere uno nuevo.
Solo tokens de socio
Estos puntos de conexión rechazan un token SSP con 401, y el punto de conexión SSP rechaza un token de socio del mismo modo. Los dos niveles son credenciales distintas, no dos niveles de permiso sobre una misma credencial.
GET /advertisement/{PAID} resuelve el aviso 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 aquí, exactamente igual que en el registro. Lo mismo se aplica al punto de conexión SSP.
El punto de conexión del registro completo es deliberadamente distinto
GET /advertisement-full/{PAID} se limita a sus propios avisos, por lo que también responde para un aviso que aún no ha alcanzado su fecha de inicio. Usted es el editor que debe examinar ese aviso antes de su publicación, así que ocultárselo no tendría sentido.
/advertisement-full/{PAID}Limitado a sus propios avisos. El PA-ID de otro editor, un aviso autopublicado sin editor y un identificador inexistente devuelven el mismo 404, y la respuesta no los distingue.
⚠️ Advertencia: datos sensibles según el RGPD
Este punto de conexión devuelve TODOS los campos, incluidos correos electrónicos, números de teléfono y direcciones completas. Utilícelo únicamente si tiene una necesidad empresarial legítima y ha celebrado los acuerdos de tratamiento de datos adecuados.
curl -X GET "https://polads.eu/api/v1/advertisement-full/ABC12" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Campos del anunciante:
companyName, legalName, firstName, lastName, email, phone, streetAddress, postalCode, city, country
Campos de la campaña:
name, totalValue, medium, isOngoing, startDate, endDate
Anunciantes y responsables del tratamiento:
Todos los campos, incluidos correos electrónicos, teléfonos y direcciones completas
/advertisement/{PAID}/metricsEste punto de conexión requiere una clave con el ámbito Lectura y escritura. La API de socios está incluida en el plan Pro.
Solo puede comunicar métricas de avisos publicados a través de su propia cuenta.
El aviso pertenece a otro editor. No se registra nada.
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}'Información básica
Cumplimiento y financiación
Segmentación
Aspectos jurídicos y metadatos
// Get single ad
const response = await fetch('https://polads.eu/api/v1/advertisement/PAID-0000001');
const data = await response.json();401 INVALID_TOKEN
Ningún token activo coincide con la credencial Bearer, o el token ha sido revocado. Una cabecera Authorization ausente o mal formada también devuelve 401, pero solo el punto de conexión de métricas añade este código a esa respuesta. Un token SSP en un punto de conexión de socios recibe la misma respuesta.
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
El token es válido, pero su editor no tiene el plan Pro. Esto se comprueba antes que el ámbito, por lo que un token de solo lectura de un editor sin el plan Pro devuelve el error de plan y no el de ámbito.
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
El token es válido y tiene el plan Pro, pero le falta el ámbito metrics:write necesario para comunicar métricas.
PUT /advertisement/{PAID}/metrics{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}403 FORBIDDEN
El aviso pertenece a otro editor. No se registra nada.
PUT /advertisement/{PAID}/metrics{
"error": "This advertisement belongs to a different publisher.",
"code": "FORBIDDEN"
}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.
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
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.
PUT /advertisement/{PAID}/metrics{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}404 NOT_FOUND
Ningún aviso coincide con ese PA-ID, o todavía no es visible para usted. Consulte la sección anterior antes de suponer que el identificador es incorrecto.
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
Se ha superado el límite por token. La respuesta incluye las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y 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"
}Esta es la versión v1 de la API, y cada respuesta lo indica en la cabecera X-API-Version. Los cambios incompatibles se publican en una ruta nueva en lugar de modificar esta. Ningún punto de conexión v1 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. Apunte Postman, Swagger UI o un generador de clientes directamente a él en lugar de transcribir esta página.
https://polads.eu/api/docs