> ## 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. # Recaptcha3 Protocol Recognition API Integration Instructions > Recaptcha verification code recognition service API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [API di riconoscimento del protocollo Recaptcha3 →](https://platform.acedata.cloud/documents/captcha-token-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: ```json theme={null} { "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: ```python theme={null} 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: ```json theme={null} { "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: ```shell theme={null} 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: ```python theme={null} 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: ```shell theme={null} 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 }' ``` ```json theme={null} { "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: ```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" } ``` Una volta completata l'elaborazione, verrà restituito `status: ready` e il token: ```json theme={null} { "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 ```json theme={null} { "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.