API проверки доступности: проверки WCAG из ваших собственных инструментов

API Pandus даёт те же автоматические проверки доступности, что и личный кабинет, но из ваших собственных инструментов: скрипта развёртывания, панели агентства, системы тикетов. Оно проверяет WCAG 2.2 уровней A и AA движком axe-core в настоящем браузере на страницах сайта и возвращает результаты с объяснениями простым языком на семи языках отчётов.

Всё на этой странице взято из нашей опубликованной спецификации OpenAPI. Результаты — это автоматическая проверка, а не полный аудит и не юридическая консультация.

Каждый эндпоинт с параметрами, примерами ответов, ошибками и примерами кода на curl, JavaScript, PHP и Python описан в документации API.

Что умеет API

Базовый адрес — https://pandus.online/api/v1. Отчёт и PDF принимают необязательный параметр lang: en, uk, de, pl, cs, ro или ru. Без него используется язык отчёта сайта.

JSON-отчёт содержит группы проблем с карточками правил, примеры, затронутые страницы, итоги по серьёзности, сравнение «было / стало» с предыдущей проверкой и тренд. У проверки бывает статус queued, running, completed или failed, и пока она не завершена, конечные точки отчёта отвечают 409.

Аутентификация и лимиты

Создайте токен в кабинете в разделе API и вебхуки и передавайте его как bearer-токен:

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

• Токен принадлежит команде, а не человеку, поэтому он продолжает работать, когда кто-то уходит.
• Права: read охватывает все GET-запросы, write — добавление и удаление сайтов и запуск проверок. Для панели мониторинга достаточно токена только для чтения.
• Ограничение частоты: 60 запросов в минуту на токен. При превышении вы получите HTTP 429 с заголовком Retry-After.
• Лимиты тарифа действуют так же, как в кабинете: число сайтов, страниц в проверке, глубина истории и то, как часто проверку можно запускать вручную. Запрос сверх лимита возвращает HTTP 422 с сообщением.
• API входит в тарифы Pro и Agency — см. цены.

Добавить сайт и запустить проверку

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 и report_locale обязательны. platform (shopify, woocommerce, prestashop, shoptet или other) позволяет показывать в отчёте инструкции по исправлению для этой платформы; tags помогают агентствам группировать сайты по клиентам. В ответ приходит 201 с новым сайтом, а его первая проверка ставится в очередь.

Чтобы запустить проверку снова, например после релиза:

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

Ответ — 202 с поставленной в очередь проверкой. Дальше либо опрашивайте GET /scans/{scan}, либо, лучше, дождитесь вебхука.

Вебхуки

Отправляются два события: scan.completed и issues.new. Каждое — это JSON-запрос POST вида {id, type, created_at, data: {scan, site, new_issues}} со следующими заголовками:

• Pandus-Event — тип события;
• Pandus-Delivery — идентификатор доставки;
• Pandus-Signature: t=<unix>,v1=<hex> — v1 содержит HMAC-SHA256 от "<t>.<исходное тело>" с секретом вашей конечной точки.

Отвечайте статусом 2xx в течение 10 секунд. Неудачные доставки повторяются примерно сутки; в кабинете можно отправить тестовое событие и повторить доставку вручную. Минимальная проверка на 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)
    );
}

Используйте исходное тело запроса, а не заново сериализованный JSON-объект, и отклоняйте старые метки времени, чтобы остановить повторную отправку перехваченных запросов.

API в CI

API проверяет публичный сайт, поэтому оно подходит после развёртывания на рабочий сайт или на общедоступную предварительную версию:

1. Ваш конвейер выполняет развёртывание.
2. Задание вызывает POST /sites/{site}/scans.
3. Ваша конечная точка получает scan.completed или issues.new, читает GET /scans/{scan}/report и создаёт тикет или пишет в чат.

Не заставляйте слияние ждать проверки всего сайта: она может занять время. Для быстрой обратной связи на каждый pull request запускайте axe-core внутри собственных тестов — см. тестирование доступности с Playwright — а Pandus пусть следит за рабочим сайтом каждую неделю и после релизов.

Localhost, тестовые среды и страницы за авторизацией

Наш сканер открывает только публичные адреса. Он блокирует частные и локальные сети, включая localhost, до и после каждого редиректа — это мера безопасности, а не пробел, который мы собираемся устранить. Для всего непубличного:

• Расширение для браузера для Chrome, Edge и Firefox проверяет страницу так, как её показывает ваш браузер: локальный сервер разработки, тестовый сайт под паролем, корзину, оформление заказа, личный кабинет покупателя. Результат проверки можно сохранить в Pandus для сайта.
• Ваши собственные тесты Playwright с @axe-core/playwright доходят до всего, до чего доходит ваш CI.
• До регистрации аккаунта попробуйте бесплатный WCAG тестер на любой публичной странице.

Чего API не делает

Оно не проводит ручной аудит, не «чинит» сайт скриптом и не решает, распространяется ли на вас закон. Оно возвращает результаты автоматической проверки со ссылками на WCAG и EN 301 549 из нашей библиотеки правил и отчёт, который может прочитать владелец магазина или клиент агентства. Для сайта на WordPress есть ещё плагин для WordPress, который использует отдельный токен, привязанный к сайту.

Частые вопросы

Есть ли у Pandus API для проверки доступности?

Да. REST API v1 позволяет получать список сайтов и добавлять их, запускать проверки, читать их статус, получать отчёт в JSON или PDF и скачивать скриншоты. Вебхуки сообщают, когда проверка завершена и когда появились новые проблемы.

В какие тарифы входит API?

В тариф Pro и тарифы Agency. На Free и с экспресс-отчётом API не входит; токены команды, перешедшей на такой тариф, перестают работать, пока тариф снова не включит API.

Может ли API проверить localhost или тестовый сервер?

Нет. Наш сканер открывает только публичные адреса и из соображений безопасности блокирует частные и локальные сети. Для localhost, тестовых сред и страниц за авторизацией используйте расширение для браузера или запускайте axe-core в собственных тестах Playwright.

Как защищены вебхуки?

Каждая доставка содержит заголовок Pandus-Signature с меткой времени и HMAC-SHA256 от метки времени и исходного тела запроса, подписанный секретом вашей конечной точки. Сверьте подпись, прежде чем доверять данным.

Результат API — это аудит WCAG?

Нет. API возвращает результаты автоматической проверки, а не полного аудита и не юридической консультации. Многие критерии WCAG по-прежнему требуют ручной проверки.