Skip to main content
Este artigo apresentará uma descrição da integração da API de reconhecimento do protocolo hCaptcha, que permite aos usuários realizar a validação sem precisar identificar e clicar nas imagens do captcha hCaptcha, bastando enviar a Chave do Website para realizar a decodificação automática em segundo plano e completar a validação.

​
Processo de Solicitação

Para usar a API de reconhecimento do protocolo hCaptcha, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro. Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no painel de controle.
📘 Documentação Completa: API de Reconhecimento do Protocolo hCaptcha →

​
Uso Básico

Primeiro, entenda a forma básica de uso, que consiste em inserir a URL do site que precisa processar o captcha hCaptcha, e você poderá obter o resultado processado. Primeiro, é necessário passar um campo website_url, nosso site de exemplo é: https://accounts.hcaptcha.com/demo, precisamos obter a website_key na página website_url, primeiro abra esta página, pressione F12 para acessar o console e, em seguida, faça uma busca global na página Element por hcaptcha-demo, e podemos obter o seguinte resultado:

A string correspondente a data-sitekey é o valor da website_key, abaixo estão os resultados dos parâmetros específicos:

Podemos ver que aqui configuramos os Headers da Requisição, incluindo:
  • accept: o formato de resposta desejado, aqui preenchido como application/json, ou seja, formato JSON.
  • authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Além disso, configuramos o Corpo da Requisição, incluindo:
  • website_url: a URL do site que precisa processar o captcha.
  • website_key: o identificador da chave do site no hCaptcha.
Após a seleção, podemos notar que o código correspondente também foi gerado à direita, como mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e aqui obtivemos 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 pegar 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:
Em seguida, use esse task_id para fazer polling em POST /captcha/tasks (recomendado a cada 3~5 segundos) para obter o resultado:
Durante o processamento, retornará status: processing:
Quando o processamento for concluído, retornará status: ready e o token:
Descrição de cobrança: no modo assíncrono, a criação de tarefas e o polling “em processamento” não geram cobrança; apenas quando o token é obtido com sucesso é cobrado uma vez (o mesmo preço do modo síncrono). Portanto, cancelar tarefas que ainda não foram concluídas durante a rotação não gerará custos. /captcha/tasks é aplicável a todas as interfaces de captcha (token e reconhecimento, como hcaptcha, recaptcha2, recaptcha3, recognition/* etc.) e você pode usar o mesmo task_id para polling.

​
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 permitir que os usuários não precisem reconhecer e clicar nas imagens do captcha hCaptcha, bastando enviar a Website Key para realizar a decodificação automática em segundo plano e completar a verificação. 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.