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

​
Processo de Solicitação

Para usar a API de reconhecimento do protocolo Recaptcha2, 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 vem com 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 Recaptcha2 →

​
Uso Básico

Primeiro, entenda a forma básica de uso, que é inserir a URL do site que precisa processar o captcha, e você poderá obter o resultado processado. Primeiro, é necessário passar um campo website_url, nosso site de exemplo é: https://www.google.com/recaptcha/api2/demo, precisamos obter a website_key na página website_url, primeiro abra esta página, pressione F12 para acessar o console, e então faça uma busca global na página Element por recaptcha-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 Cabeçalhos da Solicitaçã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 Solicitação, incluindo:
  • website_url: a URL do site que precisa processar o captcha.
  • website_key: o identificador da chave do site no Recaptcha2.
  • proxy: opcional, traga seu próprio proxy (Bring Your Own Proxy). Após a configuração, o serviço usará o IP do proxy fornecido para decifrar o captcha, controlando a qualidade do IP de saída (por exemplo, evitando que o IP de proxy público seja bloqueado pelo site de destino e retorne 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á utilizado o proxy padrão da plataforma.
Após a seleção, você pode 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:
O resultado contém vários campos, descritos a seguir:
  • token, o resultado da verificação após o processamento da tarefa Recaptcha2.
  • started_at, finished_at: o tempo de início e término do processamento desta solicitação, em timestamp Unix (segundos, ponto flutuante).
  • elapsed: o tempo total gasto para este processamento (segundos).
Podemos ver que obtivemos o resultado da verificação do Recaptcha2, que podemos usar para POST ou simular o envio para o site de destino, sendo de uso único, com validade de 120s, recomendando-se o uso dentro de 60s. A seguir, será fornecido um trecho em Python para enviar o token processado ao site de destino para passar pelo Recaptcha2. Primeiro, precisamos descobrir como o site envia a solicitação POST, para que possamos inserir o token gerado. Precisamos abrir o console F12 e realizar a verificação manualmente. Por fim, podemos ver que o site enviou uma solicitação POST. Precisamos apenas verificar a construção dessa solicitação POST, e o processo específico é o seguinte:
  • Primeiro, verifique manualmente, conforme mostrado na imagem abaixo:

  • Em seguida, clique em enviar e observe as mudanças na rede do console, conforme mostrado na imagem abaixo:

  • Analise a construção da solicitação POST desta submissão, e por fim, você pode clicar com o botão direito nessa solicitação para copiar o código CURL, conforme mostrado na imagem abaixo:

A partir da análise da imagem acima, podemos ver que a URL da solicitação POST é: https://www.google.com/recaptcha/api2/demo, e precisamos apenas enviar o parâmetro g-recaptcha-response, em seguida, precisamos apenas passar o token processado para os dados abaixo, o código CURL específico para chamar o token para verificação é o seguinte:
O código Python correspondente para chamar a verificação do token é o seguinte:
Em seguida, executamos o código e observamos que o console ficou com o seguinte resultado:

Por fim, conseguimos passar pela verificação do protocolo Recaptcha2. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, por exemplo, o código CURL é o seguinte:
O código de integração em Python é o seguinte:

​
Modo Assíncrono (async)

Por padrão, a API é bloqueante e síncrona: 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 voltar mais tarde 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; a cobrança ocorre uma vez quando o cliente lê o resultado com sucesso pela primeira vez (consistente com o comportamento atual 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 tarefa foi concluída no backend. Se a tarefa não for bem-sucedida 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 ocorrer 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

Através deste documento, você já entendeu como usar a API de reconhecimento do protocolo Recaptcha2 para que os usuários não precisem reconhecer e clicar nas imagens do captcha Recaptcha2, podendo realizar a validação 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.