> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare Turnstile Protocolo de Reconhecimento API Integração

> Cloudflare Turnstile Captcha Service API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentação Completa: [API de Reconhecimento do Protocolo Cloudflare Turnstile →](https://platform.acedata.cloud/documents/captcha-token-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:

```json theme={null}
{
  "token": "0.mNQ2f9uP6mQ0y3H5Q8bqO7iM......",
  "started_at": 1784885653.0,
  "finished_at": 1784885665.4,
  "elapsed": 12.4
}
```

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:

```python theme={null}
import requests

token = '{token}'

data = {
    'cf-turnstile-response': token
}

response = requests.post('https://react-turnstile.vercel.app', data=data)

if response.status_code == 200:
    print(response.text)
```

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:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/turnstile' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
  "website_url": "https://react-turnstile.vercel.app"
}'
```

O código de integração em Python é o seguinte:

```python theme={null}
import requests

url = "https://api.acedata.cloud/captcha/token/turnstile"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
    "website_url": "https://react-turnstile.vercel.app"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 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:

```json theme={null}
{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

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:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'
```

Durante o processamento, retornará `status: processing`; ao concluir, retornará `status: ready` e o token:

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "0.mNQ2f9uP6mQ0y3H5Q8bqO7iM......"
}
```

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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.