Skip to main content
Este artigo apresenta um guia de integração para a API de reconhecimento do protocolo hCaptcha, que permite aos usuários decodificar automaticamente o hCaptcha em segundo plano apenas enviando a Website Key, sem a necessidade de identificar e clicar nas imagens do captcha.

​
Processo de Solicitação

Para usar a API de reconhecimento do protocolo hCaptcha, primeiro acesse o Console Ace Data Cloud para obter seu Token de API, para uso futuro. Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login para se registrar e entrar, e após isso retornará automaticamente para esta página. Um único Token de API pode ser usado para chamar todos os serviços da plataforma, não é necessário solicitar separadamente para cada serviço. Na primeira solicitação, será concedida uma cota gratuita para teste; quando a cota acabar, você pode recarregar saldo geral no Console.
📘 Documentação completa: API de Reconhecimento do Protocolo hCaptcha →

​
Uso Básico

Primeiro, entenda o modo básico de uso, que é inserir a URL do site que contém o hCaptcha a ser processado para obter o resultado processado. Inicialmente, é necessário passar um campo simples website_url. Nosso site de exemplo é: https://accounts.hcaptcha.com/demo. Precisamos obter o website_key na página website_url. Para isso, abra essa página, pressione F12 para abrir o console, e na aba Elementos faça uma busca global por hcaptcha-demo. Podemos obter o seguinte resultado:

A string correspondente ao atributo data-sitekey é o valor do website_key. Abaixo estão os parâmetros específicos:

Aqui configuramos os Request Headers, incluindo:
  • accept: o formato de resposta desejado, aqui definido como application/json, ou seja, formato JSON.
  • authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Também configuramos o Request Body, incluindo:
  • website_url: a URL do site cujo captcha será processado.
  • website_key: o identificador da chave do site no hCaptcha.
  • rqdata: opcional. Desafios do hCaptcha Enterprise podem fornecer data-rqdata na página; para esses desafios, preencha com o valor original; para hCaptcha comum, não é necessário.
  • proxy: opcional, proxy próprio (Bring Your Own Proxy). Se configurado, o sistema usará o IP do proxy fornecido para resolver o captcha, útil para controlar a qualidade do IP de saída (por exemplo, evitar bloqueios do site alvo por IPs de proxy públicos que retornam 410 Gone). O formato é scheme://[user:pass@]host:port, onde scheme suporta http/https/socks4/socks5, por exemplo http://user:pass@1.2.3.4:8080. Se não preenchido, será usado o proxy padrão da plataforma.
Após a seleção, você verá que o código correspondente é gerado à direita, conforme mostrado na imagem:

Clique no botão “Try” para testar. Conforme mostrado na imagem acima, obtemos o seguinte resultado:
可以看到我们得到了处理 hCaptcha验证码 的验证结果，然后我们可以用于POST或模拟提交给目标网站，一次性使用，有效期120s，建议在60s内使用，接下来将提供一段CURL版本将处理后token提交到目标网站来通过Recaptcha2验证码。 首先我们需要获取网站是如何发送POST请求，这样我们才能将生成的token传入进去，我们需要先打开F12控制台，然后人工先通过一下，最后我们可以看到网站发送了一个POST请求，我们只需要查看这次的POST请求构造，具体的过程如下：
  • 先人工通过验证，具体的如下图：

  • 再点击submit，观看控制台的network变化，具体的如下图：

  • 分析此次提交的POST请求构造，最后可以右键该请求复制CURL的代码，具体的如下图：

由上图分析可知，此次POST请求的URL为：https://accounts.hcaptcha.com/demo，我们仅需要提交参数 g-recaptcha-response、h-captcha-response 和 email，然后我们只需要将处理后的token传入下面的data中即可，调用token验证所对应CURL代码如下：
调用token验证所对应的Python代码如下：
然后我们观察控制台变得了这样的结果：

最后我们就通过了hCaptcha验证码的验证。 另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：
Python 的对接代码如下：

​
Modo Assíncrono (async)

Por padrão, a API é síncrona e bloqueante: uma solicitação aguardará até que o token seja processado antes de retornar. Se você estiver fazendo rotação de múltiplos solucionadores (multi-solver rotation) e quiser “submeter a tarefa e imediatamente obter o task_id, ir agendar outros solucionadores e depois voltar para ler o resultado”, você pode passar async: true no corpo da solicitação. Ao passar async: true, a interface retornará imediatamente um task_id, sem bloquear a espera:
Se precisar verificar o progresso ativamente, você pode usar esse task_id para consultar POST /captcha/tasks (recomendado a cada 3~5 segundos). Esta interface não acionará ou avançará o processamento da tarefa; mesmo que você não consulte, perca a conexão ou saia do cliente, o servidor continuará processando:
Durante o processamento, retornará status: processing:
Quando o processamento estiver concluído, retornará status: ready e o token:
Descrição de cobrança: no modo assíncrono, a criação de tarefas e a leitura do status “processando” não são cobradas; o cliente será cobrado uma vez ao ler o resultado bem-sucedido pela primeira vez (consistente com o comportamento existente e o preço do modo síncrono). O servidor avançará a tarefa por conta própria, mas não cobrará antecipadamente porque a conclusão ocorreu no backend. Se a tarefa não for concluída com sucesso em 120 segundos, será encerrada com HTTP 504 timeout, sem cobrança. /captcha/tasks não é responsável por avançar a tarefa.

​
Tratamento de Erros

Ao chamar a API, se encontrar um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:
  • 400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
  • 429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
  • 500 api_error: Erro interno do servidor, algo deu errado no servidor.

​
Exemplo de Resposta de Erro

​
Conclusão

Por meio deste documento, você já entendeu como usar a API de reconhecimento do protocolo hCaptcha para que os usuários não precisem reconhecer e clicar nas imagens do captcha hCaptcha, podendo realizar a decodificação automática em segundo plano apenas enviando a Website Key. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.