Dokumentacja API SSP

API platformy po stronie podaży dla platform reklamy programatycznej

API v1

Wymagany token SSP typu Bearer

Wysoka przepustowość

Podstawowy adres URL

https://polads.eu/api/v1

Limit liczby żądań

Wysoka przepustowość dla platform reklamy programatycznej

GET /online-advertisement/{PAID}

10 000 żądań na minutę

Limit liczby żądań obowiązuje osobno dla każdego tokena SSP

PUT /online-advertisement/{PAID}/metrics

1000 żądań na minutę

Liczone osobno dla każdego tokena SSP, niezależnie od punktu końcowego etykiety, więc zgłaszanie wskaźników nigdy nie zużywa Twojego limitu żądań etykiet

GET

/online-advertisement/{PAID}

Pobierz sformatowaną etykietę przejrzystości dla reklam internetowych

📊 Kompaktowy format etykiety

Ten punkt końcowy zwraca kompaktową etykietę przejrzystości zgodną z przepisami UE, odpowiednią do wyświetlania obok reklam internetowych. Działa tylko w przypadku reklam z medium = „online”.

Token Bearer SSP

PA-ID

Przykładowe żądanie

curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
  -H "Authorization: Bearer YOUR_SSP_TOKEN" \
  -H "Accept: application/json"

Przykład odpowiedzi

{
  "text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
  "link": "https://polads.eu/ABC12",
  "PAID": "ABC12"
}

Pola odpowiedzi

text

string

Sformatowany tekst etykiety

link

string

Adres URL strony przejrzystości

PAID

string

Identyfikator reklamy politycznej

Przykład użycia

Wyświetl etykietę na swojej platformie:

<a href="[link]" target="_blank" rel="noopener">
  [text]
</a>

Zgłoś wskaźniki zaangażowania

PUT

/online-advertisement/{PAID}/metrics

Zgłoś skumulowaną liczbę wyświetleń i interakcji opublikowanego ogłoszenia dostarczonego przez Twoją platformę

Twój token SSP wymaga uprawnienia metrics:write. Administrator włącza je dla tokena, którego już używasz, więc nowy token nie jest wydawany.

Przesyłaj sumy narastające od chwili opublikowania ogłoszenia, a nigdy przyrost od Twojej ostatniej wysyłki. Każda wysyłka zastępuje wcześniejsze dane, więc ponowne wysłanie tych samych sum niczego nie zmienia.

Możesz zgłaszać dane dowolnego opublikowanego ogłoszenia, niezależnie od tego, do którego wydawcy należy. Dane pojawiają się w jego publicznym ogłoszeniu o przejrzystości wraz z datą ostatniego zgłoszenia.

Przykładowe żądanie

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}'

Pola żądania

viewsCount

integer

Liczba wyświetleń reklamy od chwili publikacji

engagementsCount

integer

Liczba interakcji z reklamą w postaci kliknięć, polubień i komentarzy od chwili publikacji

Oba pola są wymagane, a każde musi być liczbą całkowitą od 0 do 2147483647.

Przykład odpowiedzi

{
  "viewsCount": 15000,
  "engagementsCount": 320,
  "engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}

Odpowiedzi z błędem zwracane przez ten punkt końcowy

401 INVALID_TOKEN

Brakuje nagłówka Authorization albo token jest nieznany, unieważniony lub jest tokenem partnera. W obu przypadkach zwracany jest kod 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

Token jest ważny, ale nie nadano mu uprawnienia metrics:write. Poproś administratora o jego włączenie.

{
  "error": "This token is not authorised to write metrics. Required scope: metrics:write.",
  "code": "INSUFFICIENT_SCOPE"
}

404 NOT_FOUND

Żadne opublikowane ogłoszenie nie odpowiada temu PA-ID. Tak jak w przypadku punktu końcowego etykiety, kod 404 zwracany jest również dla ogłoszenia, którego wydawca jeszcze nie zatwierdził albo którego data rozpoczęcia publikacji jeszcze nie nadeszła.

{
  "error": "Advertisement not found",
  "code": "NOT_FOUND"
}

409 METRICS_NOT_APPLICABLE

Ogłoszenie wykracza poza zakres, dla którego określono wskaźniki zaangażowania. Przypis 15 do załącznika II obejmuje ogłoszenie dotyczące reklamy internetowej lub natywnej, w której zastosowano techniki targetowania lub techniki dostarczania reklamy i której emisja już się rozpoczęła. Nic nie zostaje zapisane.

{
  "error": "Engagement metrics do not apply to this notice",
  "code": "METRICS_NOT_APPLICABLE"
}

400 INVALID_METRICS

Treść żądania nie jest poprawnym dokumentem JSON albo brakuje obu wartości liczbowych, są one ujemne lub nie są liczbami całkowitymi. Odpowiedź wskazuje, które warunki nie zostały spełnione.

{
  "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

Przekroczono limit żądań dla tokena. Ta odpowiedź zawiera nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "limit": 1000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Uwierzytelnianie

Format nagłówka

Authorization: Bearer YOUR_SSP_TOKEN

Format tokena

64-znakowy ciąg szesnastkowy (entropia 256-bitowa)

Zarządzanie tokenami

Tokenami SSP zarządzają wyłącznie administratorzy systemu. Skontaktuj się z administratorem, aby uzyskać token.

Wymagania dostępu

Nie obowiązuje żaden plan subskrypcji

Token SSP jest wydawany integratorowi, a nie wydawcy, więc nie jest powiązany z żadnym kontem wydawcy i nie ma planu do sprawdzenia. W odróżnieniu od API partnerskiego nic tutaj nie zależy od subskrypcji. Token partnera jest odrzucany przez ten punkt końcowy z kodem 401, a token SSP jest w ten sam sposób odrzucany przez punkty końcowe partnera.

Kiedy punkt końcowy zwraca 404

Dostępność ogłoszenia jest ustalana według tej samej reguły widoczności co w rejestrze publicznym. Dla ogłoszenia, które nie zostało jeszcze potwierdzone, którego wydawca jeszcze nie zatwierdził albo którego data rozpoczęcia publikacji jeszcze nie nadeszła, zwracany jest kod 404. Kod 404 nie dowodzi więc, że PA-ID jest błędny.

Oznaczenie przejrzystości

Te same informacje, przedstawione dla wyświetlanej reklamy

Powyższy punkt końcowy zwraca jednowierszowy TEKST etykiety, którą Twoja platforma wyświetla samodzielnie. Oznaczenie zwraca gotowe, interaktywne ogłoszenie, które umieszczasz obok reklamy w osadzonej ramce. Oba opisują to samo ogłoszenie o przejrzystości.

Jeden adres URL dla każdej wersji

Elementy sterujące na stronie demonstracyjnej odpowiadają tym parametrom jeden do jednego, więc możesz dokonać wyboru na stronie demonstracyjnej i skopiować widoczny adres URL.

# Oznaczenie narożne, sam znak
GET https://polads.eu/badge/{PA-ID}

# Oznaczenie narożne z napisem
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Stale widoczny pasek etykiety
GET https://polads.eu/badge/{PA-ID}?layout=label

Co robi każdy parametr i co oznacza jego pominięcie

layout=label wybiera pasek. Bez niego wyświetla się oznaczenie narożne. variant=labelled sprawia, że zamknięte oznaczenie pokazuje swój napis. Bez niego wyświetla się sam znak. Parametry w i h określają obszar, w którym znajduje się oznaczenie, i decydują, jak dostosowuje się ono przy braku miejsca. Po ich pominięciu oznaczenie zakłada, że ma wystarczająco miejsca, co jest właściwe dla standardowych formatów.

hover=0 służy do wersji demonstracyjnej, nie do Twojej strony

Wymusza układ bez obsługi najechania kursorem, aby strona demonstracyjna mogła pokazać wersję dotykową w przeglądarce na komputerze. Prawdziwe oznaczenie samo sprawdza urządzenie. Jeśli ustawisz ten parametr na stałe, wyślesz niewłaściwą wersję każdemu odwiedzającemu, którego urządzenie działa inaczej.

Wymagana jest obsługa komunikatu o zmianie rozmiaru

Oznaczenie narożne ładuje się w rozmiarze 32 na 32, aby zasłaniać jak najmniej kreacji, a przy otwarciu prosi stronę nadrzędną o więcej miejsca. Bez obsługi tego komunikatu w ogóle nie może się otworzyć. Pasek etykiety dostosowuje się łagodniej i jest przycinany tylko przy małych szerokościach.

Dostępne tylko dla opublikowanego ogłoszenia

Oznaczenie jest udostępniane, gdy ogłoszenie zostało potwierdzone, zatwierdzone przez wydawcę i minęła data rozpoczęcia jego publikacji. Zapytanie o PA-ID objęty embargiem lub niezatwierdzony celowo zwraca kod 404, co nie oznacza błędu.

Otwórz interaktywną wersję demonstracyjną i skopiuj kod do osadzenia

Odpowiedzi z błędem

Każdy błąd zwraca treść JSON z komunikatem o błędzie, a każda odpowiedź zawiera nagłówek X-API-Version. Punkt końcowy etykiety nie zwraca pola z kodem odczytywalnym maszynowo, dlatego rozpoznawaj jego błędy po statusie HTTP, a nie po treści odpowiedzi. Błędy punktu końcowego wskaźników zawierają natomiast kod i są opisane powyżej, przy tym punkcie końcowym.

401 Nieautoryzowane

{
  "error": "Invalid or revoked SSP API token."
}

{
  "error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}

400 Nieprawidłowe żądanie

Reklama została znaleziona, ale jej medium nie jest online. Odpowiedź zwraca rzeczywistą wartość medium, na przykład print. Brakujący lub nieznany PA-ID zwraca zamiast tego 404.

{
  "error": "This endpoint is only for online advertisements",
  "medium": "print"
}

404 Nie znaleziono

{
  "error": "Advertisement not found"
}

429 Przekroczono limit żądań

{
  "error": "Rate limit exceeded",
  "limit": 10000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Wersjonowanie i wycofywanie

To jest wersja v1 API, co każda odpowiedź potwierdza w nagłówku X-API-Version. Zmiany naruszające zgodność są wprowadzane pod nową ścieżką, a ta pozostaje bez zmian. Punkt końcowy v1 nie zostanie wyłączony bez nagłówka Deprecation wysłanego co najmniej 90 dni wcześniej, zgodnie z RFC 8594.

Specyfikacja odczytywalna maszynowo

Pełny dokument OpenAPI 3.1 jest dostępny pod adresem /api/docs. Wskaż go bezpośrednio w Postmanie, Swagger UI lub generatorze klienta, zamiast przepisywać tę stronę.

https://polads.eu/api/docs

Integrujesz się jako partner medialny lub wydawca? Przeczytaj dokumentację API partnerskiego

Dokumentacja API SSP

API platformy po stronie podaży dla platform reklamy programatycznej

API v1

Wymagany token SSP typu Bearer

Wysoka przepustowość

Podstawowy adres URL

https://polads.eu/api/v1

Limit liczby żądań

Wysoka przepustowość dla platform reklamy programatycznej

GET /online-advertisement/{PAID}

10 000 żądań na minutę

Limit liczby żądań obowiązuje osobno dla każdego tokena SSP

PUT /online-advertisement/{PAID}/metrics

1000 żądań na minutę

Liczone osobno dla każdego tokena SSP, niezależnie od punktu końcowego etykiety, więc zgłaszanie wskaźników nigdy nie zużywa Twojego limitu żądań etykiet

GET

/online-advertisement/{PAID}

Pobierz sformatowaną etykietę przejrzystości dla reklam internetowych

📊 Kompaktowy format etykiety

Token Bearer SSP

PA-ID

Przykładowe żądanie

curl -X GET "https://polads.eu/api/v1/online-advertisement/ABC12" \
  -H "Authorization: Bearer YOUR_SSP_TOKEN" \
  -H "Accept: application/json"

Przykład odpowiedzi

{
  "text": "Politisk Reklame - ACME Corp - Folketingsvalg - polads.eu/ABC12",
  "link": "https://polads.eu/ABC12",
  "PAID": "ABC12"
}

Pola odpowiedzi

text

string

Sformatowany tekst etykiety

link

string

Adres URL strony przejrzystości

PAID

string

Identyfikator reklamy politycznej

Przykład użycia

Wyświetl etykietę na swojej platformie:

<a href="[link]" target="_blank" rel="noopener">
  [text]
</a>

Zgłoś wskaźniki zaangażowania

PUT

/online-advertisement/{PAID}/metrics

Zgłoś skumulowaną liczbę wyświetleń i interakcji opublikowanego ogłoszenia dostarczonego przez Twoją platformę

Twój token SSP wymaga uprawnienia metrics:write. Administrator włącza je dla tokena, którego już używasz, więc nowy token nie jest wydawany.

Przykładowe żądanie

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}'

Pola żądania

viewsCount

integer

Liczba wyświetleń reklamy od chwili publikacji

engagementsCount

integer

Liczba interakcji z reklamą w postaci kliknięć, polubień i komentarzy od chwili publikacji

Oba pola są wymagane, a każde musi być liczbą całkowitą od 0 do 2147483647.

Przykład odpowiedzi

{
  "viewsCount": 15000,
  "engagementsCount": 320,
  "engagementMetricsUpdatedAt": "2026-10-12T08:30:00.000Z"
}

Odpowiedzi z błędem zwracane przez ten punkt końcowy

401 INVALID_TOKEN

Brakuje nagłówka Authorization albo token jest nieznany, unieważniony lub jest tokenem partnera. W obu przypadkach zwracany jest kod 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

Token jest ważny, ale nie nadano mu uprawnienia metrics:write. Poproś administratora o jego włączenie.

{
  "error": "This token is not authorised to write metrics. Required scope: metrics:write.",
  "code": "INSUFFICIENT_SCOPE"
}

404 NOT_FOUND

{
  "error": "Advertisement not found",
  "code": "NOT_FOUND"
}

409 METRICS_NOT_APPLICABLE

{
  "error": "Engagement metrics do not apply to this notice",
  "code": "METRICS_NOT_APPLICABLE"
}

400 INVALID_METRICS

{
  "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

Przekroczono limit żądań dla tokena. Ta odpowiedź zawiera nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "limit": 1000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Uwierzytelnianie

Format nagłówka

Authorization: Bearer YOUR_SSP_TOKEN

Format tokena

64-znakowy ciąg szesnastkowy (entropia 256-bitowa)

Zarządzanie tokenami

Tokenami SSP zarządzają wyłącznie administratorzy systemu. Skontaktuj się z administratorem, aby uzyskać token.

Wymagania dostępu

Nie obowiązuje żaden plan subskrypcji

Kiedy punkt końcowy zwraca 404

Oznaczenie przejrzystości

Te same informacje, przedstawione dla wyświetlanej reklamy

Jeden adres URL dla każdej wersji

Elementy sterujące na stronie demonstracyjnej odpowiadają tym parametrom jeden do jednego, więc możesz dokonać wyboru na stronie demonstracyjnej i skopiować widoczny adres URL.

# Oznaczenie narożne, sam znak
GET https://polads.eu/badge/{PA-ID}

# Oznaczenie narożne z napisem
GET https://polads.eu/badge/{PA-ID}?variant=labelled

# Stale widoczny pasek etykiety
GET https://polads.eu/badge/{PA-ID}?layout=label

Co robi każdy parametr i co oznacza jego pominięcie

hover=0 służy do wersji demonstracyjnej, nie do Twojej strony

Wymagana jest obsługa komunikatu o zmianie rozmiaru

Dostępne tylko dla opublikowanego ogłoszenia

Otwórz interaktywną wersję demonstracyjną i skopiuj kod do osadzenia

Odpowiedzi z błędem

401 Nieautoryzowane

{
  "error": "Invalid or revoked SSP API token."
}

{
  "error": "Missing or invalid Authorization header. Expected: Bearer <token>"
}

400 Nieprawidłowe żądanie

Reklama została znaleziona, ale jej medium nie jest online. Odpowiedź zwraca rzeczywistą wartość medium, na przykład print. Brakujący lub nieznany PA-ID zwraca zamiast tego 404.

{
  "error": "This endpoint is only for online advertisements",
  "medium": "print"
}

404 Nie znaleziono

{
  "error": "Advertisement not found"
}

429 Przekroczono limit żądań

{
  "error": "Rate limit exceeded",
  "limit": 10000,
  "remaining": 0,
  "reset": "2026-05-14T15:14:00.000Z"
}

Wersjonowanie i wycofywanie

Specyfikacja odczytywalna maszynowo

Pełny dokument OpenAPI 3.1 jest dostępny pod adresem /api/docs. Wskaż go bezpośrednio w Postmanie, Swagger UI lub generatorze klienta, zamiast przepisywać tę stronę.

https://polads.eu/api/docs

Integrujesz się jako partner medialny lub wydawca? Przeczytaj dokumentację API partnerskiego