API pentru verificarea accesibilității: verificări WCAG din propriile instrumente

API-ul Pandus vă oferă aceleași verificări automate de accesibilitate ca în cabinet, direct din propriile instrumente: un script de deployment, un dashboard de agenție, un sistem de tichete. Verifică WCAG 2.2 nivel A și AA cu motorul axe-core într-un browser real, pe paginile unui site, și returnează rezultate cu explicații pe înțelesul tuturor, în șapte limbi de raport.

Tot ce apare pe această pagină provine din specificația OpenAPI publicată de noi. Rezultatele sunt o verificare automată, nu un audit complet, și nu constituie consultanță juridică.

Fiecare endpoint, cu parametri, exemple de răspuns, erori și exemple de cod în curl, JavaScript, PHP și Python, este descris în documentația API.

Ce face API-ul

URL-ul de bază este https://pandus.online/api/v1. Raportul și PDF-ul acceptă un parametru opțional lang: en, uk, de, pl, cs, ro sau ru. Fără el se folosește limba de raport a site-ului.

Raportul JSON conține grupurile de probleme cu fișele lor de reguli, exemple, paginile afectate, totaluri pe niveluri de gravitate, o comparație înainte/după cu verificarea anterioară și tendința. O verificare are starea queued, running, completed sau failed, iar endpointurile de raport răspund cu 409 până când este finalizată.

Autentificare și limite

Creați un token în cabinet, la API și webhook-uri, și trimiteți-l ca bearer token:

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

• Un token aparține echipei, nu unei persoane, așa că rămâne funcțional când cineva pleacă.
• Permisiuni: read acoperă toate cererile GET, write acoperă adăugarea și ștergerea site-urilor și pornirea verificărilor. Pentru un dashboard este suficient un token doar pentru citire.
• Limită de cereri: 60 de cereri pe minut per token. Peste această limită primiți HTTP 429 cu antetul Retry-After.
• Limitele planului se aplică la fel ca în cabinet: numărul de site-uri, paginile per verificare, istoricul și cât de des poate fi pornită manual o verificare. O cerere peste limită returnează HTTP 422 cu un mesaj.
• API-ul este inclus în planurile Pro și Agency — vedeți prețurile.

Adăugați un site și porniți o verificare

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

url și report_locale sunt obligatorii. platform (shopify, woocommerce, prestashop, shoptet sau other) permite raportului să afișeze instrucțiuni de remediere pentru acea platformă; tags ajută agențiile să sorteze site-urile după client. Răspunsul este 201 cu site-ul nou, iar prima lui verificare este pusă în coadă.

Pentru o nouă verificare mai târziu, de exemplu după o lansare:

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

Răspunsul este 202 cu verificarea pusă în coadă. Apoi fie interogați periodic GET /scans/{scan}, fie, mai bine, așteptați un webhook.

Webhook-uri

Se trimit două evenimente: scan.completed și issues.new. Fiecare este un POST JSON de forma {id, type, created_at, data: {scan, site, new_issues}} cu aceste antete:

• Pandus-Event — tipul evenimentului;
• Pandus-Delivery — ID-ul livrării;
• Pandus-Signature: t=<unix>,v1=<hex> — v1 este un HMAC-SHA256 al "<t>.<raw body>" cu secretul endpointului dumneavoastră.

Răspundeți cu un status 2xx în 10 secunde. Livrările eșuate sunt reîncercate timp de aproximativ o zi; în cabinet puteți trimite un eveniment de test și reîncerca manual o livrare. O verificare minimă în 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)
    );
}

Folosiți corpul brut al cererii, nu un obiect JSON serializat din nou, și respingeți timestampurile vechi pentru a opri reluările.

Utilizarea API-ului în CI

API-ul verifică site-ul public, așa că se potrivește după un deployment în producție sau pe un preview accesibil public:

1. Pipeline-ul face deployment.
2. Un job apelează POST /sites/{site}/scans.
3. Endpointul dumneavoastră primește scan.completed sau issues.new, citește GET /scans/{scan}/report și deschide un tichet sau trimite un mesaj într-un chat.

Nu condiționați un merge de o verificare a întregului site; un site întreg poate dura ceva timp. Pentru feedback rapid la fiecare pull request rulați axe-core în propriile teste — vedeți testarea accesibilității cu Playwright — și lăsați Pandus să urmărească site-ul de producție în fiecare săptămână și după lansări.

Localhost, staging și pagini din spatele unei autentificări

Scannerul nostru deschide doar adrese publice. Blochează rețelele private și locale, inclusiv localhost, înainte și după fiecare redirecționare — o măsură de securitate, nu o lacună pe care plănuim să o eliminăm. Pentru tot ce nu este public:

• Extensia de browser pentru Chrome, Edge și Firefox verifică pagina așa cum o afișează browserul dumneavoastră: un server local de dezvoltare, un site de staging protejat cu parolă, coșul, checkout-ul, contul clientului. O verificare poate fi salvată la site în Pandus.
• Propriile teste Playwright cu @axe-core/playwright ajung oriunde poate ajunge CI-ul dumneavoastră.
• Înainte de a vă crea un cont, încercați WCAG checkerul gratuit pe orice pagină publică.

Ce nu face API-ul

Nu efectuează un audit manual, nu „repară” un site cu un script și nu decide dacă o lege vi se aplică. Returnează constatări automate cu trimiterile la WCAG și EN 301 549 din biblioteca noastră de reguli și un raport pe care îl poate citi un proprietar de magazin sau clientul unei agenții. Pentru un site WordPress există și pluginul WordPress, care folosește un token separat, legat de site.

Întrebări frecvente

Are Pandus un API pentru verificarea accesibilității?

Da. REST API v1 vă permite să listați și să adăugați site-uri, să porniți verificări, să le citiți starea, să primiți raportul ca JSON sau PDF și să descărcați capturi de ecran. Webhook-urile vă anunță când o verificare s-a terminat și când apar probleme noi.

Ce planuri includ API-ul?

Planul Pro și planurile Agency. În planul Free și la raportul expres API-ul nu este inclus; tokenurile unei echipe care trece la un astfel de plan nu mai funcționează până când planul include din nou API-ul.

Poate API-ul să verifice localhost sau un server de staging?

Nu. Scannerul nostru deschide doar adrese publice și blochează rețelele private și locale din motive de securitate. Pentru localhost, staging și pagini din spatele unei autentificări folosiți extensia de browser sau rulați axe-core în propriile teste Playwright.

Cum sunt securizate webhook-urile?

Fiecare livrare conține un antet Pandus-Signature cu un timestamp și un HMAC-SHA256 al timestampului și al corpului brut, calculat cu secretul endpointului dumneavoastră. Comparați-l înainte să aveți încredere în conținut.

Este un rezultat API un audit WCAG?

Nu. API-ul returnează rezultatele unei verificări automate, nu un audit complet, și nu constituie consultanță juridică. Multe criterii WCAG au nevoie în continuare de o evaluare manuală.