Документация за SSP API
API на платформата от страната на предлагането (SSP) за програматични рекламни платформи
https://polads.eu/api/v1GET /online-advertisement/{PAID}
10 000 заявки в минута
Ограничението се прилага поотделно за всеки SSP токен
PUT /online-advertisement/{PAID}/metrics
1000 заявки в минута
Заявките се отчитат за всеки SSP токен поотделно и независимо от крайната точка за етикета, така че докладването на показатели никога не изразходва заявките ви за етикети
/online-advertisement/{PAID}📊 Компактен формат на етикета
Тази крайна точка връща компактен етикет за прозрачност в съответствие с правото на ЕС, подходящ за показване до онлайн реклами. Работи само за реклами, чийто носител е medium = "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"
}Полета на отговора
Пример за използване
Покажете етикета на вашата платформа:
<a href="[link]" target="_blank" rel="noopener">
[text]
</a>/online-advertisement/{PAID}/metricsВашият SSP токен трябва да има разрешението metrics:write. Администратор го включва за токена, който вече използвате, така че не се издава нов токен.
Изпращайте натрупаните общи стойности от публикуването на обявлението насам, а никога промяната след последното ви изпращане. Всяко изпращане заменя предходните стойности, така че повторното изпращане на същите общи стойности не променя нищо.
Можете да докладвате за всяко публикувано обявление, независимо на кой издател принадлежи. Данните се показват в публичното му обявление за прозрачност заедно с датата, на която са докладвани за последно.
Примерна заявка
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}'Полета на заявката
И двете полета са задължителни, като всяко е цяло число от 0 до 2147483647.
Пример за отговор
{
"viewsCount": 15000,
"engagementsCount": 320,
"engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}Отговори при грешка от тази крайна точка
401 INVALID_TOKEN
Заглавката Authorization липсва или токенът е непознат, отменен или е партньорски токен. И в двата случая отговорът съдържа кода 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
Токенът е валиден, но не му е дадено разрешението metrics:write. Помолете вашия администратор да го включи.
{
"error": "This token is not authorised to write metrics. Required scope: metrics:write.",
"code": "INSUFFICIENT_SCOPE"
}404 NOT_FOUND
Няма публикувано обявление, което да съответства на този PA-ID. Както при крайната точка за етикета, обявление, което издателят му още не е одобрил или чиято начална дата на публикуване е още в бъдещето, също връща 404.
{
"error": "Advertisement not found",
"code": "NOT_FOUND"
}409 METRICS_NOT_APPLICABLE
Обявлението е извън обхвата, за който са определени показателите за ангажираност. Бележка 15 от приложение II обхваща онлайн или нативно обявление, при което са използвани техники за таргетиране или техники за доставяне на реклами и което вече е започнало да се показва. Нищо не се записва.
{
"error": "Engagement metrics do not apply to this notice",
"code": "METRICS_NOT_APPLICABLE"
}400 INVALID_METRICS
Тялото на заявката не е валиден JSON или двете числови стойности липсват, са отрицателни или не са цели числа. Отговорът посочва какво не е преминало проверката.
{
"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
Ограничението за токена е надвишено. Отговорът съдържа заглавките X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"limit": 1000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Формат на заглавката
Authorization: Bearer YOUR_SSP_TOKENФормат на токена
64-знаков шестнадесетичен низ (256-битова ентропия)
Управление на токени
SSP токените се управляват само от системни администратори. Свържете се с вашия администратор, за да получите токен.
Не се прилага абонаментен план
SSP токен се издава на интегратор, а не на издател, затова не е свързан с издателски профил и няма план за проверка. За разлика от партньорския API тук нищо не зависи от абонамент. Партньорски токен се отхвърля на тази крайна точка с код 401, а SSP токен се отхвърля по същия начин на партньорските крайни точки.
Кога крайната точка връща 404
Обявлението се извлича по същото правило за видимост, което важи за публичния регистър. Обявление, което още не е потвърдено, което издателят му още не е одобрил или чиято начална дата на публикуване е още в бъдещето, връща 404. Затова кодът 404 не доказва, че PA-ID е грешен.
Горната крайна точка връща едноредовия ТЕКСТ на етикета, за етикет, който изобразява вашата собствена платформа. Значката връща готово интерактивно обявление, което поставяте до рекламата като вградена рамка (iframe). И двете описват едно и също обявление за прозрачност.
По един URL адрес за всяка версия
Бутоните в демонстрацията съответстват едно към едно на тези параметри, така че можете да изберете на демонстрационната страница и да копирате показания URL адрес.
# Ъглова значка, само знакът
GET https://polads.eu/badge/{PA-ID}
# Ъглова значка с надпис
GET https://polads.eu/badge/{PA-ID}?variant=labelled
# Постоянно видима лента с обозначение
GET https://polads.eu/badge/{PA-ID}?layout=labelКакво прави всеки параметър и какво означава да го пропуснете
layout=label избира лентата. Без него се показва ъгловата значка. variant=labelled показва надписа върху затворената значка. Без него остава само знакът. w и h определят мястото, в което стои значката, и избират как тя се приспособява при малко място. Ако ги пропуснете, значката приема, че има достатъчно място, което е правилно за стандартните формати.
hover=0 е за демонстрацията, а не за вашата страница
Той налага оформлението без задържане на курсора, за да може демонстрацията да покаже версията за сензорни екрани в настолен браузър. Истинската значка сама проверява устройството. Ако фиксирате стойността, ще изпращате грешната версия на всеки посетител, чието устройство не отговаря на нея.
Слушателят за преоразмеряване е задължителен
Ъгловата значка се зарежда в размер 32 на 32, за да покрива възможно най-малко от рекламното съдържание, и при отваряне иска място от страницата домакин. Без слушателя тя изобщо не може да се отвори. Лентата с обозначение се приспособява по-плавно и се отрязва само при малка ширина.
Достъпно само за публикувано обявление
Значката се предоставя, след като обявлението е потвърдено, одобрено от издателя и началната му дата на публикуване е настъпила. PA-ID под ембарго или без одобрение връща 404 умишлено, а не поради грешка.
Отворете интерактивната демонстрация и копирайте кода за вграждане
401 Неразрешено
{
"error": "Invalid or revoked SSP API token."
}{
"error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}400 Невалидна заявка
Обявлението е намерено, но носителят му не е online. Отговорът връща действителната стойност на носителя, например print. Липсващ или непознат PA-ID връща 404.
{
"error": "This endpoint is only for online advertisements",
"medium": "print"
}404 Не е намерено
{
"error": "Advertisement not found"
}429 Превишено ограничение на скоростта
{
"error": "Rate limit exceeded",
"limit": 10000,
"remaining": 0,
"reset": "2026-05-14T15:14:00.000Z"
}Това е версия v1 на API и всеки отговор го посочва в заглавка X-API-Version. Несъвместимите промени се публикуват на нов път, вместо да променят този. Крайна точка v1 няма да бъде изключена без заглавка Deprecation поне 90 дни предварително, съгласно RFC 8594.
Машинно четима спецификация
Пълният документ OpenAPI 3.1 е достъпен на /api/docs. Насочете Postman, Swagger UI или генератор на клиенти директно към него, вместо да преписвате тази страница.
https://polads.eu/api/docs