ReCAPTCHA

Descripción General

Google reCAPTCHA es el sistema de captcha más popular del mundo, utilizado por millones de sitios web para protegerse contra spam y bots. Achicaptcha actualmente admite reCAPTCHA v2 con una alta tasa de éxito.

⚠️

Actualmente Achicaptcha solo admite reCAPTCHA v2. reCAPTCHA v3 y Enterprise aún no son compatibles.

ReCAPTCHA

1. Crear Tarea

Solicitud

POST https://api.achicaptcha.com/createTask

Parámetros

Nombre del Parámetro	Tipo de Dato	¿Requerido?	Descripción
`clientKey`	string	sí	Clave API
`task.type`	string	sí	RecaptchaV2TaskProxyless para resolución ultrarrápida RecaptchaV2TaskProxylessNormal para resolución normal
`task.websiteURL`	string	sí	URL del sitio web que contiene el captcha
`task.websiteKey`	string	sí	Clave del sitio reCAPTCHA

Ejemplo de Solicitud

POST /createTask HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "TU_CLAVE_API",
  "task": {
    "type": "RecaptchaV2TaskProxyless",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}

Respuesta

Cuando tiene éxito, el servidor devuelve errorId = 0 y taskId

{
  "errorId": 0,
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

2. Obtener Resultado

Solicitud

POST https://api.achicaptcha.com/getTaskResult

Parámetros

Nombre del Parámetro	Tipo de Dato	¿Requerido?	Descripción
`clientKey`	string	sí	Clave API
`taskId`	string	sí	TaskId obtenido de (1)

Ejemplo de Solicitud

POST /getTaskResult HTTP/1.1
Host: api.achicaptcha.com
Content-Type: application/json
 
{
  "clientKey": "TU_CLAVE_API",
  "taskId": "f2fc70d6-c76b-4fba-9480-205ac1fe9fb9"
}

Respuesta

{
  "errorId": 0,
  "status": "ready",
  "solution": "03AGdBq27QGA96FJRo3mtz..."
}

Explicación del Estado

errorId = 0 y status = ready: Resuelto exitosamente, lee el resultado en solution
errorId = 0 y status = processing: Resolviendo captcha, espera 2 segundos e intenta de nuevo
errorId > 0: Error del sistema, devuelve código de error y descripción

Ejemplos de Integración

import requests
import time
 
def solve_recaptcha_v2(website_url, website_key, api_key='TU_CLAVE_API'):
    # Paso 1: Crear tarea
    create_task_url = 'https://api.achicaptcha.com/createTask'
    create_task_payload = {
        'clientKey': api_key,
        'task': {
            'type': 'RecaptchaV2TaskProxyless',
            'websiteURL': website_url,
            'websiteKey': website_key
        }
    }
    
    response = requests.post(create_task_url, json=create_task_payload)
    result = response.json()
    
    if result['errorId'] != 0:
        raise Exception(result['errorDescription'])
    
    task_id = result['taskId']
    
    # Paso 2: Obtener resultado
    get_result_url = 'https://api.achicaptcha.com/getTaskResult'
    
    while True:
        time.sleep(2)  # Esperar 2 segundos
        
        get_result_payload = {
            'clientKey': api_key,
            'taskId': task_id
        }
        
        response = requests.post(get_result_url, json=get_result_payload)
        result = response.json()
        
        if result['errorId'] != 0:
            raise Exception(result['errorDescription'])
        
        if result['status'] == 'ready':
            return result['solution']
        
        # Si status == 'processing', continuar el bucle
 
# Uso
website_url = 'https://www.google.com/recaptcha/api2/demo'
website_key = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-'
token = solve_recaptcha_v2(website_url, website_key, 'TU_CLAVE_API')
print('Token reCAPTCHA:', token)

Códigos de Error Comunes

Código de Error	Descripción	Notas
0	éxito	Éxito
1	procesando	Procesando
2	faltan campos requeridos	Faltan campos requeridos, verifica los parámetros nuevamente
3	tarea no compatible	Tipo de tarea no compatible
4	creación de tarea fallida	Creación de tarea fallida
5	la clave del cliente no existe	La clave API no existe, verifica la clave API nuevamente
6	saldo de cuenta insuficiente	Saldo de cuenta insuficiente, agrega más créditos
7	tarea fallida, por favor crea una nueva tarea	Tarea fallida, por favor crea una nueva tarea
8	el ID de tarea no existe	El ID de tarea no existe

Mejores Prácticas

Para obtener los mejores resultados al usar la API de Achicaptcha, sigue estos principios:

1. Validar Clave del Sitio

Verifica la clave del sitio antes de enviar la solicitud
Asegúrate de que la clave del sitio obtenida del atributo data-sitekey sea precisa
Verifica que la URL del sitio web coincida con la página que contiene el captcha

2. Manejar Tiempos de Espera

El token tiene un tiempo de expiración (generalmente 120 segundos)
Usa el token inmediatamente después de recibirlo
No almacenes en caché el token durante demasiado tiempo

3. Intervalo de Sondeo

Espera al menos 2 segundos entre verificaciones de resultado
No envíes spam a la API con demasiadas solicitudes consecutivas
Establece un tiempo de espera para evitar bucles infinitos (recomendado 120 segundos)

4. Lógica de Reintento

Implementa reintento para errores temporales como ERROR_NO_SLOT_AVAILABLE
Usa retroceso exponencial al reintentar
Limita los intentos máximos de reintento

5. Seguridad de la Clave API

No codifiques la clave API en el código
Usa variables de entorno
No expongas la clave API en el lado del cliente

Enlaces útiles:

Imagen Captcha Geetest