cURL + CaptchaAI: Resolución CLI CAPTCHA

No se necesita SDK. Resuelve CAPTCHA directamente desde tu terminal con cURL y la API REST de CaptchaAI. Perfecto para pruebas rápidas, pipelines CI/CD y scripts de shell.

Requisitos

Comandos básicos

Consultar saldo

curl -s "https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=getbalance"

Salida: 1.234

Enviar reCAPTCHA v2

curl -s "https://ocr.captchaai.com/in.php?key=YOUR_API_KEY&method=userrecaptcha&googlekey=6Le-wvkS...&pageurl=https://example.com"

Salida: OK|73548291

Sondear resultado

curl -s "https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=73548291"

Salida: OK|03AGdBq24PBCbw... o CAPCHA_NOT_READY

Script de resolución en Bash

Crear solve_captcha.sh:

#!/bin/bash
set -euo pipefail

API_KEY="${CAPTCHAAI_API_KEY:?Set CAPTCHAAI_API_KEY environment variable}"
BASE_URL="https://ocr.captchaai.com"

solve_recaptcha() {
    local site_key="$1"
    local page_url="$2"
    local timeout="${3:-300}"

    # Submit
    local response
    response=$(curl -s "${BASE_URL}/in.php?key=${API_KEY}&method=userrecaptcha&googlekey=${site_key}&pageurl=${page_url}")

    if [[ ! "$response" == OK|* ]]; then
        echo "ERROR: Submit failed: $response" >&2
        return 1
    fi

    local task_id="${response#OK|}"
    echo "Submitted task: $task_id" >&2

    # Poll
    local deadline=$((SECONDS + timeout))
    while (( SECONDS < deadline )); do
        sleep 5
        local result
        result=$(curl -s "${BASE_URL}/res.php?key=${API_KEY}&action=get&id=${task_id}")

        if [[ "$result" == "CAPCHA_NOT_READY" ]]; then
            echo "Waiting..." >&2
            continue
        fi

        if [[ "$result" == OK|* ]]; then
            echo "${result#OK|}"
            return 0
        fi

        echo "ERROR: Solve failed: $result" >&2
        return 1
    done

    echo "ERROR: Timeout after ${timeout}s" >&2
    return 1
}

# Usage: ./solve_captcha.sh SITE_KEY PAGE_URL
if [[ $# -ge 2 ]]; then
    solve_recaptcha "$1" "$2"
fi

Hazlo ejecutable:

chmod +x solve_captcha.sh

Ejecutar:

export CAPTCHAAI_API_KEY="your_key_here"
./solve_captcha.sh "6Le-wvkS..." "https://example.com"

Resolver Cloudflare Turnstile

curl -s "https://ocr.captchaai.com/in.php?key=${CAPTCHAAI_API_KEY}&method=turnstile&sitekey=0x4AAAAA...&pageurl=https://example.com"

Resolver CAPTCHA de imagen

# Encode image to base64
IMAGE_B64=$(base64 -w 0 captcha.png)

# Submit
curl -s "https://ocr.captchaai.com/in.php?key=${CAPTCHAAI_API_KEY}&method=base64&body=${IMAGE_B64}"

Para imágenes grandes, usa POST:

curl -s -X POST "https://ocr.captchaai.com/in.php" \
  -F "key=${CAPTCHAAI_API_KEY}" \
  -F "method=post" \
  -F "file=@captcha.png"

Resolver y usar tokens en un solo pipeline

#!/bin/bash
# Solve CAPTCHA and submit form in one pipeline

API_KEY="${CAPTCHAAI_API_KEY}"
SITE_KEY="6Le-wvkS..."
TARGET_URL="https://staging.example.com/qa-login"

# Solve
TOKEN=$(./solve_captcha.sh "$SITE_KEY" "$TARGET_URL")

if [[ -z "$TOKEN" ]]; then
    echo "Failed to solve CAPTCHA"
    exit 1
fi

# Submit form with token
curl -s -X POST "$TARGET_URL" \
  -d "username=user" \
  -d "password=pass" \
  -d "g-recaptcha-response=${TOKEN}"

Procesamiento por lotes

Resuelva múltiples CAPTCHA de un archivo:

#!/bin/bash
# Input file: urls.txt (one URL per line)

while IFS= read -r url; do
    echo "Processing: $url"
    TOKEN=$(./solve_captcha.sh "6Le-wvkS..." "$url")
    if [[ -n "$TOKEN" ]]; then
        echo "$url,$TOKEN" >> results.csv
        echo "  Solved ✓"
    else
        echo "  Failed ✗"
    fi
done < urls.txt

PowerShell (Windows)

$ApiKey = $env:CAPTCHAAI_API_KEY
$BaseUrl = "https://ocr.captchaai.com"

# Submit
$response = Invoke-RestMethod "${BaseUrl}/in.php?key=${ApiKey}&method=userrecaptcha&googlekey=6Le-wvkS...&pageurl=https://example.com"

if ($response -match '^OK\|(.+)$') {
    $taskId = $Matches[1]
    Write-Host "Task: $taskId"
} else {
    Write-Error "Submit failed: $response"
    exit 1
}

# Poll
do {
    Start-Sleep -Seconds 5
    $result = Invoke-RestMethod "${BaseUrl}/res.php?key=${ApiKey}&action=get&id=${taskId}"
} while ($result -eq 'CAPCHA_NOT_READY')

if ($result -match '^OK\|(.+)$') {
    $token = $Matches[1]
    Write-Host "Token: $token"
} else {
    Write-Error "Solve failed: $result"
}

Solución de problemas

Preguntas frecuentes

¿Puedo usar esto en pipelines CI/CD?

Sí. Configura CAPTCHAAI_API_KEY como secreto de CI y llama al script en tu pipeline. Funciona con GitHub Actions, GitLab CI, Jenkins, etc.

¿CURL es más lento que usar un SDK?

La sobrecarga HTTP es idéntica. cURL no agrega latencia en comparación con los clientes HTTP Python o Node.js. El tiempo de resolución de CAPTCHA domina.

¿Cómo manejo los caracteres especiales en las URL?

Parámetros de codificación de URL: use --data-urlencode con cURL POST o curl -G --data-urlencode "pageurl=...".

Guías relacionadas

• Axios + CaptchaAI (Sin navegador)
• Configuración y autenticación de clave API
• Formatos de respuesta API

Configuración recomendada para su pipeline

Use exactamente la misma configuración de navegador en todos sus entornos de QA, staging y CI. Esto evita que un test funcione en local y falle en CI sin razón aparente.

from selenium import webdriver

def make_driver(headless: bool = True) -> webdriver.Chrome:
    options = webdriver.ChromeOptions()
    if headless:
        options.add_argument('--headless=new')
    options.add_argument('--window-size=1280,800')
    options.add_argument('--lang=es-ES')
    return webdriver.Chrome(options=options)

Mantener viewport, idioma y user-agent por defecto idénticos en todos los runners reduce la varianza y facilita comparar resultados entre ejecuciones de su propio QA.

Cómo se integra CaptchaAI en su pipeline propio

El patrón de integración con CaptchaAI siempre es el mismo, independientemente del lenguaje o framework de pruebas que use:

1. Su test detecta el widget de CAPTCHA en la página de su propia aplicación (formulario de QA, landing de staging, endpoint de preproducción).
2. Su test envía a CaptchaAI los datos públicos del widget (sitekey, URL de la página, tipo de CAPTCHA).
3. CaptchaAI devuelve un token válido para esa página.
4. Su test inyecta ese token en el campo correspondiente y envía el formulario.
5. Su backend verifica el token con el proveedor de CAPTCHA, exactamente igual que con un usuario real.

Este flujo se aplica únicamente a integraciones que usted controla. No se utiliza para sortear protecciones de sitios de terceros.

Métricas y observabilidad

Incluya métricas específicas para los pasos relacionados con CAPTCHA en sus pipelines de QA. Esto le permite detectar regresiones en su propia integración antes de que lleguen a producción:

• Tiempo de resolución por intento — desde la solicitud a CaptchaAI hasta la entrega del token.
• Tasa de éxito por endpoint propio — cuántas verificaciones backend pasan respecto al total de intentos.
• Distribución de errores — agrupados por código (ERROR_*, timeouts internos, fallos de red).
• Latencia extremo a extremo — incluyendo render de la página, resolución de CAPTCHA y respuesta de su backend.

Conserve trazas (logs, capturas, HAR) durante un período razonable para poder reproducir incidentes en su entorno QA cuando un test falle de forma intermitente.

Buenas prácticas en su entorno QA

• Pruebe siempre sobre su propia aplicación o sobre entornos explícitamente autorizados.
• Mantenga una API key de CaptchaAI separada para QA, distinta de la de producción, para no mezclar métricas.
• Defina timeouts y reintentos razonables (backoff exponencial) para no acumular trabajos pendientes en CaptchaAI durante caídas.
• Versione sus snapshots de configuración (sitekey, action, umbrales) junto al código de los tests.
• Revise periódicamente el changelog de su proveedor de CAPTCHA para anticipar cambios que afecten a su propia integración.

Valide sus integraciones CAPTCHA en entornos propios con CaptchaAI.