Referência Técnica

API REST

Analise a acessibilidade de qualquer URL programaticamente. Integre com CI/CD, dashboards e ferramentas de auditoria usando nossa API com autenticação por chave.

Disponívelv1https://webparatodos.com.br/api/v1

Primeiros Passos

Autenticação

Todas as requisições autenticadas exigem uma API key no header X-Api-Key. As chaves seguem o formato wpt_....

Para obter uma API key, entre em contato em contato@webparatodos.com.br.

# Inclua o header X-Api-Key em todas as requisições
curl -X POST https://webparatodos.com.br/api/v1/analyze \
  -H "X-Api-Key: wpt_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.exemplo.com.br"}'

Endpoints

Referência

POST/api/v1/analyze

Analisa a acessibilidade de uma URL usando Playwright (renderização completa de JavaScript) e axe-core (WCAG 2.1 A, AA + regras AAA automáticas). Retorna score, violações detalhadas e metadados da página.

Corpo da requisição

Campo	Tipo	Descrição
`url`*	`string`	URL a ser analisada. Prefixo https:// é adicionado automaticamente se ausente.

Exemplo de requisição

curl -X POST https://webparatodos.com.br/api/v1/analyze \
  -H "X-Api-Key: wpt_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.exemplo.com.br"}'

// JavaScript / Node.js
const res = await fetch('https://webparatodos.com.br/api/v1/analyze', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'wpt_sua_chave_aqui'
  },
  body: JSON.stringify({ url: 'https://www.exemplo.com.br' })
})
const data = await res.json()
console.log(data.score, data.violations)

# Python
import httpx

res = httpx.post(
    "https://webparatodos.com.br/api/v1/analyze",
    headers={"X-Api-Key": "wpt_sua_chave_aqui"},
    json={"url": "https://www.exemplo.com.br"}
)
data = res.json()
print(data["score"], len(data["violations"]), "violações")

Resposta 200 OK

{
  "url": "https://www.exemplo.com.br",
  "analyzedAt": "2026-03-27T14:25:16.636Z",
  "captureMethod": "playwright",
  "score": 74,
  "reportUrl": "https://webparatodos.com.br/analyzer?url=https%3A%2F%2Fwww.exemplo.com.br",
  "summary": {
    "critical": 1,
    "serious": 3,
    "moderate": 4,
    "minor": 0,
    "total": 8
  },
  "violations": [
    {
      "id": "color-contrast-enhanced",
      "severity": "serious",
      "description": "Contraste Insuficiente para o Nível AAA (7:1)",
      "wcag": "1.4.6 Contraste Melhorado — Nível AAA",
      "affectedElements": 12,
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.11/color-contrast-enhanced",
      "sample": {
        "selector": "a.nav-link",
        "html": "<a class=\"nav-link\" href=\"/home\">Início</a>"
      }
    }
  ],
  "meta": {
    "pageTitle": "Portal MT — Governo de Mato Grosso",
    "httpStatus": 200,
    "loadTimeMs": 2340,
    "domElementCount": 847,
    "detectedFrameworks": ["WordPress"],
    "requestsUsedToday": 3,
    "dailyLimit": 50
  }
}

Campos da resposta

Campo	Tipo	Descrição
`score`	`number`	Pontuação de 0 a 100. Calculada como proporção ponderada das regras aprovadas: nota = (peso aprovadas ÷ peso total) × 100, com pesos crítica=4, séria=3, moderada=2, menor=1.
`reportUrl`	`string`	Link direto para o relatório visual completo no analisador do Web para Todos.
`summary`	`object`	Contagem de violações por severidade: critical, serious, moderate, minor e total.
`violations[].id`	`string`	Identificador da regra axe-core (ex: color-contrast, landmark-one-main).
`violations[].severity`	`string`	Impacto: critical, serious, moderate ou minor.
`violations[].wcag`	`string\|null`	Critério WCAG relacionado, quando mapeado (ex: 1.4.3 Contraste Mínimo).
`violations[].affectedElements`	`number`	Quantidade de elementos HTML afetados pela violação.
`violations[].sample`	`object`	Primeiro elemento afetado: selector CSS e HTML truncado em 300 caracteres.
`meta.loadTimeMs`	`number`	Tempo de carregamento da página em milissegundos.
`meta.requestsUsedToday`	`number`	Requisições consumidas hoje com esta chave.
`meta.dailyLimit`	`number`	Limite diário de requisições desta chave.

GET/api/v1/report

Redireciona para o relatório visual completo do analisador com a URL pré-preenchida. Não requer autenticação — útil para links em e-mails, relatórios e dashboards.

Parâmetros

Parâmetro	Tipo	Descrição
`url`*	`string`	URL a ser analisada. Será codificada automaticamente.

Exemplo

https://webparatodos.com.br/api/v1/report?url=https://www.exemplo.com.br

Retorna HTTP 302 redirecionando para /analyzer?url=...

Erros

Códigos de resposta

Código	Situação	Mensagem típica
200	Análise concluída com sucesso	—
400	URL ausente ou inválida	Body inválido. Esperado: {"url": "https://..."}
401	API key ausente, inválida ou desativada	API key ausente ou inválida. Inclua o header X-Api-Key: wpt_...
429	Limite diário atingido	Limite diário de 50 requisições atingido. Renova às 00h00 (UTC).
502	URL inacessível ou retornou erro	Falha ao capturar a URL: ...
504	Timeout (página demorou mais de 45s)	Timeout ao carregar a URL (limite: 45s).

Limites e Cobertura

O que a API analisa

Cobertura

✓ WCAG 2.1 Nível A — 30 critérios
✓ WCAG 2.1 Nível AA — 20 critérios adicionais
✓ AAA automático: contraste 7:1, links idênticos
✓ JavaScript renderizado (Playwright + Chromium)
~ ~34% dos critérios WCAG cobertos automaticamente (30 de 87)

Limites de uso

→ Timeout por análise: 45 segundos
→ Limite diário: conforme seu plano
→ Reset do contador: 00h00 UTC
→ HTML retornado: truncado em 300 caracteres

Integração

Uso em CI/CD

Adicione auditoria de acessibilidade automática no seu pipeline de deploy.

# GitHub Actions — auditar acessibilidade no deploy
name: Auditoria de Acessibilidade

on:
  push:
    branches: [main]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - name: Auditar acessibilidade
        run: |
          RESULT=$(curl -sf -X POST https://webparatodos.com.br/api/v1/analyze \
            -H "X-Api-Key: ${{ secrets.WPT_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"url": "https://www.exemplo.com.br"}')

          SCORE=$(echo $RESULT | python3 -c "import sys,json; print(json.load(sys.stdin)['score'])")
          echo "Score de acessibilidade: $SCORE"

          # Falha o build se score abaixo de 70
          [ "$SCORE" -ge 70 ] || (echo "Score abaixo do mínimo (70)" && exit 1)