Referencia de la API

Referencia de la API (V2)

URL base: https://api.captchacore.eu: todos los endpoints responden con JSON. Si usa el widget suministrado, nunca llamará usted a /challenge; de eso se encarga el widget. Para un complemento propio solo /verify es obligatorio.

Autenticación

La clave va siempre en la cabecera X-CaptchaCore-Key, nunca en la URL.

GET /api/v2/challenge

Solicita un cálculo junto con su política. Parámetro de consulta opcional: form_type (véanse las políticas de formulario). Responde con HTTP 200.

{
  "challenge_id": "ch_a45cd15b0d6d2dc6",
  "nonce": "a45cd15b…1d50",          // einmalig, 5 Minuten gültig
  "expires_at": 1788860066,
  "policy": {
    "mode": "adaptive",
    "challenge_type": "sha256_pow",     // Zusatzprüfung steht ggf. unter "step_up"
    "challenge_types": ["sha256_pow"],
    "difficulty": 4,                  // führende Nullen im Hash
    "algorithm": "sha256",
    "time_budget_ms": 500,
    "requires_interaction": false,
    "requires_stepup_on_submit": false,
    "memory_hard_enabled": false,
    "form_type": "contact",
    "site_profile": "balanced",
    "uam_level": 0              // 0–3, Under-Attack-Stufe
  },
  "bindings": {                       // bindet den Token an Site, Origin und Formular
    "site_id": 2,
    "origin": "https://example.com",
    "form_type": "contact",
    "issued_at": 1788859766,
    "expires_at": 1788860066,
    "token_ttl_sec": 300
  },
  "bindings_signature": "CBkATjVc…RDg==",  // Ed25519, unveränderlich mitschicken
  "signing_key_id": "k_397d99d39156c5f5",
  "widget": { /* im Admin gepflegtes Erscheinungsbild */ },
  "widget_version": "3.0.0"
}

Importante para clientes propios: bindings y bindings_signature deben volver al token sin modificar. Si faltan o se alteran, /verify responde con block.

POST /api/v2/verify

Comprueba el token del formulario. Por regla general responde con HTTP 200, también en caso de rechazo. Evalúe el cuerpo, no el código de estado.

// Request
{
  "token": "<Wert des Feldes captchacore_token>",
  "form_type": "contact",      // optional, steuert die Policy
  "page_url": "https://…",      // optional, nur für Auswertungen
  "client_ip": "203.0.113.42"  // empfohlen: IP des Besuchers
}

// Response
{
  "valid": true,               // false bei block UND bei step_up
  "decision": "allow",        // allow | challenge | step_up | block
  "action": "allow",          // identisch zu decision (älterer Feldname)
  "request_id": "…",          // für Rückfragen an den Support
  "risk_score": 8,             // 0–100, höher = riskanter
  "confidence": 0.94,          // 0.0–1.0 Signalabdeckung
  "reasons": ["pow_valid", "behavior_human_like"],
  "step_up": null             // bei decision=step_up: Daten für die Zusatzprüfung
}

Cómo tratar decision

GET /api/v2/status

Disponibilidad y nivel actual de ataque del sitio. Adecuado para una comprobación de estado en su complemento.

{ "status": "ok", "under_attack": false, "version": "2.x" }

Códigos de estado HTTP

Límites de peticiones

Verify se cuenta por sitio, no por IP. Su servidor puede así comprobar tantos formularios como tráfico tenga su sitio, sin bloquearse a sí mismo.

En el límite por sitio solo cuentan los tokens de un challenge realmente emitido. Las solicitudes basura de un atacante chocan con el límite por IP del visitante y no agotan el contingente de sus visitantes reales. Para ello, envíe client_ip, como hacen todas las integraciones oficiales.

Webhooks

CaptchaCore avisa a sus propios sistemas cuando ocurre algo a lo que quiera reaccionar: cuota alcanzada, modo under-attack activado, cuenta bloqueada o desbloqueada. Se configura en el área de cliente en Sitios → Webhooks (a partir del plan Professional).

Eventos

Qué llega

Un POST con cuerpo JSON. Tres cabeceras ayudan a identificarlo y verificarlo:

POST /ihr-endpunkt HTTP/1.1
Content-Type: application/json
X-CaptchaCore-Event: usage.limit_reached
X-CaptchaCore-Delivery: 5f1c2c1e-…            // eindeutig je Zustellung, gleich bei Wiederholungen
X-CaptchaCore-Timestamp: 1758196800
X-CaptchaCore-Signature: sha256=3b2a…

{
  "event": "usage.limit_reached",
  "occurred_at": "2026-09-18T14:00:00+02:00",
  "organisation_id": 42,
  "data": { "threshold_percent": 100, "used": 10000, "limit": 10000, "plan": "pro", "period": "2026-09" }
}

Verificar la firma

La firma es un HMAC-SHA256 sobre «timestamp.body» con la clave del área de cliente. Compare en tiempo constante y rechace marcas de tiempo de más de cinco minutos: así evita repeticiones de solicitudes interceptadas.

$secret    = getenv('CAPTCHACORE_WEBHOOK_SECRET');
$body      = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_CAPTCHACORE_TIMESTAMP'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (abs(time() - (int) $timestamp) > 300
    || ! hash_equals($expected, $_SERVER['HTTP_X_CAPTCHACORE_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}

$event = json_decode($body, true);
// … verarbeiten, dann schnell mit 2xx antworten
http_response_code(204);

Entrega y reintentos

• Responda con un estado 2xx en menos de 5 segundos; procese lo costoso de forma asíncrona.
• Ante errores o tiempo de espera se reintenta hasta tres veces (a los 30 segundos y a los 5 minutos) con el mismo ID de entrega; haga su procesamiento idempotente con él.
• Tras diez fallos consecutivos el webhook se desactiva; en el área de cliente verá el motivo y podrá reactivarlo.
• Cada entrega, con código de respuesta, duración y extracto de la respuesta, figura en «Entregas», también para depurar en su lado.

Versionado y estabilidad

Quien mantiene un complemento necesita saber con qué puede contar. Estos son nuestros compromisos.