# API do sprawdzania dostępności: kontrole WCAG z własnych narzędzi
URL: https://pandus.online/pl/api-do-sprawdzania-dostepnosci-wcag
Updated: 2026-10-20

API Pandus do kontroli dostępności: dodawanie stron, uruchamianie kontroli WCAG 2.2 AA, raporty JSON i PDF, podpisane webhooki, użycie w CI i sprawdzanie localhost.

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](https://pandus.online/api/v1/openapi.yaml). Wyniki to **automatyczna kontrola, a nie pełny audyt**, i **nie są poradą prawną**.

Pracujesz z Claude Code, Cursorem lub VS Code? [Serwer MCP](https://pandus.online/pl/serwer-mcp-dostepnosc) daje Twojemu asystentowi AI te same dane: co naprawić najpierw, szczegóły każdego problemu i nowe kontrole, bez pisania wywołań API.

Każdy endpoint z parametrami, przykładami odpowiedzi, błędami i przykładami kodu w curl, JavaScript, PHP i Python opisuje [dokumentacja API](https://pandus.online/pl/docs/api).

## Co robi API

| Metoda i ścieżka                         | Co robi                                                                            | Uprawnienie |
| ---------------------------------------- | ---------------------------------------------------------------------------------- | ----------- |
| `GET /account`                           | Plan, limity i wykorzystanie zespołu                                               | read        |
| `GET /sites`                             | Lista stron zespołu                                                                | read        |
| `POST /sites`                            | Dodaje stronę; uruchamia jej pierwszą kontrolę, chyba że `scan` ma wartość `false` | write       |
| `GET /sites/{site}`                      | Jedna strona                                                                       | read        |
| `DELETE /sites/{site}`                   | Usuwa stronę wraz z kontrolami, raportami i zrzutami ekranu                        | write       |
| `GET /sites/{site}/scans`                | Kontrole strony w ramach historii planu, od najnowszej                             | read        |
| `POST /sites/{site}/scans`               | Uruchamia kontrolę teraz (obowiązują zasady planu)                                 | write       |
| `GET /scans/{scan}`                      | Status i podsumowanie kontroli                                                     | read        |
| `GET /scans/{scan}/report`               | Raport dla właściciela z zakończonej kontroli w JSON                               | read        |
| `GET /scans/{scan}/pdf`                  | Raport PDF z zakończonej kontroli                                                  | read        |
| `GET /scans/{scan}/evidence/{kind}/{id}` | Zrzut ekranu z raportu (`kind` to `page` lub `issue`)                              | read        |
| `GET /scans/{scan}/export`               | Problemy jako CSV, JSON, zgłoszenia GitHub lub import do Jira (płatne plany)       | read        |
| `GET /scans/{scan}/compare/{other}`      | Naprawione, nowe i nadal otwarte problemy między dwiema kontrolami strony          | read        |

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 **Asystenci AI i API** i wysyła jako token bearer:

```bash
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](https://pandus.online/pl/cennik).

## Dodanie strony i uruchomienie kontroli

```bash
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:

```bash
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:

```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](https://pandus.online/pl/testy-dostepnosci-playwright-axe-core) – 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](https://pandus.online/pl/rozszerzenie-do-sprawdzania-dostepnosci) 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](https://pandus.online/pl/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ł](https://pandus.online/pl/rules) oraz raport, który może przeczytać właściciel sklepu lub klient agencji. Dla strony na WordPressie jest też [wtyczka WordPress](https://pandus.online/pl/wtyczka-dostepnosci-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.

Q: Czy Pandus ma API do sprawdzania dostępności?
A: 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.

Q: Które plany obejmują API?
A: 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.

Q: Czy API może sprawdzić localhost lub serwer testowy?
A: 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.

Q: Jak zabezpieczone są webhooki?
A: 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ć.

Q: Czy wynik z API to audyt WCAG?
A: 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.
