CapMonster Cloud API
Extensión para navegadores
En este artículo hemos intentado responder a todas las preguntas clave. Para empezar a resolver la tarea, primero hay que determinar qué sistema de protección se está utilizando. Para ello, puedes consultar la lista de captchas y sistemas de protección antibot más populares, donde se muestran ejemplos visuales y señales clave que te ayudarán a identificar rápidamente con qué estás tratando.
Si descubres que tu sitio web utiliza reCAPTCHA v2 Enterprise, el siguiente paso será analizar con más detalle sus propiedades y su funcionamiento. En este mismo artículo también puedes consultar la guía de integración de reCAPTCHA v2 Enterprise para comprender por completo cómo funciona en tu sitio. Esto te permitirá no solo entender la protección actual, sino también planificar correctamente su mantenimiento.
Al probar formularios que incluyen reCAPTCHA v2 Enterprise, normalmente debes verificar que la captcha funcione y esté integrada correctamente.
Puedes comprobar manualmente la captcha incrustada en tu sitio.
Para la resolución automática puedes usar herramientas como CapMonster Cloud, que reciben los parámetros de la captcha, los procesan en sus servidores y devuelven un token listo para usar. Inserta ese token en el formulario para pasar la verificación sin interacción del usuario.
Trabajar con CapMonster Cloud mediante la API suele implicar los siguientes pasos:
Creación de la tarea
Enviar una solicitud APITu solicitud para resolver reCAPTCHA v2 Enterprise debe incluir:
type - RecaptchaV2EnterpriseTask;
websiteURL - la URL donde aparece la captcha;
websiteKey - el sitekey mostrado en esa página;
enterprisePayload - envíalo si tu widget reCAPTCHA Enterprise añade un campo s al objeto que se pasa a grecaptcha.enterprise.render junto con el sitekey;
pageAction - el valor action que el widget envía a Google. Valor por defecto: verify.
https://api.capmonster.cloud/createTask{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTask",
"websiteURL": "https://mydomain.com/page-with-recaptcha-enterprise",
"websiteKey": "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd",
"pageAction": "verify",
"enterprisePayload": {
"s": "SOME_ADDITIONAL_TOKEN"
}
}
}
{
"errorId":0,
"taskId":407533072
}
Recepción del resultadohttps://api.capmonster.cloud/getTaskResult{
"clientKey":"API_KEY",
"taskId": 407533072
}
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AFcWeA66ZARdA5te7acD9vSwWE2hEQ2-B2aqFxm455iMA-g-Jis..."
}
}
Colocar el token en la páginaimport { chromium } from 'playwright';
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV2EnterpriseRequest } from '@zennolab_com/capmonstercloud-client';
(async () => {
const browser = await chromium.launch({ headless: false });
const context = await browser.newContext();
const page = await context.newPage();
// 2. Abre la página con la captcha
await page.goto('https://example.com');
// 3. Crea el cliente de CapMonster Cloud
const cmcClient = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: '<your_capmonster_cloud_api_key>' })
);
// 4. Configura la petición que resuelve la captcha
const recaptchaRequest = new RecaptchaV2EnterpriseRequest({
websiteURL: page.url(),
websiteKey: '6Lf76sUnAAAAAIKLuWNyegRsFUfmI-3Lex3xT5N'
// enterprisePayload: { s: 'SOME_ADDITIONAL_TOKEN' } // Parámetro enterprise opcional
});
// 5. Resuelve la captcha con CapMonster
const solution = await cmcClient.Solve(recaptchaRequest);
const token = solution.solution.gRecaptchaResponse;
console.log('Token del captcha:', token);
// 6. Inserta el token en un campo oculto
await page.evaluate((t) => {
const el = document.getElementById('g-recaptcha-response');
if (el) el.value = t;
}, token);
// 7. (Opcional) Envía el formulario — sustituye por el selector adecuado
await page.click('button[data-action="submit"]');
await page.waitForTimeout(5000);
await browser.close();
})();Como reCAPTCHA Enterprise se ejecuta en Google Cloud, primero debes crear un proyecto en su consola:
1. Ve a la Google Cloud Console.
2. En el menú superior elige un proyecto existente o haz clic en Nuevo proyecto.
3. Introduce un nombre de proyecto, especifica tu organización y confirma la creación.
4. Abre la página de la API: reCAPTCHA Enterprise API y haz clic en Habilitar.
5. Ve a Crear clave en la consola y haz clic en Crear clave.
6. Configura los ajustes básicos:
Luego abre Configuración adicional, activa ¿Vas a usar desafíos? y habilita Checkbox Challenge.
7. Haz clic en Crear. Recibirás una clave que debes añadir a tu sitio para activar la protección.
8. Añade el script a tu página.
Fragmento de HTML de ejemplo que puedes incrustar en tu sitio<html>
<head>
<title>reCAPTCHA demo: Simple page</title>
<script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
</head>
<body>
<form action="" method="POST">
<div class="g-recaptcha" data-sitekey="YOUR_SITEKEY" data-action="LOGIN"></div>
<br/>
<input type="submit" value="Submit">
</form>
</body>
</html>9. Valida la respuesta en el servidor.
Ejemplo en PHPEl token (g-recaptcha-response) se envía al backend.
Es válido durante 2 minutos, ¡así que verifícalo en cuanto lo recibas! Para una comunicación segura con la API recomendamos las bibliotecas oficiales de Google Cloud:
<?php
require 'vendor/autoload.php';
// Instala las bibliotecas de Google Cloud mediante Composer
use Google/Cloud/RecaptchaEnterprise/V1/RecaptchaEnterpriseServiceClient;
use Google/Cloud/RecaptchaEnterprise/V1/Event;
use Google/Cloud/RecaptchaEnterprise/V1/Assessment;
use Google/Cloud/RecaptchaEnterprise/V1/CreateAssessmentRequest;
use Google/Cloud/RecaptchaEnterprise/V1/TokenProperties/InvalidReason;
/**
* Valida el token de reCAPTCHA Enterprise y obtén la puntuación de riesgo.
*
* @param string $recaptchaKey Clave de reCAPTCHA de tu sitio/app
* @param string $token Token recibido desde el cliente
* @param string $projectId ID del proyecto de Google Cloud
* @param string $action Nombre de la acción asociado al token
*/
function create_assessment(string $recaptchaKey, string $token, string $projectId, string $action): void {
$client = new RecaptchaEnterpriseServiceClient();
$projectName = $client->projectName($projectId);
// Crea el evento de evaluación (assessment)
$event = (new Event())->setSiteKey($recaptchaKey)->setToken($token);
$assessment = (new Assessment())->setEvent($event);
$request = (new CreateAssessmentRequest())->setParent($projectName)->setAssessment($assessment);
try {
$response = $client->createAssessment($request);
if (!$response->getTokenProperties()->getValid()) {
echo 'El token no es válido: ' . InvalidReason::name($response->getTokenProperties()->getInvalidReason());
return;
}
if ($response->getTokenProperties()->getAction() === $action) {
echo 'Puntuación de riesgo: ' . $response->getRiskAnalysis()->getScore();
} else {
echo 'La acción en la etiqueta reCAPTCHA no coincide con el valor esperado';
}
} catch (Exception $e) {
echo 'Error al comprobar reCAPTCHA: ' . $e->getMessage();
}
}
// Llama a la función con las variables
create_assessment(
'YOUR_SITE_KEY',
'YOUR_USER_RESPONSE_TOKEN',
'YOUR_PROJECT_ID',
'YOUR_RECAPTCHA_ACTION'
);
?>
Si has heredado un sitio web que ya tiene un captcha u otro sistema de protección instalado y no tienes acceso al código, no pasa nada. Identificar qué tecnología se está utilizando es bastante sencillo. Para comprobar que todo funciona correctamente, puedes usar el servicio de reconocimiento CapMonster Cloud en un entorno de pruebas aislado, para asegurarte de que el mecanismo de procesamiento de tokens y la lógica de verificación funcionan correctamente.
En el caso de reCAPTCHA v2 Enterprise, basta con detectar el sistema, analizar su comportamiento y confirmar que la protección funciona correctamente. En el artículo hemos mostrado cómo identificar reCAPTCHA v2 Enterprise y dónde encontrar las instrucciones para su integración o reconfiguración, de modo que puedas mantener la protección con confianza y controlar su funcionamiento.
