Scarnox · Blog

API de solver de captcha: como funciona e como chamá-la

Uma API de solver de captcha é um serviço web que você chama por HTTP. Você envia os detalhes do captcha, que são o tipo de tarefa, o sitekey da página e a URL da página, e ela devolve um token que o site aceita como prova de que o desafio foi cumprido. O endpoint da Scarnox funciona assim e é síncrono, então uma única requisição já traz a resposta.

Este guia cobre a requisição, a resposta, o formato dos erros e os detalhes que decidem se uma integração se sustenta em produção. Se você quer um script executável primeiro, comece por Como resolver PopularCaptcha em Python.

O que a API faz e o que não faz

O seu código encontra o captcha em uma página, lê o sitekey e o envia ao solver. O solver devolve um token. O seu código escreve esse token no campo do formulário que o site espera e envia o formulário.

O solver não carrega a sua página, não clica em nada e não envia o seu formulário. Ele apenas produz o token. Ter essa fronteira em mente facilita o raciocínio sobre o resto da integração: tudo o que diz respeito à sua sessão, aos cookies e ao tempo das requisições continua no seu código.

Hoje o único tipo de tarefa disponível é o PopularCaptcha, proxyless, que é PopularCaptchaTaskProxyless. Outros tipos de captcha estão no roteiro. O guia dos tipos de captcha lista o que é o quê.

O endpoint

Envie uma requisição POST para:

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

O corpo descreve a tarefa:

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

Os três campos obrigatórios são:

captcha_type: o tipo de tarefa. Para resoluções ativas hoje, é PopularCaptchaTaskProxyless.
site_key: o sitekey lido da página. Os sitekeys do PopularCaptcha são UUIDs.
site_url: a URL da página onde o captcha aparece. Use a página real, não a página inicial, porque o token fica vinculado à página que exibiu o widget.

Existem três campos opcionais. proxy recebe um valor no formato http://user:pass@host:port e é usado com os tipos de tarefa com proxy. rqdata e is_invisible são para variantes específicas do widget. A lista completa de tipos de tarefa e detalhes de campos está na referência da API.

Síncrono significa sem polling

A chamada fica bloqueada até o token estar pronto. Você não faz polling, e não existe uma segunda requisição de "obter resultado" nesse fluxo. Defina o timeout do seu cliente HTTP em cerca de 185 segundos, para que uma resolução lenta não pareça uma falha de rede.

Em Python com a biblioteca requests, fica assim:

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Leia a chave de uma variável de ambiente, em vez de escrevê-la no script. Quem puder ler o código-fonte não deve conseguir usar o seu saldo.

Lendo a resposta

Uma resolução bem-sucedida retorna errorId com valor 0, o token dentro de solution e um campo cost:

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

Uma resolução com falha retorna um errorId diferente de 0, além de um errorCode legível por máquina e um errorDescription legível por humanos:

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Verifique o errorId no corpo em toda chamada. Não presuma que uma requisição HTTP concluída significa que você tem um token. A regra mais importante é esta: você só é cobrado quando errorId é 0. Resoluções com falha são gratuitas. Para os valores atuais, veja a página de preços.

Validade do token

Os tokens do PopularCaptcha expiram em cerca de dois minutos. Envie o token assim que o receber. Não guarde tokens para uso posterior e não resolva antes do envio do formulário. Se o seu código executa várias etapas entre obter o token e enviar o formulário, mova a resolução para o último momento possível.

Colocando o token no formulário

A maioria dos sites lê a resposta do PopularCaptcha de um campo de formulário chamado h-captcha-response. Muitos também aceitam g-recaptcha-response com o mesmo valor, então enviar os dois é uma escolha segura e comum:

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

Se o formulário não aceitar o token, a causa geralmente é um sitekey ou uma URL de página que não correspondem à página em que o widget realmente estava. Confira os valores duas vezes antes de culpar o solver.

Tratamento de erros

Uma integração em produção precisa de um conjunto curto de boas práticas:

Verifique errorId e registre errorCode em toda chamada. O código é o que o suporte vai pedir primeiro.
Refaça as resoluções com falha usando um backoff curto. Como resoluções com falha são gratuitas, uma nova tentativa não custa uma resolução, mas um loop apertado ainda desperdiça tempo e pode atingir os seus próprios limites de taxa.
Defina um timeout de cliente de cerca de 185 segundos e trate o timeout como um erro a ser repetido, não como sucesso.
Mantenha o token e o envio do formulário próximos no tempo, já que o token expira rapidamente.

O guia de tratamento de erros e retentativas aprofunda cada um desses pontos.

Primeiros passos

Crie uma conta e você pode começar com crédito de teste grátis, sem cartão. Depois, execute a requisição acima em uma página de teste que você controla e confirme que o formulário aceita o token antes de conectá-lo a qualquer coisa importante.