Recaptcha3 Protocol Recognition API Integration Instructions

Questo documento presenterà una guida all’integrazione dell’API di riconoscimento del protocollo Recaptcha3, che consente agli utenti di completare la verifica senza dover riconoscere e selezionare le immagini del codice captcha di Recaptcha3, ma semplicemente inviando la Website Key per attivare la decodifica automatica in background.

Processo di richiesta

Per utilizzare l’API di riconoscimento del protocollo Recaptcha3, prima di tutto vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro.

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza dover richiedere separatamente per ogni servizio. La prima richiesta include un credito gratuito, che consente di provare senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.

📘 Documentazione completa: API di riconoscimento del protocollo Recaptcha3 →

Utilizzo di base

Iniziamo a comprendere le modalità di utilizzo di base; rispetto a Recaptcha2, è necessario fornire un parametro aggiuntivo page_action, il quale deve essere ottenuto dal codice. L’URL di esempio per il test della velocità di rete è: https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php, di seguito viene mostrato un metodo per ottenerlo:

Metodo rapido:

Apri f12, quindi cerca nella pagina Elementi .execute(; nell’area evidenziata in rosso possiamo vedere il parametro action, mentre dopo execute c’è una stringa, che è anche il contenuto necessario in seguito, come mostrato nell’immagine sottostante.

Inoltre, è necessario inserire l’URL del sito web che deve elaborare il captcha per ottenere il risultato elaborato; prima di tutto, è necessario semplicemente passare un campo website_url, e infine è necessario inserire il parametro website_key, che può essere ottenuto nel testo precedente, anch’esso una stringa dopo execute. Possiamo quindi compilare i contenuti corrispondenti nell’interfaccia, come mostrato nell’immagine:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, tra cui:

accept: il formato della risposta desiderata, qui impostato su application/json, ovvero formato JSON.
authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.

Inoltre, abbiamo impostato il corpo della richiesta, che include:

page_action: deve essere ottenuto dal codice del sito web del captcha.
website_url: l’URL del sito web che deve elaborare il captcha.
website_key: l’identificatore della chiave del sito in Recaptcha3.

Dopo aver selezionato, possiamo notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” è possibile effettuare un test; come mostrato nell’immagine sopra, abbiamo ottenuto il seguente risultato:

{
  "token": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6jJmBtwR98S2bmmZOjbLh7ogEMDd8NzJdq8DoHOD_LHIUWmdEL3HJS0pP2nmTTSoU_ltxORWA4sVsrWiXDgkARA4wAhJCegD6PftkRuu0KKbqRsJ7KVKukUbLU1ThBu7P3r0fybwpS11yQmF7xpbEZeFzRm_osERk9tQzs1lEYORZSVA5dimbWi42TqUC87mJHCKO0HMiU404LOyER84It7ne51V5YXEHR_o6-ORr2CmBOawdTDTsqWUwT8vyEvzy-ov-pZdl0B0A_U59_uZd7vbIwv937-iXyzkVWbakUXNMdXlHffpFYd7OLTSBhJu6nasV3IhrbnxO8eGIbPDoHIyGpA74D882ALwTnXMgkcmGeGM9YuqCrf7F06cNKY7yKiisZIU-7v3ZnHV3JUkODGpXQ6dwq2fuP5o6kgeUQVdkv4fAZ_Tx_TB_R6gPSgwulr8Q5hH34bs-v1oUl2S9mLhXT9SWvgYizU_4FN2Ou23ETXTAVD_uI9fWaDgKaLOKI1i-xHCF_LKU3wKjyYJfQhFSCSyoeGL4o1j9lZ27cEHL5AlCm_jcCiXhe2_LT_dI-r5ozuyOGv-iDZ_1XTSSnCGdmroXX56XsZAytU52zBAlYVe_aRAojruc9KdkhK4kdeBESBbDLVe3-jNFwYspe0R93SORxXXIqR9CtZrIjI_2U8XjCHFz_euChdU_wkH5BjvONVbUT1DQNuoo0ugJL5kUkFrubHppOKvoZMwIKjjK_ZX1NBeCvQvYm6IpwBWfvM4hjGI7UVXH3iZkrX9PLATIIIkA8PxTeN45k8DulzOhKLSFKK196fRlH83S8UAaM-vjBxf32Vg83C1gWzKB5sYhxqEtZeB7DNpmAkozFfubljURr7YTjtq8Bgnj0PkfzbgKk8FRl-hMUb9BUjNNuSuFC7GZVim6xQnIV9ZPaAcuzJTYcOizFJePbVEXlc9A5Vq2rDh3D7Ld5o5oqc2kK4eCrO_38le6EVTs_fRY2nXy6RMyjjaJN12lOKYwYzGKhm52gTZTrJXqeTAW8o2KfwZ9iek-tr5qxj5b40iY4V2PY6SflMQvmKLAgFhB-yo-o5PEkikQ98T-bE-wG2-3kd5NRMiD132kIhf48zhVJUGeJqdV_3m8ukyqTk26KisM12kN-h9uYefvUCxzd_mBuWlHzH9rFMlJSe8Z6lcZIVcqNF4fcEM-ukNnwMUK5H_SC48U7O_xfOaEqEpAHDC7CCyVwlGCFh0uAT8KSpaNFfxBmMPXeYrGYn83PCgMg1NZA-7PrpeidXmWdBZ2yY8MA__7uCe8clCmINseBTCIbNmAHPlI_zJKqQfhXaDbaELeD62P0Pquu_SBtdEtqPeB9Esn_yjbK3IFvAaGSnFhwhHHK8dpOI7v-rJvTigPu8MMrEUTvug_zog81kCG8HY3xorTj2OdTwdEYpeMJ1VIHSjdTcnepLB0Cffx5wAdk-gf1TGEnEyTiwII4A4vtq8r0LFK4YObOzNmBTl3IoTNheYYKpheTKH3KShMK6hXDKxDRGEUhdsW4TRtVT-dwJDqY_F7J1RwKP-xDuN98VgwQmQuhJteQUALevgI2jAGFCFfSeFbQ8BOT6ekEI0m30zDX0kh83mkE7-u9qKljYifjqbLarMNPP51QRbvAS3mHlP17PMhIKzjuIka4T2Y9XdRwDgRRdEkYiJgDvkcABTknGBMezraon8JNDRhIJMUIKpidWTdhEQ79qAEfZkowdbnTdKeWeayi1OmV_W4aox-aC62H-VIn70McXXB6zRyYlA2NvTUWgNhHWkSO1SW7uflNEyUeWFRLBZV_firMEVfIGirHOAbQqsn83BirDNPHl4xevf4nRu4gWpgOGBrzeUXQeuMWO4ZFsdWxJ2VsT19t0H5DJtxtHYXFtPZ8tFDFY-r8JKFab4S6e5v8PCrfjCWkPmDaRJal_vLFa1V1dF1l0ARu9NLW4mEuT600azFms8cMlvuCTvWI2VWyn4Wk05UvcR8FYO2-ke4E-ZFRl0jSxjlEutzbOwm2ik4eF0Wh2DBliaSr1obHaxkmLJDUIzGQ3wi49Nyn0SSOdz_BGaxuRrrxCZ4ci0e2b5cxLtkv64Njy7IYJURaBuQk99ijdw7rg3pssAa_uJSMQeZe_kLtgEWF73uT4ceSOFPVuxMGLrJRQTBYxAHVKq7kloS5wtphUr2Sp-b4kezKnCV9HNfC5NRk2KqDT-bkJ6cUYN_0yauyZK1_F4BVTk36IOCe1Cqfe3K-wAZBzvrI_Vz8Li1uEWe0b5KOQ"
}

I risultati della richiesta contengono diversi campi, descritti come segue:

token, il risultato della verifica del compito Recaptcha3.

Possiamo vedere che abbiamo ottenuto il risultato della verifica del Recaptcha3, che possiamo utilizzare per simulare una submission POST o GET al sito target, utilizzabile una sola volta, con una validità di 120 secondi, si consiglia di utilizzarlo entro 60 secondi. Di seguito verrà brevemente descritta una modalità per inviare il token generato al sito target: Chiamata del codice Python corrispondente alla verifica del token:

import requests

url = "https://recaptcha-demo.appspot.c/recaptcha-v3-verify.php?action=examples/v3scores&token='{token}'"

r = requests.get(url)
if r.status_code == 200:
    return r.text

Pertanto possiamo ottenere il risultato:

{
  "success": true,
  "hostname": "recaptcha-demo.appspot.com",
  "challenge_ts": "2024-09-14T08:52:26Z",
  "apk_package_name": null,
  "score": 0.9,
  "action": "examples/v3scores",
  "error-codes": []
}

Possiamo vedere che success indica il risultato della verifica, quindi abbiamo superato con successo la verifica del Recaptcha3. Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, ad esempio il codice CURL è il seguente:

curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha3' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
  "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
  "page_action": "examples/v3scores"
}'

Il codice di integrazione Python è il seguente:

import requests

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

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

payload = {
    "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
    "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
    "page_action": "examples/v3scores"
}

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

Modalità asincrona (async)

Per impostazione predefinita, l’API è sincrona e bloccante: una richiesta attenderà fino a quando il token non sarà elaborato prima di restituire. Se stai effettuando un cambio di risolutore multiplo (multi-solver rotation) e desideri “ricevere immediatamente il task_id dopo aver inviato il compito, per poi programmare altri risolutori e tornare più tardi a prendere il risultato”, puoi inviare async: true nel corpo della richiesta. Dopo aver inviato async: true, l’interfaccia restituirà immediatamente un task_id, senza bloccare l’attesa:

curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha3' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
  "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
  "page_action": "examples/v3scores",
  "async": true
}'

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab",
  "status": "processing"
}

Successivamente, utilizza il task_id per interrogare POST /captcha/tasks (si consiglia ogni 3~5 secondi) per ottenere il risultato:

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:

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

Una volta completata l’elaborazione, verrà restituito status: ready e il token:

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6......"
}

Informazioni sulla fatturazione: in modalità asincrona, la creazione di un compito e l’interrogazione “in elaborazione” non comportano costi; si paga solo una volta quando si ottiene un risultato con successo (allo stesso prezzo della modalità sincrona). Pertanto, annullare i compiti non completati durante il cambio non comporterà costi. /captcha/tasks è comune a tutte le interfacce di verifica (token e serie di riconoscimento), è possibile interrogare con lo stesso task_id.

Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:

400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
500 api_error: Errore interno del server, qualcosa è andato storto sul server.

Esempio di risposta di errore

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

Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API di riconoscimento del protocollo Recaptcha3 per consentire agli utenti di non dover riconoscere e selezionare le immagini del captcha Recaptcha3, ma semplicemente di inviare la Website Key per realizzare la decodifica automatica in background e completare la verifica. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

Recaptcha3 Protocol Recognition API Integration Instructions

Processo di richiesta

Utilizzo di base

Metodo rapido:

Modalità asincrona (async)

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Processo di richiesta

​Utilizzo di base

​Metodo rapido:

​Modalità asincrona (async)

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Processo di richiesta

Utilizzo di base

Metodo rapido:

Modalità asincrona (async)

Gestione degli errori

Esempio di risposta di errore

Conclusione