API pro kontrolu přístupnosti: kontroly WCAG z vašich vlastních nástrojů

Pandus API vám dává stejné automatické kontroly přístupnosti jako klientský účet, ale z vašich vlastních nástrojů: z nasazovacího skriptu, agenturního dashboardu nebo systému tiketů. Kontroluje WCAG 2.2 úrovně A a AA enginem axe-core ve skutečném prohlížeči napříč stránkami webu a vrací výsledky se srozumitelným vysvětlením v sedmi jazycích reportu.

Vše na této stránce vychází z naší zveřejněné specifikace OpenAPI. Výsledky jsou automatizovaná kontrola, nikoli úplný audit, a nejsou právním poradenstvím.

Každý endpoint s parametry, ukázkami odpovědí, chybami a ukázkami kódu v curl, JavaScriptu, PHP a Pythonu popisuje dokumentace API.

Co API umí

Základní URL je https://pandus.online/api/v1. Report a PDF přijímají volitelný parametr lang: en, uk, de, pl, cs, ro nebo ru. Bez něj se použije jazyk reportu nastavený u webu.

JSON report obsahuje skupiny problémů s kartami pravidel, příklady, dotčené stránky, součty podle závažnosti, porovnání „před a po“ s předchozí kontrolou a trend. Kontrola má stav queued, running, completed nebo failed a koncové body reportu odpovídají 409, dokud kontrola není dokončená.

Ověření a limity

Vytvořte token v účtu v sekci API a webhooky a posílejte ho jako bearer token:

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

• Token patří týmu, ne osobě, takže funguje dál, i když někdo odejde.
• Oprávnění: read zahrnuje každý požadavek GET, write přidávání a mazání webů a spouštění kontrol. Pro dashboard stačí token jen pro čtení.
• Limit požadavků: 60 požadavků za minutu na token. Nad limit dostanete HTTP 429 s hlavičkou Retry-After.
• Limity tarifu platí stejně jako v účtu: počet webů, stránek na kontrolu, historie a jak často lze kontrolu spustit ručně. Požadavek nad limit vrátí HTTP 422 se zprávou.
• API je součástí tarifů Pro a Agency; viz ceník.

Přidání webu a spuštění kontroly

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": "cs", "platform": "shopify", "tags": ["client-a"]}'

url a report_locale jsou povinné. platform (shopify, woocommerce, prestashop, shoptet nebo other) umožní, aby report zobrazil návody k opravě pro danou platformu; tags pomáhají agenturám třídit weby podle klientů. Odpověď je 201 s novým webem a jeho první kontrola je zařazena do fronty.

Pro pozdější opakovanou kontrolu, například po vydání nové verze:

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

Odpověď je 202 s kontrolou ve frontě. Poté buď dotazujte GET /scans/{scan}, nebo lépe počkejte na webhook.

Webhooky

Odesílají se dvě události: scan.completed a issues.new. Každá je JSON POST ve tvaru {id, type, created_at, data: {scan, site, new_issues}} s těmito hlavičkami:

• Pandus-Event je typ události;
• Pandus-Delivery je ID doručení;
• Pandus-Signature: t=<unix>,v1=<hex>, kde v1 je HMAC-SHA256 z "<t>.<raw body>" s tajným klíčem vašeho koncového bodu.

Odpovězte stavem 2xx do 10 sekund. Neúspěšná doručení se opakují zhruba jeden den; v účtu můžete poslat testovací událost a doručení ručně zopakovat. Minimální ověření v 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)
    );
}

Použijte surové tělo požadavku, ne znovu serializovaný objekt JSON, a odmítejte stará časová razítka, abyste zabránili opakovanému přehrání.

Použití API v CI

API kontroluje veřejný web, takže se hodí po nasazení do produkce nebo na veřejně dostupný preview:

1. Váš pipeline nasadí.
2. Úloha zavolá POST /sites/{site}/scans.
3. Váš koncový bod přijme scan.completed nebo issues.new, přečte GET /scans/{scan}/report a otevře tiket nebo pošle zprávu do chatu.

Nenechávejte merge čekat na kontrolu celého webu; celý web může chvíli trvat. Pro rychlou zpětnou vazbu u každého pull requestu spouštějte axe-core uvnitř vlastních testů (viz testování přístupnosti pomocí Playwright) a nechte Pandus sledovat produkční web každý týden a po vydání nových verzí.

Localhost, testovací weby a stránky za přihlášením

Náš skener otevírá jen veřejné adresy. Blokuje privátní a lokální sítě, včetně localhost, před každým přesměrováním i po něm. Je to bezpečnostní opatření, ne mezera, kterou bychom plánovali odstranit. Pro cokoli, co není veřejné:

• Rozšíření prohlížeče pro Chrome, Edge a Firefox zkontroluje stránku tak, jak ji vidí váš prohlížeč: lokální vývojový server, testovací web chráněný heslem, košík, pokladnu, zákaznický účet. Kontrolu lze uložit k webu v Pandus.
• Vaše vlastní testy Playwright s @axe-core/playwright dosáhnou všude, kam se dostane váš CI.
• Ještě před založením účtu vyzkoušejte bezplatný WCAG checker na libovolné veřejné stránce.

Co API nedělá

Neprovádí ruční audit, „neopravuje“ web skriptem a nerozhoduje, zda se na vás vztahuje zákon. Vrací automatické nálezy s odkazy na WCAG a EN 301 549 z naší knihovny pravidel a report, který si přečte majitel obchodu nebo klient agentury. Pro web na WordPressu existuje také plugin pro WordPress, který používá samostatný token vázaný na web.

Časté otázky

Má Pandus API pro kontrolu přístupnosti?

Ano. REST API v1 umožňuje vypsat a přidávat weby, spouštět kontroly, číst jejich stav, získat report jako JSON nebo PDF a stáhnout snímky obrazovky. Webhooky vás upozorní, že kontrola skončila a že se objevily nové problémy.

Které tarify obsahují API?

Tarif Pro a tarify Agency. Ve verzi Free a s expresním reportem API součástí není; tokeny týmu, který přejde na takový tarif, přestanou fungovat, dokud tarif API znovu nezahrnuje.

Může API zkontrolovat localhost nebo testovací server?

Ne. Náš skener otevírá jen veřejné adresy a z bezpečnostních důvodů blokuje privátní a lokální sítě. Pro localhost, testovací weby a stránky za přihlášením použijte rozšíření prohlížeče, nebo spusťte axe-core ve vlastních testech Playwright.

Jak jsou webhooky zabezpečené?

Každé doručení nese hlavičku Pandus-Signature s časovou značkou a HMAC-SHA256 z časové značky a surového těla, vytvořeným tajným klíčem vašeho koncového bodu. Než datům uvěříte, podpis porovnejte.

Je výsledek z API audit WCAG?

Ne. API vrací výsledky automatické kontroly, nikoli úplného auditu, a nejde o právní poradenství. Mnoho kritérií WCAG stále vyžaduje ruční posouzení.