Como resolver qualquer CAPTCHA no HyperBrowser usando o CapSolver (Guia Completo de Configuração)

npm install @hyperbrowser/sdk playwright-core

mkdir -p capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d capsolver-extension/

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  // sua chave aqui
  useCapsolver: true,
  // ... restante da configuração
};

ls capsolver-extension/manifest.json
# Deve existir

cd capsolver-extension && zip -r ../capsolver-extension.zip . && cd ..

import { Hyperbrowser } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

// Carregue a extensão do CapSolver (operação única)
const ext = await client.extensions.create({
  filePath: "capsolver-extension.zip",
});

console.log("ID da Extensão:", ext.id);
// Salve este ID — você o reutilizará para cada sessão

const session = await client.sessions.create({
  extensionIds: [ext.id],
  useProxy: true, // Requer plano pago — omita para o plano gratuito
  solveCaptchas: false, // Usando o CapSolver em vez da resolução nativa
});

console.log("ID da Sessão:", session.id);
console.log("URL do WebSocket:", session.wsEndpoint);

import { chromium } from "playwright-core";

const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

// Navegue até uma página protegida por CAPTCHA
await page.goto("https://www.google.com/recaptcha/api2/demo");

// Aguarde a extensão do CapSolver detectar e resolver o CAPTCHA
await page.waitForTimeout(30000);

// Submeta o formulário
await page.click("#recaptcha-demo-submit");
await page.waitForLoadState("networkidle");

// Verifique o sucesso
const result = await page.textContent("body");
console.log("Resultado:", result);
// Esperado: contém "Verification Success"

await browser.close();
await client.sessions.stop(session.id);

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";

const HYPERBROWSER_API_KEY = process.env.HYPERBROWSER_API_KEY!;
const CAPSOLVER_EXTENSION_ID = process.env.CAPSOLVER_EXTENSION_ID; // Opcional: reutilize um ID existente

async function main() {
  const client = new Hyperbrowser({ apiKey: HYPERBROWSER_API_KEY });

  // Passo 1: Carregar extensão (ou reutilizar ID existente)
  let extensionId = CAPSOLVER_EXTENSION_ID;

  if (!extensionId) {
    const ext = await client.extensions.create({
      filePath: "capsolver-extension.zip",
    });
    extensionId = ext.id;
    console.log("Extensão carregada:", extensionId);
  }

  // Passo 2: Criar sessão com extensão do CapSolver
  const session = await client.sessions.create({
    extensionIds: [extensionId],
    useProxy: true, // Requer plano pago — omita para o plano gratuito
    solveCaptchas: false,
  });

  console.log("Sessão iniciada:", session.id);

  // Passo 3: Conectar o Playwright
  const browser = await chromium.connectOverCDP(session.wsEndpoint);
  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();

  try {
    // Passo 4: Navegar até a página de demonstração do reCAPTCHA
    console.log("Navegando até a página de demonstração do reCAPTCHA...");
    await page.goto("https://www.google.com/recaptcha/api2/demo");

    // Passo 5: Aguardar o CapSolver resolver o CAPTCHA
    console.log("Aguardando o CapSolver resolver o CAPTCHA...");
    await page.waitForTimeout(30000);

    // Passo 6: Submeter o formulário
    console.log("Submetendo o formulário...");
    await page.click("#recaptcha-demo-submit");
    await page.waitForLoadState("networkidle");

    // Passo 7: Verificar o resultado
    const bodyText = await page.textContent("body");

    if (bodyText?.includes("Verification Success")) {
      console.log("CAPTCHA resolvido com sucesso!");
    } else {
      console.log("Resultado da verificação:", bodyText?.slice(0, 200));
    }
  } finally {
    await browser.close();
    await client.sessions.stop(session.id);
    console.log("Sessão parada.");
  }
}

main().catch(console.error);

HYPERBROWSER_API_KEY=your_key npx tsx captcha-test.ts

  Configuração Única
  ═══════════════════════════════════════════════════════

  capsolver-extension/           HyperBrowser Cloud
  ├── manifest.json    ──ZIP──►  POST /extensions
  ├── assets/config.js           │
  └── background.js              ▼
                                 extensionId: "ext_abc123"
                                 (armazenado, reutilizável)

  Fluxo por Sessão
  ═══════════════════════════════════════════════════════

  Seu Script                    HyperBrowser Cloud
  ─────────────────────────────────────────────────────
  sessions.create({       ──►    Inicia Chromium em nuvem
    extensionIds: [id],          │
    useProxy: true               ├── Carrega extensão do CapSolver
  })                             ├── Aplica proxy + stealth
                                 ▼
                          ◄──    wsEndpoint (URL de WebSocket)

  playwright.connectOverCDP()    Conecta-se ao navegador em nuvem
       │
       ▼
  page.goto(target_url)   ──►   Chromium carrega a página
                                 ┌─────────────────────────────┐
                                 │  Página com widget CAPTCHA   │
                                 │                              │
                                 │  Extensão do CapSolver:        │
                                 │  1. Script de conteúdo detecta  │
                                 │     tipo de CAPTCHA na página   │
                                 │  2. Serviço de trabalho chama  │
                                 │     API do CapSolver            │
                                 │  3. Token de solução recebido   │
                                 │  4. Token injetado no campo   │
                                 │     de formulário oculto        │
                                 └─────────────────────────────┘
                                      │
  page.waitForTimeout(30s)            │ (a resolução acontece aqui)
       │                              │
       ▼                              ▼
  page.click("Submit")    ──►   Formulário é submetido COM token válido
                                      │
                          ◄──         ▼
                                 Google demo: "Verification Success!"

// Completo: extensão do CapSolver
const session = await client.sessions.create({
  extensionIds: [capsolverExtId],
  solveCaptchas: false,
  useProxy: true, // Requer plano pago — omita para o plano gratuito
});

// Segurança dupla: ambos ativados
const session = await client.sessions.create({
  extensionIds: [capsolverExtId],
  solveCaptchas: true, // Resolução nativa lida com Turnstile/reCAPTCHA
  useProxy: true, // Requer plano pago — omita para o plano gratuito
  // Extensão do CapSolver lida com AWS WAF, GeeTest, etc.
});

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";
const HYPERBROWSER_API_KEY = process.env.HYPERBROWSER_API_KEY!;
const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY!;

async function solveCaptchaViaAPI(
  pageUrl: string,
  siteKey: string
): Promise<string> {
  // Criar tarefa
  const createRes = await fetch("https://api.capsolver.com/createTask", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      clientKey: CAPSOLVER_API_KEY,
      task: {
        type: "ReCaptchaV2TaskProxyLess",
        websiteURL: pageUrl,
        websiteKey: siteKey,
      },
    }),
  });
  const { taskId, errorDescription } = await createRes.json();
  if (!taskId) throw new Error(`createTask falhou: ${errorDescription}`);

  // Verificar resultado
  for (let i = 0; i < 40; i++) {
    await new Promise((r) => setTimeout(r, 3000));
    const resultRes = await fetch("https://api.capsolver.com/getTaskResult", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clientKey: CAPSOLVER_API_KEY, taskId }),
    });
    const result = await resultRes.json();
    if (result.status === "ready") {
      return result.solution.gRecaptchaResponse;
    }
  }
  throw new Error("Tempo esgotado para resolver");
}

async function main() {
  const client = new Hyperbrowser({ apiKey: HYPERBROWSER_API_KEY });

  // Nenhuma extensão necessária — apenas uma sessão normal
  const session = await client.sessions.create({
    solveCaptchas: false,
  });

  const browser = await chromium.connectOverCDP(session.wsEndpoint);
  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();

  try {
    await page.goto("https://www.google.com/recaptcha/api2/demo");

    // Detectar sitekey do DOM
    const siteKey = await page.evaluate(() => {
      const el = document.querySelector(".g-recaptcha[data-sitekey]");
      return el?.getAttribute("data-sitekey") ?? "";
    });
    console.log("Sitekey:", siteKey);

    // Resolver via API CapSolver
    const token = await solveCaptchaViaAPI(page.url(), siteKey);
    console.log("Token recebido, comprimento:", token.length);

    // Injetar token
    await page.evaluate((t) => {
      const textarea = document.querySelector(
        'textarea[name="g-recaptcha-response"]'
      );
      if (textarea) (textarea as HTMLTextAreaElement).value = t;
    }, token);

    // Enviar
    await page.click("#recaptcha-demo-submit");
    await page.waitForLoadState("networkidle");

    const body = await page.textContent("body");
    console.log(
      body?.includes("Verification Success")
        ? "CAPTCHA resolvido via API!"
        : body?.slice(0, 200)
    );
  } finally {
    await browser.close();
    await client.sessions.stop(session.id);
  }
}

main().catch(console.error);
``

### Quando usar API vs Extensão

| | Extensão | API |
|---|---|---|
| **Configuração** | Carregar ZIP uma vez, reutilizar ID | Nenhuma configuração — apenas chave de API |
| **Detecção** | Automática (script de conteúdo) | Manual (consultar DOM para sitekey) |
| **Injeção de token** | Automática | Manual (avaliar JS) |
| **Controle** | Opaque — extensão lida com tudo | Controle total sobre cada etapa |
| **Melhor para** | Automação "defina e esqueça" | Lógica de resolução personalizada, estratégias de repetição |

---

## Solução de Problemas

### Extensão Não Carregada na Sessão

**Sintoma**: CAPTCHA não é resolvido; a página se comporta como se nenhuma extensão estivesse presente.

**Possíveis causas**:
1. **ID de extensão incorreto** — Verifique se o ID retornado por `client.extensions.create()` está sendo passado corretamente
2. **ZIP corrompido** — Re-zipe o diretório da extensão (certifique-se de que `manifest.json` esteja no topo do ZIP, não em uma subpasta)
3. **Chave de API ausente** — Verifique se `assets/config.js` tem uma chave de CapSolver válida antes de zipar

**Solução**:
```bash
# Verificar estrutura do ZIP -- manifest.json deve estar no topo
unzip -l capsolver-extension.zip | head -20
# Deve mostrar: manifest.json (NÃO capsolver-extension/manifest.json)

try {
  const browser = await chromium.connectOverCDP(session.wsEndpoint);
} catch (err) {
  console.log("Sessão expirada, criando nova...");
  const newSession = await client.sessions.create({
    extensionIds: [extensionId],
    useProxy: true, // Requer plano pago — omita para plano gratuito
  });
  const browser = await chromium.connectOverCDP(newSession.wsEndpoint);
}

// Carregar uma vez
const ext = await client.extensions.create({ filePath: "capsolver-extension.zip" });
const CAPSOLVER_EXT_ID = ext.id;

// Reutilizar em cada sessão
for (const url of targetUrls) {
  const session = await client.sessions.create({
    extensionIds: [CAPSOLVER_EXT_ID],
    useProxy: true, // Requer plano pago — omita para plano gratuito. Proxies residenciais reduzem a frequência de CAPTCHA
  });
  // ... automatizar
  await client.sessions.stop(session.id);
}

const session = await client.sessions.create({
  extensionIds: [extensionId],
  useProxy: true, // Requer plano pago — omita para plano gratuito. Proxies residenciais reduzem a frequência de CAPTCHA
});

import axios from "axios";

async function checkBalance(apiKey: string): Promise<number> {
  const response = await axios.post("https://api.capsolver.com/getBalance", {
    clientKey: apiKey,
  });
  return response.data.balance || 0;
}

const balance = await checkBalance(process.env.CAPSOLVER_API_KEY!);
if (balance < 1) {
  console.warn("Saldo do CapSolver baixo! Recarregue em capsolver.com");
}

try {
  // ... seu código de automação
} finally {
  await browser.close();
  await client.sessions.stop(session.id);
}

# Atualize a chave em config.js, depois:
cd capsolver-extension && zip -r ../capsolver-extension.zip . && cd ..

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: session.wsEndpoint,
});