Coleta de Dados do Estoque de Loja: Guia de Recuperação do CAPTCHA

TL;DR

• A coleta de dados de estoque de loja é confiável apenas quando a identidade do produto, localização, estado do estoque e horário de coleta são capturados juntos.
• Um ponto de verificação CAPTCHA deve pausar o fluxo de trabalho de estoque; o trabalho não deve continuar até que a mesma sessão do navegador receba e valide uma solução.
• O fluxo atual da API reCAPTCHA v2 do CapSolver usa ReCaptchaV2TaskProxyLess, websiteURL e websiteKey, retornando gRecaptchaResponse após um resultado pronto.
• A disponibilidade do estoque deve ser verificada a partir de um estado da aplicação, como uma etiqueta de estoque disponível, resultado de localização de retirada, resposta de elegibilidade do carrinho ou payload de produto estruturado, e não apenas a partir da resposta do solver.
• Poluição limitada, uma repetição controlada, limites de taxa por loja e um estado claro needs_review evitam loops e alertas de estoque enganosos.
• Este fluxo é apropriado apenas para coleta legal, razoável, responsável e autorizada por páginas às quais você tem permissão para acessar.

Introdução

A coleta de dados de estoque de loja parece simples até que uma página de varejo altere seu comportamento por localização, exija um seletor de loja ou pause uma sessão do navegador autorizada em um CAPTCHA. Um coletor confiável deve preservar o contexto do produto e da loja, resolver o checkpoint por meio da mesma sessão e provar que a página retornou um estado real de estoque. CapSolver pode servir como a infraestrutura CAPTCHA dentro desse passo de recuperação controlado.

Este guia se concentra em uma situação de operações de varejo concreta: monitorar a disponibilidade pública de produtos para planejamento de reposição aprovado, QA de merchandising ou notificações de estoque para o cliente. Ele não assume que uma tarefa CAPTCHA bem-sucedida significa que a solicitação de estoque foi bem-sucedida. O fluxo termina apenas quando a aplicação de destino fornece um resultado de estoque reconhecido e o coletor registra evidências suficientes para distinguir "esgotado" de "desconhecido".

O que a Coleta de Dados de Estoque de Loja Deve Retornar

A coleta de dados de estoque de loja deve retornar um pequeno registro estável que sistemas downstream possam confiar. Um registro útil contém o varejista, identificador de produto canônico, loja solicitada ou área postal, disponibilidade observada, horário de coleta e fonte de evidência. O preço pode ser incluído, mas não deve substituir um estado de estoque explícito.

{
  "retailer": "authorized-demo-store",
  "product_id": "SKU-4821",
  "store_id": "STORE-017",
  "postal_area": "10001",
  "availability": "in_stock",
  "quantity_hint": "limited",
  "observed_at": "2026-08-13T09:15:00Z",
  "source": "product-page",
  "verification": "inventory-label-and-store-id",
  "captcha_recovery": "completed"
}

A entrada é uma URL de produto mais um contexto de loja permitido. A operação seleciona ou confirma a localização, detecta um checkpoint de verificação, o resolve quando autorizado, lê o estado de estoque e normaliza o resultado. A saída é o registro acima ou um estado terminal, como not_found, out_of_stock, needs_review ou policy_denied. Nunca converta um timeout, loop de desafio, parede de login ou resposta malformada em out_of_stock; esse erro cria sinais comerciais falsos.

A FAQ de resolução de CAPTCHA do CapSolver explica os limites do serviço, enquanto o guia de automação de navegador fornece contexto mais amplo para manter o estado da página. Nesse caso do usuário, o navegador é responsável pela navegação e evidência, o CapSolver é responsável pela tarefa documentada CAPTCHA e sua aplicação é responsável pela autorização, política de repetição e verificação final.

Por Que o CAPTCHA É um Limite de Falha de Estoque Fundamental

Um coletor de varejo comumente realiza várias ações com estado antes que o estoque apareça: carregar uma página de produto, aceitar uma configuração regional, selecionar uma loja, abrir um painel de retirada ou chamar um ponto de extremidade de estoque público iniciado pela página. Um CAPTCHA pode aparecer antes que a primeira página seja renderizada ou após uma dessas ações. Se o coletor tratá-lo como HTML genérico, os seletores falharão e o trabalho pode gravar um registro vazio ou incorreto.

A resposta correta é uma transição de estado, não uma repetição cega. O coletor muda de collecting para captcha_required, congela o contexto atual do produto e localização, coleta apenas os campos de desafio documentados e chama o adaptador do provedor. Uma resposta pronta do provedor move o fluxo para apply_solution; a aceitação da aplicação move para verify_inventory. Um resultado rejeitado, checkpoint repetido, host inesperado ou prazo esgotado move para needs_review.

Este design mantém três verdades diferentes separadas:

• Verdade do provedor: a tarefa CAPTCHA está pronta e contém o campo de solução documentado.
• Verdade do navegador: o token ou callback foi aplicado à página original e o checkpoint mudou de estado.
• Verdade do negócio: a loja e o produto solicitados retornaram um resultado de estoque reconhecido.

Apenas a terceira verdade permite que o trabalho publique um registro de estoque. Essa separação é especialmente importante quando um varejista usa conteúdo em cache, redireciona entre domínios regionais ou atualiza o estoque de forma assíncrona após o carregamento inicial do HTML.

Arquitetura para um Coletor de Estoque Autorizado

Use seis componentes com responsabilidades estreitas.

1. Registro de escopo

O registro de escopo lista hostnames aprovados, propósitos de coleta, caminhos de produto, regiões de loja, agendas e proprietários. Também deve registrar exclusões: áreas de conta autenticada, portais de funcionários, checkout, pagamento, perfis pessoais e qualquer caminho que o proprietário do site ou seu acordo coloque fora do escopo. Uma solicitação que não corresponda ao registro para antes que o navegador seja aberto.

2. Sessão do navegador

O navegador estabelece local, seleção de loja, cookies e estado de navegação. Mantenha uma verificação de produto dentro de um único contexto de navegador. Reutilizar cookies não relacionados entre lojas pode criar desvio de localização confuso; descartar o contexto durante a recuperação de CAPTCHA pode invalidar a solução. Persista apenas os dados mínimos necessários para o trabalho e os limpe de acordo com sua política de retenção.

3. Detetor de ponto de verificação

O detetor procura elementos de widget explícitos, campos de resposta conhecidos, scripts de desafio ou uma rota de verificação. Também distingue um CAPTCHA de problemas comuns, como 404, diálogo de consentimento, loja indisponível ou erro de aplicação. O glossário do CapSolver é útil para manter a terminologia de desafio consistente nos logs e manuais de operação.

4. Adaptador do CapSolver

O adaptador recebe uma solicitação estreita contendo tipo de desafio, URL da página, chave do site e ID de correlação. Ele lê a chave da API de armazenamento secreto, cria uma tarefa, verifica a mesma tarefa com um prazo, valida o esquema do resultado e retorna um sucesso ou falha normalizado. Ele não decide quais sites são permitidos e não grava dados de estoque.

5. Extrator de estoque

O extrator mapeia a página ou resposta pública para um esquema de estoque estável. Ele deve preferir identificadores de produto duráveis, IDs de loja, dados estruturados e texto de disponibilidade explícito em vez de posições visuais frágeis. Se a página contiver vários modos de atendimento, registre retirada, envio e entrega local separadamente em vez de combiná-los em um booleano.

6. Camada de evidência e alerta

A camada de evidência armazena fatos diagnósticos não sensíveis: ID de correlação, hostname permitido, ID de produto, ID de loja, tipo de desafio, ID de tarefa do provedor, tempo decorrido, estado final e o seletor ou campo de resposta usado para verificação. Deve ocultar tokens, cookies, chaves de API, endereços e qualquer dados de cliente. Alertar apenas sobre mudanças de estado significativas e exigir duas observações quando um resultado transitório único pudesse causar ruído operacional.

Requisitos e Controles de Uso Responsável

Antes de implementar a recuperação de CAPTCHA, confirme que você tem permissão para automatizar as páginas de varejo selecionadas e que o propósito da coleta está documentado. Respeite os limites contratuais, a lei aplicável, as instruções de robôs onde se aplicam ao seu uso e as taxas razoáveis de solicitação. O Protocolo de Exclusão de Robôs descreve diretrizes padronizadas para robôs; é um sinal dentro de uma revisão de autorização mais ampla, não uma concessão de acesso.

Use esses requisitos:

• Um hostname de varejo permitido e um proprietário de negócio nomeado.
• Uma lista limitada de identificadores de produto e loja.
• Uma chave API do CapSolver dedicada armazenada fora do controle de fonte.
• Python 3.11 ou superior com requests e Playwright instalados.
• Uma página permitida em staging ou produção onde os parâmetros do widget possam ser observados legalmente.
• Um contrato de verificação para cada estado de disponibilidade.
• Um orçamento de taxa, orçamento de tarefa e duração máxima de execução.

Segredos devem vir de um ambiente gerenciado ou armazenamento de segredos. A orientação de gerenciamento de segredos da OWASP apoia a separação de credenciais do código da aplicação, logs e artefatos de construção. Não coloque uma chave de cliente real, cookie, token resolvido ou endereço de cliente em um artigo, prompt, imagem ou ticket de solução de problemas.

Detectar reCAPTCHA sem Perder o Contexto da Loja

O detetor deve ser executado após cada ação que possa disparar uma página de verificação: navegação inicial, mudança de loja, abertura do painel de retirada, paginação e atualização de estoque. A detecção deve retornar evidência estruturada em vez de um simples booleano.

from dataclasses import dataclass

@dataclass(frozen=True)
class CaptchaEvidence:
    kind: str
    website_url: str
    website_key: str

async def detect_recaptcha_v2(page) -> CaptchaEvidence | None:
    frame = page.locator('iframe[src*="recaptcha"]')
    textarea = page.locator('textarea[name="g-recaptcha-response"]')
    if await frame.count() == 0 and await textarea.count() == 0:
        return None

    key = await page.locator('[data-sitekey]').first.get_attribute('data-sitekey')
    if not key:
        raise RuntimeError("reCAPTCHA detectado sem chave de site legível")

    return CaptchaEvidence(
        kind="recaptcha_v2",
        website_url=page.url,
        website_key=key,
    )

A entrada é a página Playwright já aberta. A operação verifica dois sinais de widget explícitos e lê a chave de site fornecida pela página. A saída é None ou um objeto de evidência tipado. A função para com um erro quando um desafio é visível, mas a chave não pode ser confirmada; adivinhar uma chave ou reutilizar uma de outra página tornaria a recuperação confiável.

Antes de chamar o solver, valide que page.url ainda pertence ao host de varejo permitido e que a execução atual ainda mantém os identificadores de produto e loja esperados. Se um redirecionamento levar a uma página de conta, checkout, fluxo de pagamento ou domínio inesperado, pare e marque como policy_denied. Capacidade técnica não fornece permissão para acessar dados privados, restritos, sensíveis ou não autorizados.

Criar e Verificar uma Tarefa do CapSolver

O guia oficial da tarefa reCAPTCHA v2 do CapSolver documenta ReCaptchaV2TaskProxyLess, websiteURL e websiteKey. A API createTask retorna um taskId; a API getTaskResult retorna um resultado terminal. Um resultado bem-sucedido do reCAPTCHA v2 inclui solution.gRecaptchaResponse.

import os
import time
import requests

CAPSOLVER_API = "https://api.capsolver.com"

def solve_recaptcha_v2(website_url: str, website_key: str) -> str:
    client_key = os.environ["CAPSOLVER_API_KEY"]
    created = requests.post(
        f"{CAPSOLVER_API}/createTask",
        json={
            "clientKey": client_key,
            "task": {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": website_url,
                "websiteKey": website_key,
            },
        },
        timeout=30,
    ).json()

    if created.get("errorId") or not created.get("taskId"):
        raise RuntimeError(created.get("errorDescription", "createTask failed"))

    task_id = created["taskId"]
    deadline = time.monotonic() + 120
    while time.monotonic() < deadline:
        result = requests.post(
            f"{CAPSOLVER_API}/getTaskResult",
            json={"clientKey": client_key, "taskId": task_id},
            timeout=30,
        ).json()

        if result.get("status") == "ready":
            token = result.get("solution", {}).get("gRecaptchaResponse")
            if not token:
                raise RuntimeError("resultado pronto não contém gRecaptchaResponse")
            return token
        if result.get("status") == "failed" or result.get("errorId"):
            raise RuntimeError(result.get("errorDescription", "tarefa CAPTCHA falhou"))
        time.sleep(3)

    raise TimeoutError("tarefa CAPTCHA excedeu o prazo de 120 segundos")

A entrada da função é a URL da página verificada e a chave do site. A operação cria exatamente uma tarefa e verifica apenas seu taskId. A saída é a string de token documentada. Condições de parada são explícitas: erro na criação da tarefa, status falho, resposta pronta malformada, timeout de rede ou o prazo de 120 segundos. Um retry de transporte pode repetir a solicitação HTTP para o mesmo resultado da tarefa, mas não deve criar silenciosamente uma série de novas tarefas cobradas.

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

Aplicar o Token na Mesma Sessão do Navegador

A aplicação do token é específica para a página. Em uma integração autorizada ou página de teste controlada, escreva o token no campo de resposta documentado e invoque o caminho de callback ou submissão esperado pela página. Não copie um token para um novo navegador, outra página de produto ou contexto de loja diferente.

async def apply_recaptcha_token(page, token: str) -> None:
    applied = await page.evaluate(
        """
        (token) => {
          const fields = [...document.querySelectorAll(
            'textarea[name="g-recaptcha-response"]'
          )];
          if (fields.length === 0) return false;
          for (const field of fields) {
            field.value = token;
            field.innerHTML = token;
            field.dispatchEvent(new Event('change', { bubbles: true }));
          }
          return true;
        }
        """,
        token,
    )
if not applied:
        raise RuntimeError("campo de resposta do reCAPTCHA desapareceu antes da aplicação")

Este exemplo é intencionalmente limitado ao campo de resposta visível na página atual. Algumas implementações também exigem um callback documentado. Inspecione a página que você possui ou está autorizado a testar e conecte-se ao seu contrato de integração real. Nunca invente um nome de callback. Após a aplicação, aguarde o widget ou a rota de verificação mudarem de estado, depois retome a ação de inventário.

Extrair e Verificar o Resultado do Inventário

A verificação do inventário deve vincular o estado observado ao produto e armazenamento solicitados. Um seletor que diz "disponível" é insuficiente se a etiqueta da loja mudou silenciosamente ou a página do produto redirecionou para uma variante.

from datetime import datetime, timezone

async def read_inventory(page, expected_sku: str, expected_store: str) -> dict:
    sku = (await page.locator('[data-product-sku]').first.get_attribute('data-product-sku'))
    store = (await page.locator('[data-store-id]').first.get_attribute('data-store-id'))
    label = (await page.locator('[data-inventory-status]').first.inner_text()).strip()

    if sku != expected_sku or store != expected_store:
        raise RuntimeError("o contexto do produto ou loja mudou durante a coleta")

    normalized = {
        "Em estoque": "em_estoque",
        "Estoque limitado": "limitado",
        "Sem estoque": "sem_estoque",
    }.get(label)
    if not normalized:
        raise RuntimeError(f"etiqueta de inventário não reconhecida: {label!r}")

    return {
        "product_id": sku,
        "store_id": store,
        "availability": normalized,
        "observed_at": datetime.now(timezone.utc).isoformat(),
        "verification": "product-store-status",
    }

Os seletores são placeholders para uma página que você controla ou tem permissão para automatizar. A entrada é a página atual mais os identificadores esperados. A operação verifica a identidade antes de normalizar a etiqueta. A saída é um registro de inventário verificado. A função para em elementos ausentes, identificadores alterados ou status desconhecido. Essas paradas protegem o sistema de destino de um falha comum: transformar uma página com layout alterado em um evento falso de sem estoque.

Para produção, adicione um segundo canal de evidência quando disponível. Exemplos incluem um objeto de produto estruturado, uma resposta XHR iniciada pela página, uma etiqueta de loja do painel de retirada ou uma verificação de elegibilidade do carrinho permitida pelo seu acordo. O coletor deve exigir que a evidência de identidade e disponibilidade concorde, não solicitações duplicadas simplesmente para aumentar a confiança.

Montar a Máquina de Estados de Ponta a Ponta

Uma máquina de estados previsível torna o fluxo de trabalho observável e evita recuperação recursiva.

SCOPED
  -> OPEN_PRODUCT
  -> CONFIRM_STORE
  -> DETECT_CHECKPOINT
       -> sem desafio: READ_INVENTORY
       -> reCAPTCHA v2: CREATE_ONE_TASK
            -> pronto: APPLY_IN_SAME_SESSION
            -> falha/prazo expirado: NEEDS_REVIEW
       -> não suportado/ambíguo: NEEDS_REVIEW
  -> REPLAY_INVENTORY_ACTION_ONCE
  -> VERIFY_PRODUCT + STORE + AVAILABILITY
       -> válido: WRITE_RECORD
       -> desafio repetido: NEEDS_REVIEW
       -> contexto alterado: POLICY_DENIED

O trabalho deve carregar um ID de correlação único por cada estado. Registre o tempo da transição e o resultado, mas nunca registre o token resolvido ou a chave do cliente. A FAQ de erros e solução de problemas do CapSolver pode ajudar os operadores a distinguir falhas do provedor de falhas do navegador e aplicação.

Recuperação de Erros por Classe de Falha

Falha na detecção

Sintomas incluem chave de site ausente, página de verificação inesperada ou família de widget que o adaptador não reconhece. Capture uma captura de tela com redação e o host de nível superior, depois pare. Não envie parâmetros adivinhados ou trate cada iframe como reCAPTCHA.

Falha na tarefa do provedor

Um errorId não nulo, status falho, resultado pronto malformado ou prazo de polling expirado é uma falha no limite do provedor. Preserve o taskId, descrição de erro documentada, tempo decorrido e ID de correlação. Tente novamente apenas se a classe de erro for explicitamente transitória e o orçamento restante da tarefa permitir.

Falha na aplicação do token

O campo de resposta pode desaparecer porque a página navegou, recarregou ou mudou o contexto da loja. Não aplique o token a uma página substituta automaticamente. Reinicie as verificações de escopo e contexto, depois reinicie a verificação do produto único a partir de um estado limpo ou redirecione para revisão.

Rejeição da aplicação

O provedor pode retornar uma tarefa pronta enquanto a página rejeita a solução porque a sessão, o tempo da página, os metadados do widget ou o caminho do callback não correspondem. Classifique isso como uma falha de aplicação. Uma reexecução controlada é suficiente. Se o CAPTCHA se repetir, pare em vez de iniciar um loop.

Ambiguidade de inventário

Se a página carregar, mas a evidência de estoque estiver ausente ou conflitante, registre unknown, não out_of_stock. Notifique quando a ambiguidade ultrapassar um limite para um varejista ou modelo, pois frequentemente indica uma mudança na marcação, não um evento real de estoque.

A especificação de semântica HTTP ajuda a distinguir o status de transporte do significado da aplicação. Um 200 OK apenas descreve a resposta HTTP; não prova que uma localização foi selecionada, um CAPTCHA foi aceito ou o estoque foi retornado.

Qualidade de Dados e Controles Operacionais

A automação de estoque boa minimiza a coleta enquanto maximiza a confiança. Pesquise com uma frequência justificada pela necessidade comercial e permitida pela fonte. Cache os metadados do produto estáveis. Agende as verificações da loja com jitter dentro da janela aprovada, não com solicitações paralelas em série. Use fetches condicionais onde a fonte os suportar e pare uma execução quando a taxa de desafio ou a taxa de erro de aplicação aumentar inesperadamente.

Monitore essas métricas separadamente:

• Taxa de sucesso do carregamento da página.
• Taxa de aparição de CAPTCHA por varejista e rota.
• Taxas de tarefa pronta, falha e prazo expirado do provedor.
• Taxa de aceitação da aplicação após uma tarefa pronta.
• Taxa de extração de inventário.
• Taxa de estado desconhecido e taxa de desafio repetido.
• Latência mediana e percentil por estado de fluxo de trabalho.
• Registros suprimidos porque a identidade do produto ou loja mudou.

Não otimize apenas pela conclusão do solver. Uma alta taxa de tarefa pronta com uma baixa taxa de aceitação da aplicação indica um problema de integração. Uma alta taxa de aceitação com uma taxa crescente de estoque desconhecido indica um problema de extrator ou modelo de página. As métricas devem apontar os operadores para a camada que possui a falha.

Quando os feeds de dados alertam, deduquifique observações repetidas e defina uma regra de estabilidade. Por exemplo, notifique sobre out_of_stock apenas após duas verificações válidas separadas pelo intervalo normal de coleta, enquanto uma transição para in_stock pode exigir uma observação fresca. Mantenha a regra visível na configuração para que equipes comerciais possam auditar por que um alerta foi enviado.

Plano de Teste Pré-Produção

Teste o fluxo contra páginas que você possui ou está explicitamente autorizado a automatizar. Use fixtures para estados de estoque comuns e uma integração controlada de CAPTCHA para testes de recuperação.

1. Verifique se um produto permitido sem desafio retorna o SKU, loja e disponibilidade corretos.
2. Verifique se a detecção de reCAPTCHA retorna a URL exata e a chave de site mostrada pela página.
3. Simule falha em createTask e confirme que nenhum registro de estoque é escrito.
4. Simule resultados de processing até o prazo e confirme que apenas uma tarefa foi criada.
5. Retorne um resultado pronto sem gRecaptchaResponse e confirme que a validação de esquema falha.
6. Altere o ID da loja durante a recuperação e confirme que o fluxo para.
7. Repita o CAPTCHA após a aplicação do token e confirme que o trabalho entra em needs_review.
8. Remova o seletor de estoque e confirme que o resultado é unknown, não out_of_stock.
9. Inspeção de logs para garantir que chaves, cookies, endereços e tokens sejam redacionados.
10. Confirme que um hostname não aprovado é negado antes de uma chamada de rede ao CapSolver.

O guia para escolher uma API de resolução de CAPTCHA fornece critérios adicionais de avaliação, mas o teste de aceitação para este caso de uso permanece específico do negócio: o sistema deve retornar o produto certo, a loja certa e a disponibilidade certa após uma recuperação limitada.

Conclusão

A coleta de dados de estoque das lojas se torna confiável quando o tratamento de CAPTCHA é tratado como um estado controlado dentro de um fluxo de trabalho verificado de varejo. Preserve o contexto do produto e loja, crie uma tarefa documentada, aplique a solução na mesma sessão autorizada, repita a ação de inventário uma vez e publique os dados apenas após as verificações de identidade e disponibilidade passarem. CapSolver fornece a infraestrutura de tarefa CAPTCHA; seu coletor permanece responsável pelo escopo, limites de taxa, qualidade dos dados e condições de parada.

Perguntas Frequentes

Q: Qual é a saída mínima para a coleta de dados de estoque das lojas?

A saída mínima confiável contém um ID de produto canônico, ID de loja ou região, disponibilidade normalizada, horário da observação e a evidência usada para verificar o estado. Uma página em branco ou checkpoint falhado nunca deve ser convertido em "sem estoque".

Q: Por que a mesma sessão do navegador deve ser preservada durante a recuperação de CAPTCHA?

A mesma sessão preserva a página, cookies, seleção do produto, seleção da loja e ciclo de vida do widget associado ao checkpoint. Mover o resultado para outro contexto pode causar rejeição ou associar a observação à loja errada.

Q: Quantas tentativas de CAPTCHA uma tarefa de estoque deve fazer?

Use um orçamento pequeno e explícito: uma tarefa e uma reexecução controlada é um padrão prático. Um desafio repetido deve entrar em needs_review para que a integração possa ser inspecionada sem um loop caro ou disruptivo.

Q: Uma tarefa pronta do CapSolver prova que o estoque foi coletado?

Não. Uma tarefa pronta prova apenas que o provedor retornou uma solução. O navegador deve aceitá-la, e a aplicação ainda deve retornar um produto, loja e estado de estoque reconhecidos.

Q: Este fluxo pode coletar estoque de portais privados de varejistas?

Apenas quando o proprietário do portal autorizou explicitamente essa automação e o fluxo estiver em conformidade com o acordo aplicável e a lei. A capacidade técnica não concede permissão para acessar dados privados, restritos, sensíveis ou não autorizados.