Resolver reCAPTCHA con getToken: Una solicitud, sin sondeo

TL;DR

• El endpoint getToken de CapSolver puede devolver un resultado de reCAPTCHA compatible en la respuesta a una solicitud.
• Envía clientKey y un objeto de tarea compatible a https://api.capsolver.com/getToken.
• Elige el tipo de tarea para tu variante de reCAPTCHA y proporciona la página, la clave pública del sitio y el contexto correspondiente.
• Lee solution.gRecaptchaResponse después de verificar el resultado de la API; un intercambio HTTP exitoso no es suficiente.
• Un token devuelto aún necesita la verificación normal de la aplicación propietaria. Una solicitud no significa finalización inmediata ni aceptación garantizada.
• La solicitud cURL siguiente se probó contra un fixture HTTP local. No se realizó una resolución en vivo.

Una integración convencional de solucionador de CAPTCHA crea una tarea y luego solicita su resultado. Si estás integrando una tarea de reCAPTCHA compatible y quieres una respuesta directa, el endpoint getToken de CapSolver proporciona otro patrón de solicitud documentado.

La diferencia práctica está en el cliente: envía la tarea y espera el resultado en esa respuesta HTTP. No escribes un bucle de sondeo getTaskResult para este flujo. Esta guía recorre los campos de la tarea, un archivo JSON y un comando cURL, el token devuelto y las verificaciones necesarias antes de que tu aplicación propietaria lo acepte.

¿Qué es la API getToken?

La API getToken es un punto de entrada de resultado directo para los tipos de tarea de reCAPTCHA enumerados en su documentación. Un punto de entrada de API es la dirección para una operación de API específica; usar la ruta correcta selecciona este patrón de solicitud.

La documentación oficial de getToken enumera variantes de tarea de reCAPTCHA v2 y v3 compatibles, incluyendo opciones de Empresa y proxy correspondientes. No infieras soporte para AWS WAF, Turnstile o reconocimiento de imágenes a texto a partir del nombre general del punto de entrada.

El método cambia la recuperación de resultados, no el significado de los parámetros del desafío. Una clave pública de sitio incorrecta o un tipo de tarea no coincidente sigue siendo incorrecto al enviarlo a través de un endpoint directo. Confirma primero la familia de CAPTCHA, luego elige la variante de tarea documentada.

Algunas familias de tareas createTask ya devuelven resultados directamente. La comparación no significa que cada llamada a createTask requiera sondeo.

Paso 1: Identificar la tarea de reCAPTCHA y las claves

Identifica la integración real de reCAPTCHA en tu página antes de construir la solicitud. El ejemplo siguiente usa ReCaptchaV3TaskProxyLess, por lo que sus campos deben describir una integración v3.

Mantén separadas las tres funciones clave. La clave de API de CapSolver autoriza la solicitud de resolución. La clave pública de reCAPTCHA identifica la integración de la página. La clave secreta de verificación del propietario del sitio pertenece al servidor de la aplicación; no es la clientKey o websiteKey en esta solicitud.

Para v3, verifica la acción esperada así como la clave pública. La documentación de la tarea de reCAPTCHA v3 explica los campos de la tarea, incluido pageAction. La acción de muestra submit es un marcador de posición para la acción que realmente utiliza tu formulario.

La documentación de reCAPTCHA v3 de Google describe la evaluación basada en acciones. Un token para una acción diferente no debe tratarse como una prueba exitosa de la forma deseada. Mantén alineadas la acción de la solicitud y la acción esperada por el backend.

Si la página usa v2 o Enterprise, selecciona su tipo de tarea y campos documentados en lugar de cambiar solo el título de la integración. Evita copiar una acción de v3 en una tarea diferente sin verificar sus requisitos.

Paso 2: Guardar la solicitud JSON documentada

Guarda el siguiente JSON como request.json. Su envoltura sigue la documentación de getToken, y los campos de tarea siguen la guía de v3. Estos son valores de muestra; reemplázalos con tus propias configuraciones para una verificación en vivo.

{
  "clientKey": "TU_CLAVE_DE_API",
  "task": {
    "type": "ReCaptchaV3TaskProxyLess",
    "websiteURL": "https://tu-pagina-de-prueba.ejemplo/form",
    "websiteKey": "TU_CLAVE_PÚBLICA_DEL_SITIO",
    "pageAction": "submit"
  }
}

Reemplaza cada marcador de posición antes de contactar al endpoint en vivo. El dominio de ejemplo identifica intencionalmente una página de prueba propia y no es un objetivo de CAPTCHA funcional. La clave pública y la acción deben provenir de la integración configurada en esa página.

Un archivo JSON hace que la carga útil sea fácil de inspeccionar sin un largo comando de shell. Una vez que contenga una credencial real, restringe el acceso a ese archivo y manténlo fuera del control de versiones. Usa un método adecuado de gestión de secretos al mover esta solicitud a una aplicación.

El nombre de la tarea sin proxy describe la variante de tarea del proveedor. No elimina la necesidad de un contexto de página correcto, ni implica que cada configuración de desafío use parámetros idénticos. Usa la documentación de la tarea como referencia de campo.

Paso 3: Enviar una solicitud con cURL

Ejecuta este comando desde el directorio que contiene request.json. Sus indicadores y carga útil se probaron contra un fixture HTTP local, pero el endpoint en vivo aún requiere tu credencial de resolución y parámetros de página propia:

curl --silent --show-error --connect-timeout 10 --max-time 90 \
  --json @request.json \
  https://api.capsolver.com/getToken

El comando usa la opción de solicitud JSON de cURL para enviar el archivo como cuerpo. La documentación oficial de cURL JSON explica la opción y sus encabezados de solicitud. Usa una versión de cURL que soporte --json.

Los valores de tiempo de conexión y tiempo total son elecciones locales para este ejemplo. No son un compromiso del servicio del proveedor. El endpoint puede mantener la solicitud mientras resuelve la tarea, por lo que una respuesta directa no es sinónimo de una respuesta inmediata.

Verifica tanto el resultado HTTP como el contenido JSON. Este comando muestra el cuerpo de la respuesta y los errores de transporte; no es un manejador de errores completo de la aplicación. cURL puede completar un intercambio HTTP incluso cuando el JSON devuelto describe un error del proveedor. Una aplicación debe ramificar según los campos devueltos en lugar de buscar una cadena que parezca un token en la salida terminal.

No agregues un bucle de sondeo a este comando como paso siguiente predeterminado. El flujo elegido está específicamente diseñado para devolver su resultado directamente. Si tu aplicación necesita seguimiento de tareas con recuperación de resultados separada, selecciona e implementa el flujo documentado de createTask desde el principio.

Canjea tu código de bonificación de CapSolver

¡Aumenta tu presupuesto de automatización instantáneamente!
Usa el código de bonificación CAP26 al recargar tu cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Canjéalo ahora en tu Panel de CapSolver

Paso 4: Leer la respuesta directa del token

Lee solution.gRecaptchaResponse solo después de confirmar que el resultado informa éxito y listo. La siguiente forma de respuesta es ilustrativa; el valor del token es un marcador de posición, no un token devuelto por una resolución en vivo.

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "VALOR_DE_TOKEN_ILUSTRATIVO"
  }
}

Los valores importantes son el indicador de error, el estado de listo y el campo de resultado no vacío. No trates un objeto de respuesta, identificador de tarea o estado de HTTP exitoso como intercambiables con un token utilizable. También pueden aparecer campos opcionales; retén solo los que necesite tu integración.

En caso de fallo del proveedor, inspecciona el código de error y la descripción descrita por la referencia de errores de API. Mantén suficiente información para distinguir un parámetro inválido de un problema de cuenta o un fallo de transporte, excluyendo la credencial y el token de los registros habituales.

Un endpoint directo simplifica la máquina de estados del cliente, pero la conexión sigue siendo parte de la operación. Si el cliente se agota o pierde la respuesta, su resultado podría ser incierto. La solicitud podría haber llegado al proveedor antes de que ocurriera el error local. No describas una nueva presentación inmediata como reanudar la primera tarea a menos que la API documente explícitamente ese comportamiento.

Paso 5: Validar el token en tu aplicación propia

Un token devuelto debe pasar la verificación normal de la aplicación antes de que la operación cuente como exitosa. El resultado del solucionador y la aceptación de la aplicación son eventos separados.

La documentación de verificación del lado del servidor de Google indica que los tokens de respuesta expiran después de dos minutos y solo pueden verificarse una vez. Obtén el token cerca de la operación deseada y evita probar el mismo token repetidamente a través del endpoint de verificación.

Para el flujo estándar de verificación, la clave secreta del propietario del sitio permanece en el backend. Verifica las propiedades de respuesta relevantes para tu integración, incluida la hostname esperada y, para v3, la acción y la política de puntuación. Las aplicaciones empresariales deben usar su integración correspondiente de verificación o evaluación en lugar de asumir que el ejemplo estándar cubre cada variante.

Considera un formulario propio con una acción submit. Una prueba útil primero confirma que la tarea solicitada describe esa acción, luego envía el token devuelto a través del camino normal del formulario y finalmente afirma que la operación de prueba deseada fue aceptada. Un valor de token impreso en una terminal prueba solo que se recibió una cadena.

Para la interpretación de la puntuación, consulta la guía separada de puntuación de reCAPTCHA v3. Cambiar los puntos de entrada de recuperación no establece una puntuación específica ni elimina las reglas de aceptación del backend.

¿Cuándo usar getToken en lugar de sondear?

Usa getToken cuando la variante de tarea sea compatible y el cliente pueda mantener una solicitud abierta mientras espera el resultado. Esto se ajusta a una pequeña integración directa en la que el siguiente paso de la aplicación consume inmediatamente el token devuelto.

Usa la API createTask y su flujo de resultado documentado cuando tu aplicación necesite específicamente la creación de tareas y la recuperación de resultados separados. Por ejemplo, un trabajador que persista los identificadores de tarea entre pasos puede organizarse alrededor de ese patrón.

Elige según el ciclo de vida del cliente en lugar de asumir que un endpoint es más rápido universalmente. Una solicitud directa elimina el código de sondeo del cliente, pero eso solo no prueba una menor latencia de resolución. Un trabajador en segundo plano también puede necesitar controles que no se proporcionen con una sola llamada HTTP sincrónica.

No cambies familias de CAPTCHA solo para ajustarte a un endpoint preferido. La página determina el tipo de desafío. Si la familia no está listada para getToken, sigue la API documentada de esa familia.

¿Qué establece la prueba del ejemplo?

El comando cURL se ejecutó contra un fixture HTTP local con solo el endpoint sustituido. El fixture verificó la ruta POST, el tipo de contenido JSON y la carga útil analizada exacta, luego devolvió una respuesta lista suministrada. Esto verificó el comando basado en archivo y el manejo de respuesta directa.

No se usó ninguna clave de resolución real, tarea pagada o formulario protegido por reCAPTCHA. El token del fixture no es válido para ninguna aplicación. Una integración en vivo aún necesita la clave del sitio real, la acción, la credencial de resolución y el resultado de verificación de la aplicación propia.

Antes de expandir más allá de una sola prueba, registra qué variante de tarea y campos funcionaron con la página propia. Si la prueba falla, identifica si la falla ocurrió durante la presentación de la tarea, la recuperación del resultado, la verificación del token o la operación final de la aplicación. Estas distinciones te dan un punto de partida concreto sin agregar un bucle de sondeo innecesario.

Try CapSolver con una tarea de reCAPTCHA compatible para completar el paso de verificación en vivo. Mantén los mismos campos de solicitud y verificaciones de aceptación al mover la solicitud probada de cURL a tu aplicación.

Preguntas frecuentes

P: ¿Requiere getToken getTaskResult?

El flujo directo descrito aquí devuelve el resultado en la respuesta de getToken, por lo que el cliente no sondea getTaskResult. El seguimiento de tareas con recuperación separada pertenece a la integración correspondiente de createTask.

P: ¿Puede resolver getToken cualquier tipo de CAPTCHA?

Usa solo los tipos de tarea enumerados en su documentación. Las variantes de reCAPTCHA documentadas no implican soporte para familias no relacionadas como AWS WAF o reconocimiento de imágenes.

P: ¿Es más rápido getToken que createTask?

Esta guía no establece una ventaja de latencia. La diferencia de diseño observable es que el cliente espera un resultado directo en lugar de implementar un bucle de recuperación separado.

P: ¿Es websiteKey la clave secreta de verificación privada?

No. Es la clave pública del sitio para la integración de la página. La clave secreta de verificación del sitio permanece en el backend, mientras que clientKey es la credencial del servicio de resolución.

P: ¿Por qué podría fallar la verificación de un token devuelto?

Verifica la caducidad, el uso previo, el contexto de la página esperado, la acción y la respuesta de verificación de la aplicación. Recibir un token del solucionador no garantiza que la aplicación lo acepte.

P: ¿El token de muestra fue producido por una resolución en vivo?

No. La respuesta mostrada es ilustrativa, y el comando se probó con un fixture HTTP local. Realiza una prueba en vivo separada con tu clave de resolución y aplicación propia.