Scarnox · Blog

API solver captcha: come funziona e come chiamarla

Un'API solver captcha è un servizio web che si chiama via HTTP. Le invii i dettagli di un captcha, cioè il tipo di task, la sitekey della pagina e l'URL della pagina, e restituisce un token che il sito accetta come prova che la sfida è stata superata. L'endpoint di Scarnox funziona così ed è sincrono, quindi una sola richiesta ti dà la risposta.

Questa guida copre la richiesta, la risposta, la forma degli errori e i dettagli che determinano se un'integrazione regge in produzione. Se vuoi prima uno script eseguibile, inizia da Come risolvere un PopularCaptcha in Python.

Cosa fa e cosa non fa l'API

Il tuo codice trova il captcha su una pagina, legge la sua sitekey e la invia al solver. Il solver restituisce un token. Il tuo codice scrive quel token nel campo del form che il sito si aspetta e invia il form.

Il solver non carica la tua pagina, non clicca nulla e non invia il tuo form. Produce solo il token. Tenere presente questo confine rende il resto dell'integrazione più facile da ragionare: tutto ciò che riguarda la tua sessione, i cookie e il timing delle richieste resta nel tuo codice.

Oggi l'unico tipo di task attivo è PopularCaptcha, proxyless, cioè PopularCaptchaTaskProxyless. Altri tipi di captcha sono nella roadmap. La guida ai tipi di captcha elenca quali sono quali.

L'endpoint

Invia una richiesta POST a:

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

Il corpo descrive il task:

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

I tre campi obbligatori sono:

captcha_type: il tipo di task. Per le risoluzioni live oggi è PopularCaptchaTaskProxyless.
site_key: la sitekey letta dalla pagina. Le sitekey di PopularCaptcha sono UUID.
site_url: l'URL della pagina dove compare il captcha. Usa la pagina reale, non la home, perché il token è legato alla pagina che ha mostrato il widget.

Esistono tre campi facoltativi. proxy accetta un valore nel formato http://user:pass@host:port e si usa con i tipi di task con proxy. rqdata e is_invisible servono per varianti specifiche del widget. L'elenco completo dei tipi di task e dei dettagli dei campi è nella documentazione API.

Sincrono significa niente polling

La chiamata si blocca finché il token è pronto. Non fai polling, e in questo flusso non c'è una seconda richiesta "ottieni risultato". Imposta il timeout del client HTTP a circa 185 secondi, così una risoluzione lenta non sembra un errore di rete.

In Python con la libreria requests, il codice è questo:

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Leggi la chiave da una variabile d'ambiente invece di scriverla nello script. Chi può leggere il sorgente non dovrebbe poter usare il tuo saldo.

Leggere la risposta

Una risoluzione riuscita restituisce errorId uguale a 0, il token dentro solution e un campo cost:

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

Una risoluzione fallita restituisce un errorId diverso da 0, più un errorCode leggibile dalla macchina e un errorDescription leggibile da una persona:

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Controlla errorId nel corpo a ogni chiamata. Non dare per scontato che una richiesta HTTP completata significhi che hai un token. La regola più importante è questa: paghi solo quando errorId è 0. Le risoluzioni fallite sono gratuite. Per le tariffe attuali, consulta la pagina dei prezzi.

Durata del token

I token PopularCaptcha scadono in circa due minuti. Invia il token appena lo ricevi. Non memorizzarlo per un uso successivo e non risolvere in anticipo rispetto all'invio del form. Se il tuo codice esegue più passaggi tra l'ottenimento del token e l'invio del form, sposta la risoluzione all'ultimo momento.

Mettere il token nel form

La maggior parte dei siti legge la risposta di PopularCaptcha da un campo del form chiamato h-captcha-response. Molti accettano anche g-recaptcha-response con lo stesso valore, quindi inviare entrambi è una scelta comune e sicura:

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

Se il form non accetta il token, la causa di solito è una sitekey o un URL della pagina che non corrispondono alla pagina su cui era realmente il widget. Ricontrolla i valori prima di dare la colpa al solver.

Gestione degli errori

Un'integrazione di produzione richiede un breve elenco di abitudini:

Controlla errorId e registra errorCode a ogni chiamata. Il codice è la prima cosa che chiederà il supporto.
Riprova le risoluzioni fallite con un piccolo backoff. Poiché le risoluzioni fallite non sono addebitate, un nuovo tentativo non ti costa una risoluzione, ma un ciclo serrato fa comunque perdere tempo e può superare i tuoi limiti di frequenza.
Imposta un timeout del client di circa 185 secondi, e tratta un timeout come un errore da riprovare, non come un successo.
Tieni il token e l'invio del form vicini nel tempo, perché il token scade rapidamente.

La guida ai retry e alla gestione degli errori approfondisce ciascuno di questi punti.

Come iniziare

Crea un account e puoi iniziare con crediti di prova gratuiti, senza carta di credito. Poi esegui la richiesta qui sopra su una pagina di test che controlli, e verifica che il form accetti il token prima di collegarlo a qualcosa di importante.