> ## 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 di query per i compiti di verifica (compiti asincroni del server)

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

Questo documento descrive l'interfaccia di query per i compiti di verifica `POST /captcha/tasks`. Quando chiami qualsiasi interfaccia di verifica (serie token o serie di riconoscimento) passando `async: true`, l'interfaccia restituirà immediatamente un `task_id`, il server prenderà immediatamente in carico e continuerà a elaborare; puoi utilizzare quel `task_id` per interrogare il risultato finale, ma la query non è una condizione per continuare l'esecuzione del compito. Adatto a scenari come il cambio di più risolutori (multi-solver rotation): dopo aver inviato il compito, ottieni immediatamente il `task_id`, vai a programmare altri risolutori e torna più tardi a leggere i risultati.

> 📘 Documentazione interattiva completa (incluso il debug online): [API di query per i compiti di verifica →](https://platform.acedata.cloud/documents/captcha-tasks)

## Processo di richiesta

Per utilizzare questa interfaccia, prima vai al [Pannello di controllo di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da tenere come riserva. **Un API Token è sufficiente per chiamare tutti i servizi della piattaforma, non è necessario richiederne uno per ogni servizio.**

## Utilizzo di base

### Primo passo: creare un compito in modo asincrono

Nel corpo della richiesta di qualsiasi interfaccia di verifica, passa `async: true`, l'interfaccia restituirà immediatamente un `task_id` (HTTP 201), senza bloccare l'attesa:

```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"
}
```

### Secondo passo (opzionale): interrogare i risultati con task\_id

Se desideri controllare attivamente i progressi, puoi utilizzare il `task_id` restituito nel passo precedente per interrogare `POST /captcha/tasks` (si consiglia ogni 3\~5 secondi). Questa interfaccia non attiverà o accelererà l'elaborazione del compito; la lettura dei risultati pronti seguirà il comportamento di regolamento una tantum esistente:

```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 l'elaborazione verrà restituito `status: processing`:

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

Al termine dell'elaborazione verrà restituito `status: ready` e il campo risultato corrispondente—la struttura del campo è completamente identica a quella della modalità sincrona:

* **serie token** (hcaptcha, recaptcha2, recaptcha3) restituisce `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......"
}
```

* **categoria riconoscimento** (recognition/recaptcha2, recognition/hcaptcha) restituisce `solution`; **recognition/image2text** restituisce `text`.

`/captcha/tasks` è comune a tutte le interfacce di verifica (serie token e riconoscimento), puoi semplicemente fare polling con lo stesso `task_id`.

Il server continua a elaborare dall'inizio della creazione, per un massimo di 120 secondi. Se all'ultima query della scadenza non si ottiene ancora un risultato, verrà restituito un HTTP 504 persistente. Questo stato è finale, il client dovrebbe interrompere il polling; ripetere la query dello stesso `task_id` restituirà stabilmente lo stesso risultato di errore:

```json theme={null}
{
  "detail": "Il compito di verifica è scaduto.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}
```

Le risposte finali `status: ready` e HTTP 504 includeranno entrambi i campi temporali.

* `started_at`, tempo di inizio dell'elaborazione del compito, timestamp Unix (secondi, float).
* `finished_at`, tempo di produzione del risultato del compito, timestamp Unix (secondi, float). Non verrà restituito se è ancora in elaborazione.
* `elapsed`, tempo di elaborazione del compito, unità in secondi (float, con 3 cifre decimali). Non verrà restituito se è ancora in elaborazione.

## Spiegazione della fatturazione

In modalità asincrona, la creazione di compiti e la lettura dello stato "in elaborazione" non comportano costi; **il cliente verrà addebitato una volta al primo successo nella lettura dei risultati** (coerente con il comportamento esistente e il prezzo della modalità sincrona). Il server gestirà autonomamente il compito, ma non addebiterà in anticipo se il backend completa prima. I compiti non riusciti entro la scadenza di 120 secondi verranno terminati con HTTP 504 e non comporteranno costi.

## Gestione degli errori

Quando chiami questa interfaccia, se si verifica un errore, verrà restituito il codice di errore e le informazioni corrispondenti. Ad esempio:

* `400 invalid_request`: la richiesta manca del parametro `task_id`.
* `401 invalid_token`: non autorizzato, il token di autorizzazione è invalido o mancante.
* `404 not_found`: `task_id` non esiste o non appartiene all'account corrente.
* `504 timeout`: il compito è stato terminato e non ha prodotto risultati; si prega di interrompere il polling di quel `task_id`. Questo errore non comporterà costi.

### Esempio di risposta di errore

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "compito non trovato"
  }
}
```


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