Débogage des appels API CAPTCHA avec Charles Proxy

Lorsque votre intégration CAPTCHA renvoie des erreurs inattendues, l'inspection du trafic HTTP brut révèle ce qui est réellement envoyé et reçu. Charles Proxy se situe entre votre code et CaptchaAI, vous permettant de voir chaque demande, réponse et détail du timing.

Configuration

1. Installez le proxy Charles

Télécharger depuischarlesproxy.com. Disponible sur Windows, macOS et Linux.

2. Activer le proxy SSL

CaptchaAI utilise HTTPS. Pour inspecter le trafic chiffré :

1. Proxy → Paramètres de proxy SSL → Ajouter
2. Hôte : ocr.captchaai.com, Port : 443
3. Aide → Proxyage SSL → Installer le certificat racine Charles
4. Faites confiance au certificat dans le magasin de certificats de votre système d'exploitation

3. Configurez votre code pour utiliser Charles

Charles fonctionne sur localhost:8888 par défaut.

Python :

import requests

proxies = {
    "http": "http://localhost:8888",
    "https": "http://localhost:8888",
}

# Disable SSL verification for Charles (development only)
resp = requests.post(
    "https://ocr.captchaai.com/in.php",
    data={"key": "YOUR_API_KEY", "method": "userrecaptcha", "json": "1"},
    proxies=proxies,
    verify=False,
)

Node.js :

const axios = require('axios');
const HttpsProxyAgent = require('https-proxy-agent');

const agent = new HttpsProxyAgent('http://localhost:8888');

const resp = await axios.post('https://ocr.captchaai.com/in.php', null, {
  params: { key: 'YOUR_API_KEY', method: 'userrecaptcha', json: 1 },
  httpsAgent: agent,
});

Que faut-il inspecter

Soumettre la demande (POST /in.php)

Dans Charles, cliquez sur la demande à /in.php. Vérifiez :

Problèmes courants visibles chez Charles :

• Paramètre method manquant → ERROR_BAD_PARAMETERS
• Mauvais type de contenu → Paramètres non analysés
• googlekey vide -> ERROR_WRONG_GOOGLEKEY
• Corps JSON mal formé → Utiliser les données du formulaire, pas le corps JSON

Demande de sondage (GET /res.php)

Vérifiez les demandes de sondage :

• Params : key, action=get, id=TASK_ID
• Réponse : CAPCHA_NOT_READY (continuer à interroger) ou {"status":1,"request":"TOKEN"}
• Timing : chaque sondage suivi de votre intervalle de sommeil

Débogage des problèmes courants

Problème : ERROR_WRONG_GOOGLEKEY

Dans Charles, regardez le corps de la demande de soumission. Recherchez le champ googlekey :

# What Charles shows:
key=YOUR_API_KEY&method=userrecaptcha&googlekey=&pageurl=https://example.com&json=1
                                      ^^^^^^^^ empty!

Correctif : l’extraction de la clé de site a échoué en amont. Vérifiez votre code d'extraction.

Problème : Jeton rejeté par le site cible

Comparez ce que CaptchaAI a renvoyé à ce que vous injectez :

1. Dans Charles, retrouvez la réponse /res.php avec status: 1
2. Copiez le jeton complet du champ request
3. Rechercher la requête suivante sur le site cible
4. Vérifiez que le jeton est dans le corps du formulaire comme g-recaptcha-response

Problème : expiration du délai de demande

Utilisez la vue Charles Séquence pour voir le timing :

POST /in.php     → 234ms ✓
GET  /res.php    → 189ms (CAPCHA_NOT_READY)
GET  /res.php    → 201ms (CAPCHA_NOT_READY)
GET  /res.php    → 195ms (CAPCHA_NOT_READY)
... 23 more ...
GET  /res.php    → 188ms (CAPCHA_NOT_READY)  ← never resolves

Si le problème ne se résout jamais : vérifiez si la clé du site et l'URL de la page sont correctes.

Fonctionnalités Charles pour le débogage CAPTCHA

Répéter la demande

Cliquez avec le bouton droit sur n'importe quelle demande → Répéter pour la renvoyer. Utile pour tester les demandes de sondage sans réexécuter l'intégralité de votre script.

Points d'arrêt

Définissez un point d'arrêt sur /in.php pour inspecter et modifier la requête avant son envoi :

1. Proxy → Paramètres de point d'arrêt → Ajouter
2. Hôte : ocr.captchaai.com, Chemin : /in.php
3. Cochez Demande
4. Désormais, votre code est mis en pause avant l'envoi : vous pouvez modifier les paramètres

Carte Locale

Remplacez les réponses de l'API par des fichiers locaux à des fins de test :

1. Outils → Carte locale → Ajouter
2. Mapper https://ocr.captchaai.com/res.php à un fichier JSON local
3. Créez mock_response.json :

{"status": 1, "request": "mock_token_for_testing"}

Cela vous permet de tester votre code d'injection de token sans utiliser de crédits API.

Accélérateur

Simulez des connexions lentes :

1. Proxy → Paramètres de limitation → Activer
2. Réglez le préréglage sur les vitesses 3G ou EDGE-level
3. Testez si votre code gère correctement les réponses lentes et les délais d'attente

Alternatives à Charles

configuration rapide de mitmproxy

# Install
pip install mitmproxy

# Run
mitmproxy --listen-port 8080

# Configure Python
proxies = {"https": "http://localhost:8080"}

Dépannage

FAQ

Dois-je utiliser Charles en production ?

Non. Charles est un outil de développement et de débogage. Utilisez la journalisation et la surveillance structurées pour l’observabilité de la production.

Le routage via Charles affecte-t-il la résolution de CAPTCHA ?

Non. CaptchaAI ne considère pas Charles comme un mandataire : vos demandes transitent de manière transparente.

Déboguez et optimisez votre intégration CaptchaAI

Obtenez votre clé API surcaptchaai.com.

Guides associés

• Journalisation structurée pour les opérations CAPTCHA
• Référence des codes d'erreur CaptchaAI
• Collection Postman pour les tests API CaptchaAI