Como adicionar a resolução de CAPTCHA do Gumloop aos fluxos de trabalho web

TL;DR

• A resolução de CAPTCHA do Gumloop não é um conector nativo verificado; use os nós HTTP e de roteamento documentados do Gumloop com um serviço de recuperação de navegador de organização.
• Mantenha a detecção de desafios e a aplicação de tokens dentro da mesma sessão de navegador autorizada, em vez de pedir a um nó de fluxo que reconstrua o estado da página.
• Roteie estados exatos como NO_CHALLENGE, RECOVERED, REVIEW e STOP com regras determinísticas, não com decisões de modelo aberto.
• Limite o serviço de recuperação aos adaptadores reCAPTCHA v2/v3 e Cloudflare Turnstile documentados, uma tentativa de fluxo por padrão e verificação explícita de aplicação.
• Envie tipos não suportados, sessões perdidas, desafios repetidos e autorizações ambíguas para uma fila humana sem continuar a ação da web.

Introdução

A resolução de CAPTCHA do Gumloop funciona melhor como uma ramificação de recuperação controlada em torno de uma tarefa de navegador autorizado, não como uma integração nativa assumida. O Gumloop pode orquestrar entradas, chamadas HTTP, rotas e caminhos de erro, enquanto um trabalhador de navegador externo preserva a sessão da página e aplica um resultado verificado. CapSolver pode fornecer a camada de CAPTCHA documentada dentro desse trabalhador. Essa separação importa porque um resultado de API sozinho não comprova que a página original avançou. O fluxo deve verificar o estado do navegador, impor um orçamento de repetição e parar quando a autorização ou a continuidade da sessão for incerta. O padrão abaixo é para automação legal, razoável, responsável e autorizada por usuários em sistemas e dados que você pode acessar.

Comece com a Lacuna de Pré-Requisito

Nenhum conector nativo oficial Gumloop-CapSolver foi verificado durante a pesquisa para este guia. Portanto, a resolução de CAPTCHA do Gumloop precisa de um pré-requisito explícito: sua equipe deve operar um serviço HTTPS que possua a sessão do navegador autorizado e exponha um ponto de recuperação estreito. Isso não é uma API privada do Gumloop, um nó oculto ou uma afirmação de que o Gumloop integra oficialmente o CapSolver.

A fronteira segue as capacidades documentadas para o Gumloop. Seu nó Call API pode enviar solicitações GET ou POST para um ponto de extremidade HTTPS com cabeçalhos e um corpo de solicitação. Seu nó contrato de nó de entrada pode receber valores de um usuário, webhook ou padrão. Essas capacidades são suficientes para chamar um serviço controlado pela sua organização, mas elas não criam ou preservam uma sessão de navegador por si mesmas.

O que deve existir antes de construir o fluxo

Prepare esses componentes primeiro:

• um trabalhador de navegador autorizado que possua a página, cookies, armazenamento, agente do usuário e contexto de rede;
• um ponto de recuperação HTTPS protegido por autenticação de serviço;
• uma chave API do CapSolver armazenada apenas no gerenciador de segredos do serviço de recuperação;
• uma lista de permissões de hosts e ações permitidas;
• uma resposta tipada com estados terminais e sem credenciais brutas;
• um destino de revisão manual para casos não suportados ou ambíguos.

Se algum componente estiver faltando, mantenha a resolução de CAPTCHA do Gumloop no status de design ou teste. Não substitua um nó do Gumloop não verificado ou coloque uma chave de API de produção em texto de fluxo ordinário.

Use um Contrato de Fluxo de Cinco Etapas

Um design confiável de resolução de CAPTCHA do Gumloop separa a orquestração da execução do navegador. A tela do Gumloop deve modelar o caminho de decisão; o trabalhador do navegador deve possuir a detecção de desafios, chamadas ao CapSolver, aplicação de resultados e verificação da página.

Etapa 1: receber um evento de navegador limitado

O fluxo começa com um webhook ou entrada manual contendo uma referência opaca de execução. Não envie cookies, senhas, HTML bruto ou despejo de armazenamento de navegador. Um evento mínimo pode parecer assim:

{
  "run_id": "run_01JX...",
  "session_ref": "browser_session_7f2a",
  "approved_host": "portal.example",
  "approved_action": "submit_owned_test_form",
  "observed_state": "CHALLENGE_DETECTED",
  "challenge_type": "recaptcha_v2",
  "attempt": 0
}

A entrada é uma referência a uma execução já aprovada. A saída dessa etapa é uma solicitação de recuperação válida ou STOP. O fluxo para imediatamente se o host, a ação ou a referência de sessão estiverem ausentes ou fora da política.

Etapa 2: chamar o serviço de recuperação

Configure um nó Call API para enviar uma solicitação POST para um ponto de extremidade de propriedade da organização, como https://automation.example.net/v1/browser/recover. Use uma credencial gerenciada para o cabeçalho de autorização do serviço. O corpo deve passar os campos do evento limitado, não a chave API do CapSolver.

{
  "run_id": "{{run_id}}",
  "session_ref": "{{session_ref}}",
  "approved_host": "{{approved_host}}",
  "approved_action": "{{approved_action}}",
  "challenge_type": "{{challenge_type}}",
  "attempt": "{{attempt}}",
  "max_attempts": 1
}

Esses JSON é um contrato HTTP genérico para o seu serviço. Não é uma exportação do Gumloop nem uma solicitação da API do CapSolver. Antes da implementação, confirme as variáveis exatas de interpolação e controles de credenciais disponíveis no seu workspace do Gumloop.

Etapa 3: retornar apenas o estado operacional

O serviço deve retornar uma resposta pequena que o Gumloop possa rotear sem ver um valor de solução bruta:

{
  "state": "RECOVERED",
  "run_id": "run_01JX...",
  "correlation_id": "recovery_91c8",
  "attempts_used": 1,
  "continuation_verified": true,
  "reason": "etapa de formulário esperada tornou-se visível"
}

Respostas terminais úteis são NO_CHALLENGE, RECOVERED, REVIEW e STOP. Uma falha temporária do serviço pode retornar RETRYABLE_ERROR, mas o Gumloop deve consumir seu orçamento de tentativa única antes de chamar novamente. Não trate um estado ausente, corpo não analisável ou HTTP 200 com um valor desconhecido como sucesso.

Etapa 4: rotear com condições exatas

Use o modo padrão do Router do Gumloop para correspondência exata de estado. A recuperação de desafio é um problema de controle determinístico, então não precisa de interpretação de modelo.

Esta tabela define a saída da resolução de CAPTCHA do Gumloop, não o status interno da provedora. O estado do provedor deve ser resolvido dentro do serviço de recuperação antes que uma resposta terminal atinja o fluxo.

Etapa 5: tratar falhas de transporte separadamente

Envolva o nó Call API com a ramificação de falha do Error Shield do Gumloop. Ative pass-through apenas para os campos de entrada não secretos necessários para investigar uma chamada falhada. O caminho de erro deve criar um registro de revisão ou enviar um alerta; ele não deve reconectar automaticamente à ação do navegador.

Falhas de transporte, erros do provedor, rejeição da aplicação e desafios não suportados exigem evidências diferentes. Combinar os quatro em uma única ramificação de tentativa torna a resolução de CAPTCHA do Gumloop difícil de operar e pode criar tráfego repetido após uma falha terminal.

Implemente o Serviço de Recuperação com Campos Oficiais do CapSolver

O serviço de recuperação é onde os campos oficiais do CapSolver pertencem. A solicitação createTask aceita clientKey e um objeto de tarefa. A resposta getTaskResult usa errorId, status e solution para tarefas assíncronas. As respostas oficiais indicam que um resultado processing pode ser consultado novamente após três segundos.

O exemplo Python a seguir implementa apenas o adaptador reCAPTCHA v2. Ele usa os campos documentados ReCaptchaV2TaskProxyLess, websiteURL e websiteKey da definição de tarefa reCAPTCHA v2. As funções de detecção e aplicação específicas do navegador são placeholders possuídos pelo seu trabalhador; eles não são métodos da API do Gumloop ou CapSolver.

import os
import time
import requests

CAPSOLVER_KEY = os.environ["CAPSOLVER_API_KEY"]
CREATE_TASK = "https://api.capsolver.com/createTask"
GET_RESULT = "https://api.capsolver.com/getTaskResult"
APPROVED_HOSTS = {"portal.example"}


def solve_recaptcha_v2(website_url: str, website_key: str) -> dict:
    created = requests.post(
        CREATE_TASK,
        json={
            "clientKey": CAPSOLVER_KEY,
            "task": {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": website_url,
                "websiteKey": website_key,
            },
        },
        timeout=15,
    ).json()

    if created.get("errorId") or not created.get("taskId"):
        return {"state": "REVIEW", "reason": "criação da tarefa falhou"}

    for _ in range(4):
        time.sleep(3)
        result = requests.post(
            GET_RESULT,
            json={"clientKey": CAPSOLVER_KEY, "taskId": created["taskId"]},
            timeout=15,
        ).json()

        if result.get("errorId"):
            return {"state": "REVIEW", "reason": "provedor retornou um erro"}
        if result.get("status") == "ready":
            return {"state": "SOLUTION_READY", "solution": result["solution"]}
        if result.get("status") != "processing":
            return {"state": "REVIEW", "reason": "status da tarefa inesperado"}

    return {"state": "STOP", "reason": "orçamento de verificação esgotado"}


def recover_authorized_session(event: dict, browser_store) -> dict:
    if event.get("approved_host") not in APPROVED_HOSTS:
        return {"state": "STOP", "reason": "host fora do escopo aprovado"}
    if event.get("attempt", 0) >= event.get("max_attempts", 1):
        return {"state": "STOP", "reason": "orçamento de tentativas esgotado"}

    page = browser_store.get(event["session_ref"])
    if page is None:
        return {"state": "REVIEW", "reason": "sessão do navegador indisponível"}

    info = detect_supported_challenge(page)  # seu adaptador verificado do navegador
    if info is None:
        return {"state": "NO_CHALLENGE"}
    if info["type"] != "recaptcha_v2":
        return {"state": "REVIEW", "reason": "adaptador não configurado"}

    solved = solve_recaptcha_v2(info["website_url"], info["website_key"])
    if solved["state"] != "SOLUTION_READY":
        return solved

    apply_solution_in_same_session(page, solved["solution"])
    if not verify_expected_transition(page, event["approved_action"]):
        return {"state": "REVIEW", "reason": "aplicação não avançou"}

    return {"state": "RECOVERED", "continuation_verified": True}

A entrada da função é um evento de execução aprovado mais uma referência de sessão de navegador opaca. Sua saída é um estado terminal para o Gumloop. Ele para em um host não aprovado, orçamento de tentativas esgotado, sessão de navegador ausente, adaptador não suportado, erro do provedor, status de tarefa inesperado, esgotamento de orçamento de verificação ou falha na verificação da aplicação.

Não reutilize o objeto de tarefa v2 para outros tipos de desafio. Crie adaptadores separados a partir da guia de tarefa reCAPTCHA v3 oficial e da guia de tarefa Cloudflare Turnstile. Mantenha os campos necessários de cada adaptador, solução retornada, lógica de aplicação do navegador e afirmação de validação isoladas.

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 adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Mantenha a Continuidade do Navegador Fora da Tela

A continuidade da sessão é o limite decisivo na resolução de CAPTCHA do Gumloop. Uma solução pode ser tecnicamente válida e ainda falhar ao retornar para uma página diferente, jarra de cookies, agente do usuário, identidade de proxy, rota ou ação protegida.

O fluxo do Gumloop deve passar uma session_ref opaca; ele não deve reconstruir o estado do navegador a partir de campos copiados. O trabalhador de recuperação resolve essa referência, confirma a URL atual e o desafio, aplica o resultado no mesmo contexto de navegador e verifica uma afirmação de aplicação específica. Exemplos incluem uma etapa de formulário tornar-se visível, uma rota QA proprietária completar ou um elemento de página pública esperado aparecer.

A verificação da aplicação deve ser mais forte que "a chamada HTTP foi bem-sucedida". O diagnóstico de recuperação n8n ilustra por que plataformas de fluxo de trabalho precisam de uma verificação separada após a recuperação. No Gumloop, modele essa verificação como parte da resposta do trabalhador e exija continuation_verified=true antes que a ramificação de sucesso possa ser executada.

Defina um Orçamento de Tentativa que Não Loop

Um bom fluxo de resolução de CAPTCHA do Gumloop tem dois orçamentos: um orçamento de verificação de provedor dentro do serviço de recuperação e um orçamento de tentativa de repetição no Gumloop. Eles resolvem problemas diferentes.

O orçamento de verificação de provedor controla por quanto tempo o serviço espera por uma tarefa que ainda está em processamento. O orçamento de tentativa de repetição do fluxo controla se o Gumloop pode chamar o serviço de recuperação novamente após um erro de transporte temporário. Uma política inicial sensata é uma tentativa de recuperação do fluxo e um loop de verificação de provedor pequeno e temporizado. Ajuste esses valores apenas a partir de cargas de trabalho autorizadas observadas.

Pare sem tentativa novamente quando:

• o host da página ou a ação pretendida diferir da execução aprovada;
• a sessão do navegador não puder ser restaurada;
• o tipo de desafio não puder ser classificado ou não tiver adaptador configurado;
• o alvo atingir uma fronteira de login, pagamento, privado, restrito ou dados sensíveis fora da autorização;
• o provedor retornar um erro terminal;
• o mesmo desafio reaparecer após a aplicação do resultado;
• a transição de aplicação esperada não ocorrer;
• a resposta do serviço estiver vazia, malformada ou usar um estado desconhecido.

O fluxo deve registrar o motivo da parada, o ID de correlação, o número de tentativas e o identificador do alvo redigido. Ele não deve armazenar chaves de API, cookies, valores de solução bruta ou conteúdo de página desnecessário nos logs rotineiros.

Adicione Fallback Humano Sem Inventar um Nó de Pausa

A falha humana depende da superfície Gumloop que você está operando. Para um fluxo de trabalho padrão, roteie REVIEW para uma notificação, ticket, folha ou outro fila manual, depois termine a ação do navegador autônoma. Não afirme que cada fluxo de trabalho pode pausar indefinidamente a menos que seu próprio plano e configuração Gumloop provem isso.

A Gumloop documenta separadamente aprovação humana para chamadas de ferramentas de agente. Se a ação de recuperação for exposta a um agente Gumloop como uma ferramenta aprovada, você pode exigir aprovação antes da chamada da ferramenta e permitir que o agente retome após uma decisão. Isso é uma opção de controle do agente, não comprova um conector CapSolver e não substitui as verificações de autorização do serviço de recuperação.

Um operador revisando evidências de resolução de CAPTCHA do Gumloop deve ver:

• o host e ação aprovados;
• a categoria de desafio, sem um valor de solução bruta;
• o status da sessão do navegador;
• tentativas usadas e restantes;
• a última afirmação da aplicação;
• o motivo exato pelo qual a execução autônoma parou.

A aprovação deve permitir uma ação nomeada, não expandir a execução para um novo host ou escopo de dados.

Teste as Ramificações de Falha Antes da Produção

Valide a resolução de CAPTCHA do Gumloop com fixtures em um sistema que você possua ou tenha permissão para testar. O conjunto de aceitação deve abranger tanto o canvas do Gumloop quanto o trabalhador do navegador.

1. Envie um evento NO_CHALLENGE válido e confirme que o fluxo de trabalho continua sem chamar o ponto de extremidade de recuperação.
2. Envie um fixture de reCAPTCHA v2 aprovado e confirme que o trabalhador do navegador preserva a sessão e retorna RECOVERED apenas após a afirmação da aplicação passar.
3. Retorne processing até que o orçamento de pesquisa do provedor expire e confirme que o serviço retorna STOP.
4. Simule um timeout no ponto de extremidade de recuperação e confirme que o Error Shield usa o caminho de revisão em vez do caminho de sucesso.
5. Retorne um estado desconhecido e confirme que o Router seleciona a ramificação de captura geral.
6. Remova a sessão do navegador e confirme que o fluxo não cria um novo contexto silenciosamente.
7. Apresente um fixture de reCAPTCHA v3 ou Turnstile antes que seu adaptador seja configurado e confirme que o resultado é REVIEW.
8. Repita o desafio após a aplicação e confirme que o fluxo não consome um loop de tentativas ilimitadas.

A evidência final deve responder a quatro perguntas: A execução foi autorizada? O adaptador de desafio foi documentado? A mesma sessão do navegador continuou? O estado da aplicação pretendido avançou? Uma resposta "sim" apenas da chamada da API não é suficiente.

Conclusão

A resolução de CAPTCHA do Gumloop é confiável quando o Gumloop permanece como orquestrador e um serviço de navegador autorizado possui a recuperação sensível à sessão. Use o comportamento documentado de Input, Call API, Router e Error Shield; exponha um contrato HTTP pequeno; mantenha as repetições limitadas; verifique a transição original da página e direcione a incerteza para revisão. Não afirme um conector nativo ou copie o estado do navegador para o fluxo. Para automação web aprovada que precisa de tratamento documentado de reCAPTCHA v2/v3 ou Cloudflare Turnstile atrás desses controles, avalie o CapSolver como o componente de recuperação dentro da sua fronteira de serviço.

Perguntas Frequentes

O Gumloop tem integração oficial com o CapSolver?

Não, nenhum conector nativo Gumloop-CapSolver foi verificado para este guia. A implementação usa as capacidades HTTP e de roteamento documentadas do Gumloop para chamar um serviço de recuperação pertencente à organização que integra o CapSolver.

Posso chamar a API do CapSolver diretamente de um nó Call API do Gumloop?

O nó Call API pode enviar solicitações POST, mas chamadas diretas podem expor credenciais do provedor e ainda não preservar ou retomar uma sessão do navegador. Um serviço de recuperação do lado do servidor estreito é o limite operacional mais seguro, pois armazena a chave, possui a sessão, aplica o resultado e retorna apenas um estado verificado.

Quais tipos de CAPTCHA o fluxo deve suportar?

Para esse padrão orientado a agentes, configure adaptadores documentados separados para reCAPTCHA v2, reCAPTCHA v3 incluindo Enterprise onde aplicável e Cloudflare Turnstile. Não reutilize campos entre tipos de tarefa ou trate um tipo não suportado como um erro recuperável.

Quantas tentativas de repetição um fluxo do Gumloop deve permitir?

Comece com uma tentativa de recuperação de fluxo. Mantenha a pesquisa do provedor dentro do serviço de recuperação com seu próprio tempo e orçamento de consulta. Pare quando o desafio for repetido, a continuidade da sessão for perdida, o provedor retornar um erro ou a verificação da aplicação falhar.

Quando o Gumloop deve enviar uma execução para revisão humana?

Use revisão humana quando a autorização for ambígua, a sessão do navegador estiver ausente, o tipo de desafio for não suportado, a resposta for malformada, o orçamento de tentativas for esgotado ou a transição esperada da página não ocorrer. A revisão não deve expandir o host, ação ou escopo de dados aprovados.