Skip to main content
Este artigo apresentará uma descrição da integração da API de reconhecimento do protocolo Cloudflare Turnstile, que permite aos usuários realizar a verificação sem precisar identificar e clicar no captcha Turnstile, 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 Cloudflare Turnstile, 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á retornado à 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 para que você possa experimentar; quando o crédito estiver baixo, você pode recarregar o saldo geral no painel de controle.
📘 Documentação Completa: API de Reconhecimento do Protocolo Cloudflare Turnstile →

​
Uso Básico

Primeiro, entenda a forma básica de uso, que consiste em inserir a URL do site que precisa processar o captcha Turnstile, obtendo assim o resultado processado. Primeiro, é necessário passar um campo website_url, nosso site de exemplo é: https://react-turnstile.vercel.app, precisamos obter a website_key na página website_url. Para isso, abra essa página, pressione F12 para acessar o console, e faça uma busca global por cf-turnstile na aba Element, onde você encontrará o elemento do contêiner que abriga o Turnstile, e a string correspondente ao data-sitekey será o valor da website_key. Os cabeçalhos de solicitação configurados incluem:
  • 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, o corpo da solicitação inclui:
  • website_url: a URL do site que precisa processar o captcha.
  • website_key: o identificador da chave do site no Cloudflare Turnstile.
  • action: parâmetro opcional, necessário apenas se o site de destino tiver configurado uma action personalizada para o componente Turnstile.
  • cdata: parâmetro opcional, necessário apenas se o site de destino tiver configurado um cData personalizado para o componente Turnstile.
Clique no botão “Try” para realizar o teste, e assim obtemos o seguinte resultado:
O resultado retornado contém vários campos, descritos a seguir:
  • token, o resultado da verificação após o processamento da tarefa do captcha Cloudflare Turnstile.
  • started_at, finished_at: o tempo em que a solicitação começou a ser processada e o resultado foi gerado, em timestamp Unix (segundos, ponto flutuante).
  • elapsed: o tempo total gasto no processamento (segundos).
Podemos ver que obtivemos o resultado da verificação do captcha Turnstile, que pode ser usado para POST ou simular o envio ao site de destino, sendo de uso único, com validade de 120s, recomendando-se o uso dentro de 60s. Ao enviar, normalmente o token é enviado como parâmetro cf-turnstile-response para o site de destino, o código Python correspondente para chamar a verificação do token é o seguinte:
Além disso, se você deseja 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 uma rotação de múltiplos solucionadores (multi-solver rotation) e desejar “submeter a tarefa e imediatamente obter o task_id, para então 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; ao concluir, 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 apenas porque o processamento foi concluído 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.
Nota: O Cloudflare Turnstile atualmente não suporta proxy próprio (Bring Your Own Proxy), portanto, esta interface não aceita o parâmetro proxy; se passado, retornará 400 invalid_proxy.

​
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 invalid_proxy：Solicitação inválida, proxy não é suportado para este tipo de captcha.
  • 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 Cloudflare Turnstile para permitir que os usuários não precisem reconhecer e clicar no captcha Turnstile, bastando enviar a Chave do Website 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.