API DeskCaptcha

Início Rápido

Em menos de 5 minutos você pode integrar o DeskCaptcha em qualquer aplicação web.

GET https://seu-servidor.com/v1/health

GET https://seu-servidor.com/v1/captcha/generate?scale=1&chars=4

POST https://seu-servidor.com/v1/captcha/validate
Content-Type: application/json

{ "token": "abc123...", "answer": "A3B7" }

Base URL

https://seu-servidor.com/v1

http://localhost/deskcaptcha/public/index.php/v1

Autenticação

Por padrão a API é pública. Para produção você pode habilitar autenticação por API Key no arquivo config/api.php.

X-API-Key: sua-chave-secreta

Endpoints

{
  "success": true,
  "data": {
    "token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "image_url": "https://seu-servidor.com/v1/captcha/xYz12345.png",
    "expires_in": 600,
    "expires_at": "2026-04-24 10:00:00",
    "scale": 1,
    "chars": 4,
    "dimensions": { "width": 400, "height": 100 }
  },
  "meta": {
    "version": "1.0.0",
    "api": "DeskCaptcha",
    "request_id": "8dd91872875d7ada",
    "time_ms": "15.6",
    "remaining": { "minute": 28, "hour": 2998, "day": 9998 }
  }
}

<img src="https://seu-servidor.com/v1/captcha/xYz12345.png" alt="captcha">

{
  "token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "answer": "A3B7"
}

{
  "success": true,
  "data": {
    "valid": true,
    "message": "Captcha validated successfully."
  }
}

{
  "success": true,
  "data": {
    "valid": false,
    "message": "Incorrect answer."
  }
}

{
  "success": true,
  "data": {
    "status": "operational",
    "pool": { "active": 48, "target": 50 },
    "rate_limits": {
      "global": {
        "remaining": { "minute": 28, "hour": 2950, "day": 9800 },
        "limits": { "per_minute": 30, "per_hour": 3000, "per_day": 10000 }
      }
    },
    "database": "deskcaptcha_2026_04.sqlite"
  }
}

{
  "data": {
    "status": "healthy",
    "database": "ok"
  }
}

{
  "data": {
    "status": "degraded",
    "database": "error"
  }
}

Rate Limiting

A API aplica dois níveis de limites independentes: global (todos os usuários somados) e por usuário (identificado por IP + fingerprint).

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1714000000
Retry-After: 45          ← presente apenas em respostas 429/503

Códigos de Erro

Formato padrão de erro:

{
  "success": false,
  "error": {
    "code": 429,
    "type": "rate_limit",
    "message": "Too many requests. Please wait before retrying."
  },
  "meta": {
    "rate_limit": { "window": "minute", "retry_after": 45, "limit": 10 },
    "request_id": "8dd91872875d7ada"
  }
}

Exemplos de Código

HTML + JavaScript

<img id="captcha-img" alt="captcha">
<input type="text" id="answer" placeholder="Digite os caracteres"
       oninput="this.value=this.value.toUpperCase()">
<button onclick="load()">Atualizar</button>
<button onclick="submit()">Enviar</button>

<script>
const API = 'https://seu-servidor.com/v1';
let token = '';
let busy  = false;

async function load() {
  if (busy) return;
  busy = true;
  const res  = await fetch(`${API}/captcha/generate?scale=1&chars=4`);
  const json = await res.json();
  token = json.data.token;
  // Aguarda a imagem carregar antes de liberar o lock
  await new Promise(resolve => {
    const img = document.getElementById('captcha-img');
    img.onload  = resolve;
    img.onerror = resolve;
    img.src = json.data.image_url + '?t=' + Date.now();
  });
  busy = false;
}

async function submit() {
  const answer = document.getElementById('answer').value.trim();
  const res  = await fetch(`${API}/captcha/validate`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token, answer })
  });
  const json = await res.json();
  if (json.data?.valid) {
    alert('Captcha validado!');
  } else {
    alert('Resposta incorreta. Tente novamente.');
    load();
  }
}

load();
</script>

PHP — Validação no Backend

<?php
function validarCaptcha(string $token, string $resposta): bool {
    $ctx = stream_context_create([
        'http' => [
            'method'  => 'POST',
            'header'  => "Content-Type: application/json\r\n",
            'content' => json_encode(['token' => $token, 'answer' => $resposta]),
            'ignore_errors' => true,
        ]
    ]);
    $resp = file_get_contents(
        'https://seu-servidor.com/v1/captcha/validate',
        false, $ctx
    );
    $data = json_decode($resp, true);
    return $data['data']['valid'] ?? false;
}

// No handler do seu formulário:
if (!validarCaptcha($_POST['captcha_token'], $_POST['captcha_answer'])) {
    http_response_code(422);
    die(json_encode(['erro' => 'Captcha inválido.']));
}

// Prossiga com o processamento do formulário...

cURL

# Gerar captcha
curl "https://seu-servidor.com/v1/captcha/generate?scale=1&chars=4"

# Validar resposta
curl -X POST "https://seu-servidor.com/v1/captcha/validate" \
  -H "Content-Type: application/json" \
  -d '{"token":"abc123...","answer":"A3B7"}'

Fluxo Completo de Integração

Browser                    Seu Backend               DeskCaptcha API
  │                              │                           │
  │── página carrega ────────────▶                           │
  │                              │── GET /v1/captcha/generate ──▶
  │                              │◀── { token, image_url } ─────│
  │◀── exibe imagem captcha ─────│                           │
  │                              │                           │
  │── usuário digita e envia ────▶                           │
  │                              │── POST /v1/captcha/validate ─▶
  │                              │◀── { valid: true/false } ────│
  │                              │                           │
  │◀── sucesso ou erro ──────────│                           │