Guia do Tencent Captcha (TCaptcha)

O Tencent Captcha é o serviço de verificação da Tencent Cloud para detectar atividades automatizadas em sites. Ele pode apresentar ao visitante um quebra-cabeça com controle deslizante, um desafio com imagens ou um teste de áudio. Dependendo da avaliação de risco, alguns visitantes podem seguir sem resolver um desafio.

Os sites usam o Tencent Captcha para proteger cadastros, logins e outras ações sensíveis. O serviço também ajuda a limitar spam, fraudes e acessos automatizados indesejados ao conteúdo.

Pontos principais

• A Tencent Cloud documenta cinco modos de verificação: controle deslizante, desafio gráfico, áudio, verificação inteligente e verificação sem interação.
• A segunda versão do script usa novos nomes de arquivo e um novo domínio.
• Quando o usuário resolve o desafio, a Tencent retorna ticket e randstr para verificação no servidor. Os tickets emitidos em caso de falha precisam de tratamento separado.
• O CapMonster Cloud usa uma tarefa CustomTask da classe TenDI. Os parâmetros obrigatórios específicos do site são websiteURL e websiteKey.
• Tencent Captcha e NetEase YiDun são produtos de empresas diferentes.

Termos e definições

• TCaptcha — nome abreviado do Tencent Captcha, também usado nos nomes dos arquivos da primeira versão do script.
• captchaAppId (aid) — identificador de uma configuração de captcha no console da Tencent Cloud. Nas requisições de rede, aparece como aid.
• ticket — valor retornado quando ret é 0. O backend precisa validá-lo e tratar também as respostas emitidas em caso de falha.
• randstr — sequência aleatória associada a uma tentativa. É enviada com o ticket para verificação no servidor.
• Desafio com controle deslizante — captcha da Tencent em que o usuário move o controle até a peça se encaixar no recorte.

Como o Tencent Captcha é exibido e carregado

Para resolver o captcha deslizante da Tencent, o usuário arrasta o controle até a peça se encaixar no recorte.

A visão geral do produto da Tencent Cloud também apresenta outros quatro modos de verificação.

Captcha gráfico: o usuário clica nas formas da imagem na ordem indicada. Esse modo é usado em cenários que exigem mais segurança.

Captcha de áudio: o usuário digita o que ouve na gravação. Esse modo serve principalmente como recurso de acessibilidade.

Verificação inteligente: o sistema só exibe um desafio para usuários que considera suspeitos, de forma semelhante ao reCAPTCHA do Google.

Verificação sem interação: o usuário não recebe um desafio. O backend retorna o resultado com base na avaliação de risco.

A Tencent analisa trajetórias e identifica características, além de fazer verificações para detectar emuladores.

Como o widget carrega

Carregue o script do CAPTCHA pela URL oficial da Tencent em vez de hospedar uma cópia. O guia da Tencent usa uma tag script comum e dispensa o import() dinâmico do JavaScript. Há duas versões do script:

• Versão original: o guia de migração do JavaScript da Tencent lista https://sg.captcha.qcloud.com/TCaptcha-global.js e https://global.captcha.gtimg.com/TCaptcha-global.js como os endereços antigos do script. A documentação do CapMonster Cloud também cita TCaptcha.js como um possível nome de arquivo.
• Segunda versão: o arquivo TJNCaptcha-global.js é carregado do domínio ca.turing.captcha.qcloud.com. Segundo a documentação do CapMonster Cloud, essas páginas podem usar arquivos com nomes no formato TJNCaptcha*.js ou TJCaptcha*.js. O * representa uma sequência de caracteres, como -global, ou uma sequência vazia.

Segundo o guia de integração web da Tencent Cloud, a segunda versão é inicializada com new TencentCaptcha(DOM, CaptchaAppId, callback, options). O parâmetro opcional aidEncrypted recebe uma sequência criptografada de verificação associada a CaptchaAppId. Quando esse modo está habilitado, o backend do site gera a sequência.

Em páginas que usam a integração original, você pode encontrar uma requisição para https://sg.captcha.qcloud.com/cap_union_prehandle?aid=.... O parâmetro aid identifica a aplicação do CAPTCHA. Seu valor pode ser usado como websiteKey em uma tarefa TenDI no CapMonster Cloud.

O callback recebe ret, ticket e randstr. O valor ret = 0, por si só, não confirma que a verificação foi bem-sucedida. Um erro de carregamento ou de rede pode gerar o mesmo valor, com um ticket que começa com trerror_. No fluxo normal, o backend precisa validar o ticket pela API da Tencent antes de permitir a ação protegida. Trate as respostas de contingência separadamente, levando em conta ticket, errorCode e a política de recuperação configurada no site. Consulte as orientações da Tencent para recuperação em caso de falha.

Tencent Captcha e NetEase YiDun: quais são as diferenças?

É comum comparar o YiDun com o Tencent Captcha porque os dois serviços oferecem quebra-cabeças com controle deslizante. São produtos distintos. O Tencent Captcha é desenvolvido pela Tencent Cloud, enquanto o NetEase YiDun é desenvolvido pela NetEase.

Os dois produtos oferecem verificação baseada em risco, mas a integração no cliente e a validação no servidor funcionam de formas diferentes. A visão geral da integração do YiDun descreve os tipos de CAPTCHA. A documentação sobre o funcionamento do componente mostra como a avaliação de risco orienta a verificação, e o guia de integração no servidor explica como validar o resultado.

Os identificadores são diferentes. A tarefa TenDI no CapMonster Cloud precisa do aid da Tencent. O captchaId do YiDun não funciona no lugar dele.

Parâmetros da tarefa no CapMonster Cloud

O CapMonster Cloud ajuda a contornar a maioria dos tipos de captcha, incluindo o Tencent Captcha. Para criar uma tarefa TenDI para resolver o Tencent Captcha, envie uma requisição POST em formato JSON para https://api.capmonster.cloud/createTask. Os exemplos pressupõem testes automatizados em um site próprio ou em um site ao qual você tem acesso legal.

Por padrão, o CapMonster Cloud usa proxies integrados, que já estão incluídos no preço. Use um proxy próprio apenas se o site rejeitar o token ou se o acesso aos proxies integrados estiver restrito. Se o seu proxy controlar o acesso por IP, adicione 65.21.190.34 à lista de endereços permitidos.

A resposta traz data.randstr, data.ticket e headers com o User-Agent que você deve manter nas requisições seguintes.

Como criar uma tarefa

Substitua os valores de exemplo. Em CURRENT_WINDOWS_UA, use a sequência retornada pelo endpoint de User-Agent no momento em que você criar a tarefa. Inclua aidEncrypted apenas se o site fornecer o valor criptografado. Esse valor é distinto do aid usado como websiteKey.

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "CustomTask",
    "class": "TenDI",
    "websiteURL": "https://your-test-site.example/login",
    "websiteKey": "YOUR_CAPTCHA_APP_ID",
    "userAgent": "CURRENT_WINDOWS_UA",
    "metadata": {
      "captchaUrl": "https://ca.turing.captcha.qcloud.com/TJNCaptcha-global.js"
    }
  }
}

Exemplo com metadados opcionais. Inclua esse bloco na tarefa somente se o site fornecer aidEncrypted.

{
  "metadata": {
    "captchaUrl": "https://ca.turing.captcha.qcloud.com/TJNCaptcha-global.js",
    "aidEncrypted": "FRESH_AID_ENCRYPTED_VALUE"
  }
}

Resposta:

{
  "errorId": 0,
  "taskId": 407533072
}

Como obter o resultado

A API é assíncrona. Chame getTaskResult com o taskId e repita a consulta, com um intervalo entre as requisições, enquanto o status for processing. Pare de consultar quando a tarefa estiver pronta ou quando a API retornar um erro. Trate o erro antes de tentar de novo. Faça no máximo 120 consultas por tarefa. Se você ultrapassar esse limite, a conta poderá ser bloqueada temporariamente.

{
  "clientKey": "YOUR_API_KEY",
  "taskId": 407533072
}

Resposta quando a tarefa estiver pronta:

{
  "errorId": 0,
  "cost": 0.0016,
  "status": "ready",
  "solution": {
    "data": {
      "randstr": "@EcL",
      "ticket": "tr03lHUhdnuW3neJZu.....7LrIbs*"
    },
    "headers": {
      "User-Agent": "CURRENT_WINDOWS_UA"
    }
  }
}

Os tickets do Tencent Captcha valem por cinco minutos e só podem ser usados uma vez, mesmo dentro desse prazo. O backend do site deve verificar o ticket e o randstr retornados pela API de verificação da Tencent antes que o ticket expire.

Como encontrar websiteKey e captchaUrl

1. Na página com o CAPTCHA, abra as ferramentas do desenvolvedor.
2. Acesse a aba Network e acione o CAPTCHA.
3. Encontre a requisição que contém o parâmetro aid. O valor desse parâmetro é o websiteKey.
4. Procure por TCaptcha.js ou TCaptcha-global.js entre os scripts carregados. Integrações mais recentes podem usar arquivos no formato TJNCaptcha*.js ou TJCaptcha*.js. Copie a URL do script para metadata.captchaUrl.

Os scripts carregados de global.captcha.gtimg.com fazem parte da integração original. Em testes automatizados, você pode usar o Playwright para capturar os parâmetros atuais do CAPTCHA.

Como obter aidEncrypted

Se o site usar a verificação de CaptchaAppId com criptografia, o frontend pode obter aidEncrypted em uma requisição separada, como https://example.com/path/GetCaptchaAid.ashx?_=1234567890000. Inspecione a requisição na aba Network, identifique o valor criptografado na resposta e passe-o em metadata.aidEncrypted.

O endpoint e o formato da resposta dependem do site. A Tencent não define GetCaptchaAid.ashx como endpoint padrão. Esse endereço é apenas um exemplo. Obtenha o valor atual para cada tarefa, sem copiar um exemplo da documentação nem reutilizar uma resposta anterior. Se o site não fornecer aidEncrypted, omita o parâmetro. Use o aid sem criptografia da requisição cap_union_prehandle como websiteKey.

Exemplos de código para testar o Tencent Captcha com Node.js e Python

Os SDKs oficiais criam a tarefa para resolver o Tencent Captcha e fazem consultas até obter o resultado. Nestes exemplos, o User-Agent atualizado é obtido durante a execução.

Node.js (módulo ES)

No terminal, instale o SDK:

npm install @zennolab_com/capmonstercloud-client

Salve o código abaixo em um arquivo .mjs e execute-o com o Node.js 18 ou posterior.

// https://github.com/CapMonsterCloud/capmonster-nodejs-captcha-solver
import {
  CapMonsterCloudClientFactory,
  ClientOptions,
  TenDIRequest,
} from "@zennolab_com/capmonstercloud-client";
const API_KEY = "YOUR_API_KEY"; // Your CapMonster Cloud API key
const UA_ENDPOINT = "https://capmonster.cloud/api/useragent/actual";
async function getActualUserAgent() {
  const response = await fetch(UA_ENDPOINT);
  if (!response.ok) {
    throw new Error(`User-Agent endpoint returned HTTP ${response.status}`);
  }
  return (await response.text()).trim();
}
async function solveTenDI() {
  const client = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: API_KEY }),
  );
  const userAgent = await getActualUserAgent();
  const metadata = {
    captchaUrl: "https://ca.turing.captcha.qcloud.com/TJNCaptcha-global.js", // Optional
  };
  // Only if the website provides aidEncrypted: get the current encrypted value
  // metadata.aidEncrypted = "FRESH_AID_ENCRYPTED_VALUE";
  // Without a proxy, CapMonster Cloud uses its built-in proxies
  const tenDIRequest = new TenDIRequest({
    websiteURL: "https://your-test-site.example/login", // Page with the captcha
    websiteKey: "YOUR_CAPTCHA_APP_ID", // The aid value
    userAgent,
    metadata,
    // To use your own proxy, uncomment:
    // proxy: {
    //   proxyType: "http",
    //   proxyAddress: "203.0.113.10",
    //   proxyPort: 8080,
    //   proxyLogin: "username",
    //   proxyPassword: "password",
    // },
  });
  const balance = await client.getBalance();
  console.log("Balance:", balance);
  const result = await client.Solve(tenDIRequest);
  console.log("Solution:", result.solution);
}
solveTenDI().catch(console.error);

Python

No terminal, instale o SDK:

python -m pip install capmonstercloudclient

Salve o código abaixo em um arquivo .py e execute-o com o Python 3.9 ou posterior.

# https://github.com/CapMonsterCloud/capmonster-python-captcha-solver
import asyncio
import urllib.request
from capmonstercloudclient import CapMonsterClient, ClientOptions
from capmonstercloudclient.requests import TenDiCustomTaskRequest
# Import ProxyInfo if you plan to use your own proxy
# from capmonstercloudclient.requests.proxy_info import ProxyInfo
API_KEY = "YOUR_API_KEY"  # Your CapMonster Cloud API key
UA_ENDPOINT = "https://capmonster.cloud/api/useragent/actual"
def get_actual_user_agent() -> str:
    with urllib.request.urlopen(UA_ENDPOINT, timeout=15) as response:
        return response.read().decode("utf-8").strip()
async def solve_tendi():
    client = CapMonsterClient(options=ClientOptions(api_key=API_KEY))
    user_agent = await asyncio.to_thread(get_actual_user_agent)
    metadata = {
        "captchaUrl": "https://ca.turing.captcha.qcloud.com/TJNCaptcha-global.js"  # Optional
    }
    # Only if the website provides aidEncrypted: get the current encrypted value
    # metadata["aidEncrypted"] = "FRESH_AID_ENCRYPTED_VALUE"
    # Without a proxy, CapMonster Cloud uses its built-in proxies
    tendi_request = TenDiCustomTaskRequest(
        websiteUrl="https://your-test-site.example/login",  # Page with the captcha
        websiteKey="YOUR_CAPTCHA_APP_ID",  # The aid value
        userAgent=user_agent,
        metadata=metadata,
        # To use your own proxy, uncomment the import above and add:
        # proxy=ProxyInfo(
        #     proxyType="http",
        #     proxyAddress="203.0.113.10",
        #     proxyPort=8080,
        #     proxyLogin="username",
        #     proxyPassword="password",
        # ),
    )
    balance = await client.get_balance()
    print("Balance:", balance)
    result = await client.solve_captcha(tendi_request)
    print("Solution:", result)
asyncio.run(solve_tendi())

Automação de testes com o CapMonster Cloud

O CapMonster Cloud resolve o Tencent Captcha por meio da tarefa TenDI. Assim, equipes de QA podem executar testes de ponta a ponta dos fluxos de login, cadastro e checkout em seus próprios sites sem resolver manualmente o desafio com controle deslizante. Os parâmetros e exemplos de uso dos SDKs estão na documentação da tarefa TenDI para o Tencent Captcha.

NB: Por favor, observe que o produto é destinado à automação de testes exclusivamente em seus próprios sites e em recursos para os quais você possui autorização legal de acesso.