v1.0

Documentación

Integración del captcha en cualquier web en 60 segundos.

Quickstart

Crea una cuenta gratis.
En el dashboard, registra tu dominio y copia tu sitekey y secret_key.
Pega el snippet HTML donde quieras el captcha.
En tu backend, valida el token con POST /siteverify.

Integración HTML

Pega esto en tu formulario, donde quieras que aparezca el captcha:

<script src="https://captcha.softwalabs.com/v1/api.js" async defer></script>

<form method="post" action="/login">
  <input name="email" type="email">
  <input name="password" type="password">

  <div class="softwacap" data-sitekey="TU_SITEKEY"></div>

  <button type="submit">Entrar</button>
</form>

El widget inyecta automáticamente un <textarea name="g-recaptcha-response"> en el formulario. Tu backend recibirá el token en ese campo.

Atributos de configuración

Atributo	Tipo	Descripción
`data-sitekey`	string	Tu clave pública (obligatorio).
`data-callback`	string	Nombre de función JS global a llamar al éxito (recibe el token).
`data-expired-callback`	string	Nombre de función JS al expirar el token.
`data-error-callback`	string	Nombre de función JS si falla la verificación.
`data-response-field-name`	string	Nombre del input hidden (default: `g-recaptcha-response`).

Verificación server-side

En tu backend, valida el token con una petición POST. Compatible drop-in con reCAPTCHA siteverify.

POST https://captcha.softwalabs.com/siteverify
Content-Type: application/x-www-form-urlencoded

secret=TU_SECRET_KEY&response=TOKEN_DEL_FORMULARIO&remoteip=IP_USUARIO

Respuesta:

{
  "success": true,
  "score": 0.85,
  "challenge_ts": "2026-04-26T10:30:00Z",
  "hostname": "midominio.com"
}

Si success es true, el usuario es humano. score va de 0 a 1; típicamente acepta > 0.5.

Migración desde reCAPTCHA

Si ya usas reCAPTCHA v2/v3, cambias 2 líneas:

1. Frontend

// Antes
<script src="https://www.google.com/recaptcha/api.js"></script>
<div class="g-recaptcha" data-sitekey="..."></div>

// Después — dos opciones

// Opción A: cambiar src y clase
<script src="https://captcha.softwalabs.com/v1/api.js"></script>
<div class="softwacap" data-sitekey="..."></div>

// Opción B: solo cambiar src (mantenemos g-recaptcha)
<script src="https://captcha.softwalabs.com/v1/api.js"></script>
<div class="g-recaptcha" data-sitekey="..."></div>

2. Backend

Cambia el endpoint:

// Antes
https://www.google.com/recaptcha/api/siteverify

// Después
https://captcha.softwalabs.com/siteverify

El formato de la petición y de la respuesta JSON es idéntico. Tu lógica de validación no cambia.

Referencia API JS

El widget expone una API global compatible con grecaptcha:

// Renderizar manualmente
var widgetId = softwacap.render('mi-div', {
  sitekey: 'pk_swl_...',
  callback: function (token) { console.log(token); }
});

// Obtener el token actual
var token = softwacap.getResponse(widgetId);

// Resetear (forzar nuevo challenge)
softwacap.reset(widgetId);

// Esperar a que esté listo
softwacap.ready(function () { /* widget cargado */ });

Ejemplos por lenguaje

PHP

$response = $_POST['g-recaptcha-response'] ?? '';

$ch = curl_init('https://captcha.softwalabs.com/siteverify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'secret'   => $_ENV['SOFTWACAP_SECRET'],
        'response' => $response,
        'remoteip' => $_SERVER['REMOTE_ADDR'] ?? '',
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($result['success']) && ($result['score'] ?? 0) > 0.5) {
    // Es humano — procesar el formulario
} else {
    // Bloquear o pedir verificación adicional
}

Node.js

const verify = async (token, ip) => {
  const r = await fetch('https://captcha.softwalabs.com/siteverify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      secret: process.env.SOFTWACAP_SECRET,
      response: token,
      remoteip: ip,
    }),
  });
  const data = await r.json();
  return data.success && data.score > 0.5;
};

Python

import requests

r = requests.post('https://captcha.softwalabs.com/siteverify', data={
    'secret': os.environ['SOFTWACAP_SECRET'],
    'response': token,
    'remoteip': request.remote_addr,
})
data = r.json()
if data.get('success') and data.get('score', 0) > 0.5:
    pass  # humano

Códigos de error

Código	Significado
`missing-input-secret`	No se envió el parámetro `secret`.
`invalid-input-secret`	El `secret` no coincide con ningún sitio.
`missing-input-response`	No se envió el parámetro `response`.
`invalid-input-response`	Token inválido, mal firmado o expirado.
`timeout-or-duplicate`	Token ya usado (one-time-use).
`quota-exceeded`	Has superado tu cuota mensual.
`rate-limited`	Demasiadas peticiones desde tu IP.

MCP server Pro+

Opera SoftwaCAP desde Claude Desktop, Claude Code u otros clientes IA.

El servidor MCP está en https://captcha.softwalabs.com/mcp y habla JSON-RPC 2.0 sobre HTTP (Streamable transport). Soporta los métodos initialize, tools/list, tools/call, ping.

1. Crea una API key personal

En /dashboard/settings → API Keys (MCP) genera una key con scope read (y write si quieres operaciones de escritura). La key se muestra una sola vez; cópiala.

2. Configura Claude Desktop

Edita ~/.config/claude/claude_desktop_config.json (Linux/macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "softwacap": {
      "url": "https://captcha.softwalabs.com/mcp",
      "headers": {
        "Authorization": "Bearer ak_swl_TU_API_KEY"
      }
    }
  }
}

Reinicia Claude Desktop. El asistente verá las tools de SoftwaCAP automáticamente.

3. Tools disponibles

Lectura (Pro+)

Tool	Descripción
`list_sites`	Lista todos tus sitios
`get_site`	Detalles de un sitio (incluye secret_key)
`get_quota`	Uso actual del mes y límite del plan
`get_stats`	Estadísticas agregadas (total, % éxito, scores)
`recent_verifications`	Últimas verificaciones (filtrable por site / sólo fallos)
`get_billing_info`	Plan, ciclo, fecha de renovación

Escritura (Pro+, scope `write`)

Tool	Descripción
`create_site`	Crea un sitio nuevo y devuelve sitekey + secret_key
`update_site`	Modifica nombre, dominios, dificultad o estado activo
`rotate_secret`	Invalida el secret_key actual y genera uno nuevo
`delete_site`	Elimina un sitio definitivamente

Avanzadas Business+

Tool	Descripción
`simulate_verify`	Simula una verificación con perfil `human` / `bot` / `borderline` y devuelve el score
`bulk_export_csv`	Exporta hasta 50.000 verificaciones como CSV

4. Ejemplo de prompts

Tú: Lista mis sitios y dime cuáles tuvieron mayor tasa de fallo este mes.
Tú: Crea un sitio nuevo para midominio.com en dificultad easy con Adaptive Pace activado.
Tú: Simula una verificación con perfil bot y otra con perfil humano para ver la diferencia de scores.
Tú: Exporta a CSV las verificaciones fallidas de los últimos 7 días del sitio #3.

Adaptive Pace Pro+

Captcha que se ajusta solo al ritmo de tus humanos.

Por defecto un sitio tiene una dificultad fija (easy, normal o hard). Con Adaptive Pace activo, el motor recalcula los timings reales (velocidad de flash, pausa entre estrellas, longitud de la secuencia) en función de la tasa de éxito de las sesiones humanas en los últimos 7 días.

Cómo decide el ajuste

Sólo cuenta verificaciones con behavior_score ≥ 0.6 Y ai_score ≥ 0.5. Los bots no envenenan la métrica.
Necesita al menos 30 muestras humanas en los últimos 7 días. Mientras tanto usa el baseline.
Si la tasa de éxito humano < 60% → relaja: +20% al flash, +20% al gap, −1 a la secuencia (mínimo 3).
Si > 95% → endurece: −10% al flash, −10% al gap, +1 a la secuencia (máximo 5).
Recálculo cada 5 minutos. Cache en BD por sitio.

Cómo activarlo

En /dashboard/sites:

Al crear un sitio nuevo: marca el checkbox Adaptive Pace en el modal.
En sitios existentes: usa el botón Activar/Desactivar en la sección Adaptive Pace de cada sitio.

Alternativa MCP: update_site con adaptive_pace: true.

¿Algo no funciona? Escribe a hola@softwalabs.com o usa el chat de soporte cuando estés logueado.