Documentation de l'API SSP
API de plateforme côté offre pour les plateformes publicitaires programmatiques
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10 000 requêtes par minute
Limite de débit appliquée par jeton SSP
PUT /online-advertisement/{PAID}/metrics
1 000 requêtes par minute
Comptabilisées par jeton SSP, séparément du point de terminaison des étiquettes, si bien que la déclaration des mesures d’engagement n’entame jamais votre quota de requêtes d’étiquettes
/online-advertisement/{PAID}📊 Format d'étiquette compact
Ce point de terminaison renvoie une étiquette de transparence compacte et conforme au droit de l'UE, destinée à être affichée à côté des publicités en ligne. Fonctionne uniquement pour les publicités avec medium = "online".
Exemple de requête
curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
-H "Authorization: Bearer YOUR_SSP_TOKEN" \
-H "Accept: application/json"Exemple de réponse
{
"text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
"link": "https://polads.eu/ABC12",
"PAID": "ABC12"
}Champs de la réponse
Exemple d'utilisation
Affichez l'étiquette sur votre plateforme :
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsVotre jeton SSP doit disposer du droit metrics:write. Un administrateur l’active sur le jeton que vous utilisez déjà, sans délivrer de nouveau jeton.
Envoyez les totaux cumulés depuis la publication de l’avis, jamais la variation depuis votre dernier envoi. Chaque envoi remplace les chiffres précédents : renvoyer les mêmes totaux ne change donc rien.
Vous pouvez déclarer les chiffres de n’importe quel avis publié, quel que soit l’éditeur dont il relève. Ces chiffres apparaissent sur l’avis de transparence public correspondant, avec la date de leur dernière déclaration.
Exemple de requête
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}'Champs de la requête
Les deux champs sont obligatoires, chacun étant un nombre entier compris entre 0 et 2147483647.
Exemple de réponse
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Réponses d’erreur de ce point de terminaison
401 INVALID_TOKEN
L’en-tête Authorization est absent, ou le jeton est inconnu, révoqué ou il s’agit d’un jeton partenaire. Dans les deux cas, la réponse porte le code 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
Le jeton est valide, mais le droit metrics:write ne lui a pas été accordé. Demandez à votre administrateur de l’activer.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Aucun avis publié ne correspond à ce PA-ID. Comme sur le point de terminaison des étiquettes, un avis que son éditeur n’a pas encore validé, ou dont la date de début de publication est encore à venir, renvoie lui aussi 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
L’annonce ne relève pas du champ pour lequel les chiffres d’engagement sont définis. La note 15 de l’annexe II vise une annonce en ligne ou native ayant eu recours à des techniques de ciblage ou de diffusion d’annonces publicitaires et dont la diffusion a commencé. Rien n’est écrit.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
Le corps de la requête n’est pas du JSON valide, ou les deux compteurs sont absents, négatifs ou non entiers. La réponse indique ce qui a échoué.
{
"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
La limite par jeton a été dépassée. La réponse contient les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Format de l'en-tête
Authorization: Bearer YOUR_SSP_TOKENFormat du jeton
Chaîne hexadécimale de 64 caractères (entropie de 256 bits)
Gestion des jetons
Les jetons SSP sont gérés uniquement par les administrateurs système. Contactez votre administrateur pour obtenir un jeton.
Aucune formule d’abonnement ne s’applique
Un jeton SSP est délivré à un intégrateur et non à un éditeur : il n’est rattaché à aucun compte éditeur et aucune formule n’est à vérifier. Contrairement à l’API partenaire, rien ici ne dépend d’un abonnement. Un jeton partenaire est rejeté sur ce point de terminaison avec le code 401, et un jeton SSP est rejeté de la même façon sur les points de terminaison partenaires.
Quand le point de terminaison renvoie 404
L’avis est résolu selon la même règle de visibilité que le registre public. Un avis qui n’est pas encore confirmé, que son éditeur n’a pas encore validé ou dont la date de début de publication est encore à venir renvoie 404. Un 404 ne prouve donc pas qu’un PA-ID est erroné.
Le point de terminaison ci-dessus renvoie le TEXTE de l’étiquette sur une ligne, pour une étiquette que votre propre plateforme affiche. La pastille renvoie un avis interactif prêt à l’affichage, que vous placez à côté de la publicité dans un cadre intégré. Les deux décrivent le même avis de transparence.
Une URL par version
Les commandes de la démonstration correspondent une à une à ces paramètres : vous pouvez choisir sur la page de démonstration et copier l'URL affichée.
# Pastille d'angle, marque seule
GET https://polads.eu/badge/{PA-ID}
# Pastille d'angle avec sa mention
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Bandeau de mention toujours visible
GET https://polads.eu/badge/{PA-ID}?layout=labelCe que fait chaque paramètre, et ce que signifie son absence
layout=label sélectionne le bandeau. Sans ce paramètre, vous obtenez la pastille d'angle. variant=labelled affiche la mention sur la pastille fermée. Sans ce paramètre, seule la marque s'affiche. w et h déclarent l'emplacement qui accueille la pastille et déterminent son adaptation quand la place manque. Sans eux, la pastille considère qu'elle dispose de la place nécessaire, ce qui convient aux formats standard.
hover=0 est réservé à la démonstration, pas à votre page
Ce paramètre force l'affichage sans survol afin que la démonstration puisse montrer la version tactile dans un navigateur de bureau. La vraie pastille détecte elle-même le type d'appareil. Si vous figez cette valeur, vous envoyez la mauvaise version à chaque visiteur dont l'appareil ne correspond pas.
L’écouteur de redimensionnement est obligatoire
La pastille d'angle se charge en 32 sur 32 pour couvrir le moins possible de la création, puis demande de la place à la page hôte lorsqu’elle s’ouvre. Sans l’écouteur, elle ne peut pas s’ouvrir du tout. Le bandeau de mention se dégrade plus progressivement et n’est tronqué qu’aux faibles largeurs.
Disponible uniquement pour un avis publié
La pastille est servie une fois l’avis confirmé, validé par l’éditeur et sa date de début de publication passée. Un PA-ID sous embargo ou non validé renvoie 404 par conception, et non par erreur.
Ouvrir la démonstration interactive et copier le code d’intégration
401 Non autorisé
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Requête incorrecte
L’annonce a été trouvée, mais son support n’est pas online. La réponse renvoie la valeur réelle du support, par exemple print. Un PA-ID absent ou inconnu renvoie 404 à la place.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Introuvable
{
"error": "Advertisement not found"
}429 Limite de débit dépassée
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Il s’agit de la version d’API v1, et chaque réponse l’indique dans un en-tête X-API-Version. Les changements incompatibles sont publiés sous un nouveau chemin plutôt que de modifier celui-ci. Un point de terminaison v1 ne sera pas désactivé sans un en-tête Deprecation envoyé au moins 90 jours à l’avance, conformément à la RFC 8594.
Spécification lisible par machine
Le document OpenAPI 3.1 complet est servi sur /api/docs. Pointez Postman, Swagger UI ou un générateur de client directement dessus plutôt que de recopier cette page.
https://polads.eu/api/docs