API do sprawdzania dostępności: kontrole WCAG z własnych narzędzi

API Pandus daje te same automatyczne kontrole dostępności co panel klienta, ale z własnych narzędzi: skryptu wdrożenia, panelu agencji, systemu zgłoszeń. Sprawdza WCAG 2.2 poziomy A i AA silnikiem axe-core w prawdziwej przeglądarce, na wielu stronach serwisu, i zwraca wyniki z objaśnieniami prostym językiem w siedmiu językach raportu.

Wszystko na tej stronie pochodzi z naszej opublikowanej specyfikacji OpenAPI. Wyniki to automatyczna kontrola, a nie pełny audyt, i nie są poradą prawną.

Każdy endpoint z parametrami, przykładami odpowiedzi, błędami i przykładami kodu w curl, JavaScript, PHP i Python opisuje dokumentacja API.

Co robi API

Bazowy adres URL to https://pandus.online/api/v1. Raport i PDF przyjmują opcjonalny parametr lang: en, uk, de, pl, cs, ro lub ru. Bez niego używany jest język raportu strony.

Raport JSON zawiera grupy problemów z kartami reguł, przykłady, dotknięte strony, podsumowania według ważności, porównanie „było / stało” z poprzednią kontrolą oraz trend. Kontrola ma status queued, running, completed lub failed, a punkty końcowe raportu odpowiadają 409, dopóki nie zostanie ukończona.

Uwierzytelnianie i limity

Token tworzy się w panelu w sekcji API i webhooki i wysyła jako token bearer:

curl -H "Authorization: Bearer $PANDUS_TOKEN" \
     https://pandus.online/api/v1/sites

• Token należy do zespołu, a nie do osoby, więc działa dalej, gdy ktoś odchodzi.
• Uprawnienia: read obejmuje każde żądanie GET, write obejmuje dodawanie i usuwanie stron oraz uruchamianie kontroli. Do panelu podglądu wystarczy token tylko do odczytu.
• Limit zapytań: 60 żądań na minutę na token. Powyżej tego otrzymuje się HTTP 429 z nagłówkiem Retry-After.
• Limity planu obowiązują tak jak w panelu: liczba stron, liczba podstron w kontroli, historia i to, jak często można ręcznie uruchomić kontrolę. Żądanie przekraczające limit zwraca HTTP 422 z komunikatem.
• API wchodzi w skład planów Pro i Agency – zob. cennik.

Dodanie strony i uruchomienie kontroli

curl -X POST https://pandus.online/api/v1/sites \
     -H "Authorization: Bearer $PANDUS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"url": "shop.example", "report_locale": "pl", "platform": "shopify", "tags": ["client-a"]}'

url i report_locale są wymagane. platform (shopify, woocommerce, prestashop, shoptet lub other) pozwala raportowi pokazać instrukcje naprawy dla tej platformy; tags pomagają agencjom sortować strony według klienta. Odpowiedź to 201 z nową stroną, a jej pierwsza kontrola trafia do kolejki.

Aby sprawdzić ponownie później, np. po wydaniu zmian:

curl -X POST https://pandus.online/api/v1/sites/$SITE_ID/scans \
     -H "Authorization: Bearer $PANDUS_TOKEN"

Odpowiedź to 202 z kontrolą w kolejce. Potem można odpytywać GET /scans/{scan} albo, lepiej, poczekać na webhook.

Webhooki

Wysyłane są dwa zdarzenia: scan.completed i issues.new. Każde to JSON POST w postaci {id, type, created_at, data: {scan, site, new_issues}} z następującymi nagłówkami:

• Pandus-Event – typ zdarzenia;
• Pandus-Delivery – identyfikator dostarczenia;
• Pandus-Signature: t=<unix>,v1=<hex> – v1 to HMAC-SHA256 z "<t>.<surowa treść>" sekretem Państwa endpointu.

Należy odpowiedzieć statusem 2xx w ciągu 10 sekund. Nieudane dostarczenia są ponawiane przez około dobę; w panelu można wysłać zdarzenie testowe i ręcznie ponowić dostarczenie. Minimalna weryfikacja w Node.js:

import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
    const parts = Object.fromEntries(
        header.split(',').map((p) => p.split('=')),
    );
    const expected = crypto
        .createHmac('sha256', secret)
        .update(`${parts.t}.${rawBody}`)
        .digest('hex');
    const given = Buffer.from(parts.v1 ?? '');
    return (
        given.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(expected), given)
    );
}

Należy użyć surowej treści żądania, a nie ponownie zserializowanego obiektu JSON, i odrzucać stare znaczniki czasu, aby zapobiec powtórzeniom.

Użycie API w CI

API sprawdza publiczny serwis, więc pasuje po wdrożeniu na produkcję lub na publicznie dostępny podgląd:

1. Państwa pipeline wdraża zmiany.
2. Zadanie wywołuje POST /sites/{site}/scans.
3. Państwa endpoint otrzymuje scan.completed lub issues.new, pobiera GET /scans/{scan}/report i otwiera zgłoszenie albo wysyła wiadomość na czat.

Nie warto kazać scaleniu zmian czekać na kontrolę całego serwisu; cały serwis może to chwilę potrwać. Do szybkiej informacji zwrotnej przy każdym pull requeście warto uruchamiać axe-core we własnych testach – zob. testy dostępności z Playwright – a Pandus niech co tydzień i po wydaniach pilnuje serwisu produkcyjnego.

Localhost, środowisko testowe i strony za logowaniem

Nasz skaner otwiera tylko adresy publiczne. Blokuje sieci prywatne i lokalne, w tym localhost, przed każdym przekierowaniem i po nim – to środek bezpieczeństwa, a nie luka, którą planujemy usunąć. Dla wszystkiego, co nie jest publiczne:

• Rozszerzenie do przeglądarki dla Chrome, Edge i Firefox sprawdza stronę tak, jak pokazuje ją przeglądarka: lokalny serwer deweloperski, środowisko testowe chronione hasłem, koszyk, zamówienie, konto klienta. Wynik kontroli można zapisać przy stronie w Pandus.
• Własne testy Playwright z @axe-core/playwright docierają wszędzie tam, dokąd dociera Państwa CI.
• Przed założeniem konta można wypróbować darmowy WCAG checker na dowolnej stronie publicznej.

Czego API nie robi

Nie przeprowadza audytu ręcznego, nie „naprawia” strony skryptem i nie rozstrzyga, czy dotyczy Państwa jakieś prawo. Zwraca automatyczne ustalenia z odniesieniami do WCAG i EN 301 549 z naszej biblioteki reguł oraz raport, który może przeczytać właściciel sklepu lub klient agencji. Dla strony na WordPressie jest też wtyczka WordPress, która używa osobnego tokenu powiązanego ze stroną.

Najczęstsze pytania

Czy Pandus ma API do sprawdzania dostępności?

Tak. REST API v1 pozwala wyświetlać i dodawać strony, uruchamiać kontrole, odczytywać ich status, pobierać raport w JSON lub PDF oraz zrzuty ekranu. Webhooki informują, kiedy kontrola się zakończyła i kiedy pojawiły się nowe problemy.

Które plany obejmują API?

Plan Pro i plany Agency. W planie Free i przy raporcie ekspresowym API nie jest dostępne; tokeny zespołu, który przechodzi na taki plan, przestają działać, dopóki plan znów nie obejmie API.

Czy API może sprawdzić localhost lub serwer testowy?

Nie. Nasz skaner otwiera tylko adresy publiczne i ze względów bezpieczeństwa blokuje sieci prywatne i lokalne. Dla localhost, środowiska testowego i stron za logowaniem służy rozszerzenie do przeglądarki albo axe-core uruchamiany we własnych testach Playwright.

Jak zabezpieczone są webhooki?

Każde wywołanie zawiera nagłówek Pandus-Signature ze znacznikiem czasu i HMAC-SHA256 z tego znacznika i surowej treści, utworzonym sekretem Państwa endpointu. Przed zaufaniem danym należy go porównać.

Czy wynik z API to audyt WCAG?

Nie. API zwraca wyniki automatycznej kontroli, a nie pełnego audytu, i nie jest poradą prawną. Wiele kryteriów WCAG nadal wymaga przeglądu ręcznego.