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

# API de Consulta de Tarefas de Captcha (Tarefa Assíncrona do Servidor) - Instruções de Integração

> hCaptcha verification code recognition service API guide - Ace Data Cloud

Este documento apresenta a interface de consulta de tarefas assíncronas de captcha `POST /captcha/tasks`. Quando você chama qualquer interface de captcha (série token ou série recognition) e passa `async: true`, a interface retornará imediatamente um `task_id`, o servidor assumirá e continuará a processar; você pode usar esse `task_id` para consultar o resultado final, mas a consulta não é uma condição para a continuação da execução da tarefa. É aplicável a cenários como rotação de múltiplos decodificadores (multi-solver rotation): após enviar a tarefa, você obtém imediatamente o `task_id`, pode agendar outros decodificadores e voltar mais tarde para ler o resultado.

> 📘 Documentação interativa completa (incluindo depuração online): [API de Consulta de Tarefas de Captcha →](https://platform.acedata.cloud/documents/captcha-tasks)

## Processo de Solicitação

Para usar esta interface, 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 mantido em reserva. **Um Token de API é suficiente para chamar todos os serviços da plataforma, não é necessário solicitar um para cada serviço.**

## Uso Básico

### Passo 1: Criar Tarefa de Forma Assíncrona

No corpo da solicitação de qualquer interface de captcha, passe `async: true`, a interface retornará imediatamente um `task_id` (HTTP 201), sem bloquear a espera:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "website_url": "https://www.google.com/recaptcha/api2/demo",
  "async": true
}'
```

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

### Passo 2 (Opcional): Consultar Resultados com task\_id

Se precisar verificar o progresso ativamente, você pode usar o `task_id` retornado na etapa anterior para consultar `POST /captcha/tasks` (recomenda-se a cada 3\~5 segundos). Esta interface não acionará ou avançará o processamento da tarefa; ao ler resultados prontos, o comportamento de liquidação única existente será mantido:

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

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

Quando o processamento estiver concluído, retornará `status: ready` e o campo de resultado correspondente — a estrutura do campo é idêntica ao modo síncrono:

* **Série token** (hcaptcha, recaptcha2, recaptcha3) retorna `token`:

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "started_at": 1784885653.0,
  "finished_at": 1784885665.4,
  "elapsed": 12.4,
  "token": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMB......"
}
```

* **Classificação recognition** (recognition/recaptcha2, recognition/hcaptcha) retorna `solution`; **recognition/image2text** retorna `text`.

`/captcha/tasks` é aplicável a todas as interfaces de captcha (séries token e recognition), basta usar o mesmo `task_id` para a consulta.

O servidor continuará a processar desde a criação, por um máximo de 120 segundos. Se na última consulta antes do prazo não houver resultado, retornará um HTTP 504 persistente. Esse estado é terminal, o cliente deve parar a consulta; consultas repetidas ao mesmo `task_id` retornarão consistentemente o mesmo resultado de falha:

```json theme={null}
{
  "detail": "A tarefa de captcha expirou.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}
```

As respostas de estado `ready` e HTTP 504 incluirão campos de temporização.

* `started_at`, hora de início do processamento da tarefa, timestamp Unix (segundos, ponto flutuante).
* `finished_at`, hora de produção do resultado da tarefa, timestamp Unix (segundos, ponto flutuante). Não será retornado enquanto estiver em processamento.
* `elapsed`, tempo de processamento da tarefa, em segundos (ponto flutuante, com 3 casas decimais). Não será retornado enquanto estiver em processamento.

## Instruções de Cobrança

No modo assíncrono, a criação de tarefas e a leitura do estado "em processamento" 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 existente e o preço do modo síncrono). O servidor avançará a tarefa autonomamente, mas não cobrará antecipadamente se o processamento em segundo plano for concluído antes. Tarefas que não forem bem-sucedidas dentro do prazo de 120 segundos serão encerradas com HTTP 504 e não serão cobradas.

## Tratamento de Erros

Ao chamar esta interface, se ocorrer um erro, retornará o código e a mensagem de erro correspondentes. Por exemplo:

* `400 invalid_request`: A solicitação está faltando o parâmetro `task_id`.
* `401 invalid_token`: Não autorizado, Token de autorização inválido ou ausente.
* `404 not_found`: `task_id` não existe ou não pertence à conta atual.
* `504 timeout`: A tarefa foi encerrada e não produziu resultados; por favor, pare de consultar esse `task_id`. Essa falha não resultará em cobrança.

### Exemplo de Resposta de Erro

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "tarefa não encontrada"
  }
}
```


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