Resolva o reCAPTCHA com getToken: Uma Solicitação, Sem Poling

TL;DR

• O endpoint getToken do CapSolver pode retornar um resultado de reCAPTCHA compatível na resposta a uma única solicitação.
• Envie clientKey e um objeto de tarefa compatível para https://api.capsolver.com/getToken.
• Escolha o tipo de tarefa para sua variante de reCAPTCHA e forneça a página, a chave pública do site e o contexto correspondente.
• Leia solution.gRecaptchaResponse após verificar o resultado da API; uma troca HTTP bem-sucedida por si só é insuficiente.
• Um token retornado ainda precisa da verificação normal da sua aplicação. Uma única solicitação não significa conclusão instantânea ou aceitação garantida.
• A solicitação cURL abaixo foi verificada contra um fixture HTTP local. Uma solução ao vivo não foi realizada.

A integração convencional de um solucionador de CAPTCHA cria uma tarefa e depois solicita seu resultado. Se você estiver integrando uma tarefa de reCAPTCHA compatível e quiser uma resposta direta, o endpoint getToken do CapSolver fornece outro padrão de solicitação documentado.

A diferença prática está no cliente: envie a tarefa e aguarde seu resultado naquela resposta HTTP. Você não escreve um loop de polling getTaskResult para esse fluxo. Este guia percorre os campos da tarefa, um arquivo JSON e o comando cURL, o token retornado e as verificações necessárias antes que sua aplicação possa aceitá-lo.

O que é a API getToken?

A API getToken é um endpoint de resultado direto para os tipos de tarefa reCAPTCHA listados em sua documentação. Um endpoint de API é o endereço para uma operação específica de API; usar o caminho correto seleciona este padrão de solicitação.

A documentação oficial da getToken lista variantes de tarefa reCAPTCHA v2 e v3 compatíveis, incluindo opções correspondentes de Enterprise e proxy. Não infira suporte para AWS WAF, Turnstile ou reconhecimento de imagem a partir do nome geral do endpoint.

O método muda a recuperação de resultados, não o significado dos parâmetros do desafio. Uma chave pública do site incorreta ou um tipo de tarefa desalinhado permanece incorreto ao ser enviado por um endpoint direto. Confirme primeiro a família CAPTCHA, depois escolha a variante de tarefa documentada.

Alguns tipos de tarefa createTask já retornam resultados diretamente. A comparação não significa que cada chamada createTask exija polling.

Etapa 1: Identificar a tarefa reCAPTCHA e as chaves

Identifique a integração de reCAPTCHA real na sua página antes de construir a solicitação. O exemplo abaixo usa ReCaptchaV3TaskProxyLess, então seus campos devem descrever uma integração v3.

Mantenha as três funções-chave separadas. A chave da API do CapSolver autoriza a solicitação de resolução. A chave pública do site reCAPTCHA identifica a integração da página. A chave secreta de verificação do proprietário do site pertence ao servidor da aplicação; não é a clientKey ou websiteKey nesta solicitação.

Para v3, verifique a ação esperada, bem como a chave pública. A documentação da tarefa reCAPTCHA v3 explica os campos da tarefa, incluindo pageAction. A ação de exemplo submit abaixo é um espaço reservado para a ação que seu formulário realmente usa.

A documentação do reCAPTCHA v3 da Google descreve a avaliação baseada em ação. Um token para uma ação diferente não deve ser tratado como um teste bem-sucedido do formulário pretendido. Mantenha a ação da solicitação e a ação esperada pelo backend alinhadas.

Se a página usar v2 ou Enterprise, selecione seu tipo de tarefa documentado e campos em vez de alterar apenas o título da integração. Evite copiar uma ação v3 para uma tarefa diferente sem verificar seus requisitos.

Etapa 2: Salvar a solicitação JSON documentada

Salve o seguinte JSON como request.json. Seu envelope segue a documentação do getToken, e os campos da tarefa seguem o guia v3. Esses são valores de exemplo; substitua-os por suas configurações para uma verificação ao vivo.

{
  "clientKey": "SUA_CHAVE_DA_API",
  "task": {
    "type": "ReCaptchaV3TaskProxyLess",
    "websiteURL": "https://sua-pagina-teste-exemplo/form",
    "websiteKey": "SUA_CHAVE_PÚBLICA_DO_SITE",
    "pageAction": "submit"
  }
}

Substitua todos os marcadores antes de contatar o endpoint ao vivo. O domínio de exemplo identifica intencionalmente uma página de teste própria e não é um alvo de CAPTCHA funcional. A chave pública e a ação devem vir da integração configurada nessa página.

Um arquivo JSON facilita a inspeção da carga útil sem um longo comando de shell. Quando contém uma credencial real, restrinja o acesso a esse arquivo e mantenha-o fora do controle de versão. Use um método apropriado de gerenciamento de segredos ao mover essa solicitação para uma aplicação.

O nome da tarefa sem proxy descreve a variante da tarefa do provedor. Não remove a necessidade de contexto de página correto, nem implica que toda configuração de desafio use parâmetros idênticos. Use a documentação da tarefa como referência de campo.

Etapa 3: Enviar uma única solicitação com cURL

Execute esse comando no diretório que contém request.json. Seus flags e carga útil foram testados contra um fixture HTTP local, mas o endpoint ao vivo ainda exige sua credencial de resolução e parâmetros da página própria:

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

O comando usa a opção de solicitação JSON do cURL para enviar o arquivo como corpo. A documentação oficial do cURL sobre JSON explica a opção e seus cabeçalhos de solicitação. Use uma versão do cURL que suporte --json.

Os valores de timeout de conexão e total são escolhas locais para este exemplo. Eles não são um compromisso de serviço do provedor. O endpoint pode manter a solicitação enquanto resolve a tarefa, então uma resposta direta não é sinônimo de resposta instantânea.

Verifique tanto o resultado HTTP quanto o conteúdo JSON. Este comando exibe o corpo da resposta e erros de transporte; não é um manipulador de erros completo da aplicação. O cURL pode completar uma troca HTTP mesmo quando o JSON retornado descreve um erro do provedor. Uma aplicação deve ramificar nos campos retornados em vez de procurar uma string com aparência de token no terminal.

Não adicione um loop de polling a esse comando como próximo passo padrão. O fluxo escolhido é especificamente destinado a retornar seu resultado diretamente. Se sua aplicação precisar de rastreamento de tarefa com recuperação de resultado separada, selecione e implemente o fluxo createTask documentado desde o início.

Resgate seu código promocional do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta do CapSolver para obter um bônus extra de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Etapa 4: Ler a resposta direta do token

Leia solution.gRecaptchaResponse apenas após confirmar que o resultado relata sucesso e prontidão. A seguinte forma de resposta é ilustrativa; o valor do token é um exemplo, não um token retornado por uma solução ao vivo.

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

Os valores importantes são o indicador de erro, o status de prontidão e o campo de resultado não vazio. Não trate um objeto de resposta, identificador de tarefa ou status HTTP de sucesso como intercambiáveis com um token útil. Campos opcionais também podem aparecer; mantenha apenas os que sua integração precisa.

Em caso de falha do provedor, inspecione o código de erro e a descrição descritos pela referência de erro da API. Mantenha informações suficientes para distinguir um parâmetro inválido de um problema de conta ou falha de transporte, excluindo credencial e token de logs rotineiros.

Um endpoint direto simplifica a máquina de estado do cliente, mas a conexão permanece parte da operação. Se o cliente expirar ou perder a resposta, seu resultado pode ser incerto. A solicitação pode ter chegado ao provedor antes da falha local. Não descreva uma nova submissão imediata como retomar a primeira tarefa, a menos que a API documente explicitamente esse comportamento.

Etapa 5: Validar o token em sua aplicação própria

Um token retornado deve passar pela verificação normal da aplicação antes que a operação seja considerada bem-sucedida. O resultado do solucionador e a aceitação pela aplicação são eventos separados.

A documentação de verificação do lado do servidor da Google afirma que os tokens de resposta expiram após dois minutos e podem ser verificados apenas uma vez. Obtenha o token perto da operação pretendida e evite testar o mesmo token repetidamente por meio do ponto de verificação.

Para o fluxo padrão de verificação, a chave secreta do proprietário do site permanece no backend. Verifique as propriedades da resposta relevantes para sua integração, incluindo o hostname esperado e, para v3, a ação e a política de pontuação. Aplicações Enterprise devem usar suas integrações de verificação ou avaliação correspondentes em vez de assumir que o exemplo padrão cobre todas as variantes.

Considere um formulário próprio com uma ação submit. Um teste útil primeiro confirma que a tarefa solicitada descreve essa ação, depois envia o token retornado pelo caminho normal do formulário e, finalmente, afirma que a operação de teste pretendida foi aceita. Um token impresso em um terminal prova apenas que uma string foi recebida.

Para interpretação de pontuação, consulte o guia separado sobre pontuação do reCAPTCHA v3. Mudar os pontos de recuperação não estabelece uma pontuação específica ou remove as regras de aceitação do backend.

Quando usar getToken em vez de polling?

Use o getToken quando a variante da tarefa for compatível e o cliente puder manter uma solicitação aberta enquanto espera pelo resultado. Isso se encaixa em uma pequena integração direta em que o próximo passo da aplicação consome imediatamente o token retornado.

Use a API createTask e seu fluxo de resultado documentado quando sua aplicação precisar especificamente de criação de tarefa e recuperação de resultado separados. Por exemplo, um trabalhador que persiste identificadores de tarefa entre etapas pode ser organizado em torno desse padrão.

Escolha de acordo com o ciclo de vida do cliente, em vez de assumir que um endpoint é universalmente mais rápido. Uma solicitação direta remove o código de polling do cliente, mas isso sozinho não prova menor latência de resolução. Um trabalhador de fundo também pode precisar de controles que não sejam fornecidos por uma única chamada HTTP síncrona.

Não mude as famílias de CAPTCHA apenas para se adequar a um endpoint preferido. A página determina o tipo de desafio. Se a família não estiver listada para o getToken, siga a API documentada dessa família.

O que o exemplo de teste estabelece?

O comando cURL foi executado contra um fixture HTTP local com apenas o endpoint substituído. O fixture verificou o caminho POST, o tipo de conteúdo JSON e a carga útil analisada exata, depois retornou uma resposta pronta fornecida. Isso verificou o comando baseado em arquivo e o tratamento de resposta direta.

Nenhuma chave de resolução real, tarefa paga ou formulário protegido por reCAPTCHA foi usada. O token do fixture não é válido para nenhuma aplicação. Uma integração ao vivo ainda precisa da chave do site real, ação, credencial de resolução e o resultado de verificação da aplicação própria.

Antes de expandir além de um único teste, registre qual variante de tarefa e campos funcionaram com a página própria. Se o teste falhar, identifique se a falha ocorreu durante a submissão da tarefa, recuperação do resultado, verificação do token ou a operação final da aplicação. Essas distinções dão um ponto de partida concreto sem adicionar um loop de polling desnecessário.

Tente o CapSolver com uma tarefa de reCAPTCHA compatível para completar a etapa de verificação ao vivo. Mantenha os mesmos campos da solicitação e verificações de aceitação ao mover a solicitação comprovada do cURL para sua aplicação.

Perguntas frequentes

Q: O getToken exige getTaskResult?

O fluxo direto descrito aqui retorna o resultado na resposta do getToken, então o cliente não faz polling em getTaskResult. O rastreamento de tarefa com recuperação separada pertence à integração correspondente do createTask.

Q: O getToken pode resolver qualquer tipo de CAPTCHA?

Use apenas os tipos de tarefa listados em sua documentação. As variantes de reCAPTCHA documentadas não implicam suporte para famílias não relacionadas, como AWS WAF ou reconhecimento de imagem.

Q: O getToken é mais rápido que o createTask?

Este guia não estabelece uma vantagem de latência. A diferença de design observável é que o cliente espera por um resultado direto em vez de implementar um loop de recuperação separado.

Q: O websiteKey é a chave secreta de verificação privada?

Não. É a chave pública do site para a integração da página. A chave secreta de verificação do site permanece no backend, enquanto clientKey é a credencial do serviço de resolução.

Q: Por que um token retornado pode falhar na verificação?

Verifique expiração, uso anterior, contexto da página esperado, ação e a resposta de verificação da aplicação. Receber um token do solucionador não garante que a aplicação o aceite.

Q: O token de exemplo foi produzido por uma solução ao vivo?

Não. A resposta mostrada é ilustrativa, e o comando foi verificado com um fixture HTTP local. Conclua um teste ao vivo separado com sua chave de resolução e aplicação própria.