Client REST Insomnia pour le développement de l'API CaptchaAI

Avant d'écrire la moindre ligne de code d'intégration, vous pouvez rejouer tout le cycle de l'API CaptchaAI dans Insomnia : soumettre une tâche, interroger le résultat, vérifier le solde et reproduire les erreurs à la main. C'est le moyen le plus rapide de lever les doutes sur vos paramètres, votre clé et vos endpoints avant de les figer dans un script. Ce guide monte un espace de travail Insomnia réutilisable.

Préparer votre espace de travail Insomnia

Créer l'espace de travail CaptchaAI

1. Ouvrez Insomnia
2. Cliquez sur Create → Design Document ou Request Collection
3. Nommez-le « API CaptchaAI »

Centraliser les valeurs dans des environnements

Ne codez jamais l'URL de base ni la clé en dur dans chaque requête : le système d'environnements d'Insomnia évite les copier-coller et les fuites accidentelles.

1. Ouvrez la liste déroulante des environnements (en haut à gauche)
2. Sélectionnez Manage Environments
3. Créez un Base Environment avec les valeurs partagées :

{
  "base_url": "https://ocr.captchaai.com",
  "api_key": "YOUR_API_KEY"
}

1. Ajoutez des Sub Environments pour vos différents contextes :

Développement :

{
  "test_sitekey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
  "test_pageurl": "https://www.google.com/recaptcha/api2/demo"
}

Production :

{
  "test_sitekey": "YOUR_PRODUCTION_SITEKEY",
  "test_pageurl": "https://your-target-site.com"
}

Vous référencez ensuite ces variables avec {{ base_url }} et {{ api_key }} dans chaque requête. Basculer du développement vers la production revient alors à changer de sous-environnement, sans toucher aux requêtes.

Les requêtes essentielles de l'API

1. Vérifier le solde du compte

C'est le premier test à réussir : il confirme que votre clé et votre URL de base sont bons.

Paramètres de requête :

Réponse attendue :

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

2. Soumettre une tâche reCAPTCHA v2

Paramètres du formulaire :

Réponse attendue :

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

La valeur request renvoyée ici est l'ID de tâche : vous en aurez besoin à l'étape suivante.

3. Interroger le résultat

Paramètres de requête :

Réponses possibles :

Traitement en cours :

{
  "status": 0,
  "request": "CAPCHA_NOT_READY"
}

Résolu :

{
  "status": 1,
  "request": "03AGdBq24PBCb..."
}

Tant que la réponse est CAPCHA_NOT_READY, patientez quelques secondes et renvoyez la requête. Le token complet arrive dans le champ request.

4. Soumettre une tâche Cloudflare Turnstile

Le principe est identique à reCAPTCHA v2 ; seuls la method et le nom de la clé de site changent.

5. Soumettre un CAPTCHA image

Valider les réponses à l'œil

Insomnia n'embarque pas d'assertions de test automatiques, mais quelques repères visuels suffisent pour juger une réponse d'un coup d'œil.

Repères de réussite

Erreurs fréquentes et correctifs

Dépannage

Organiser les requêtes en dossiers

Sur un espace de travail qui couvre plusieurs types de CAPTCHA, une arborescence de dossiers vous fait gagner du temps :

CaptchaAI API/
├── Account/
│   └── Check Balance
├── reCAPTCHA/
│   ├── Submit v2 Task
│   ├── Submit v3 Task
│   ├── Submit Enterprise Task
│   └── Poll Result
├── Cloudflare/
│   ├── Submit Turnstile Task
│   └── Poll Result
├── Image/
│   ├── Submit Base64 Image
│   └── Poll Result
└── hCaptcha/
    ├── Submit hCaptcha Task
    └── Poll Result

Couvrir plusieurs types de CAPTCHA

Un modèle de requête par type

Le corps de la requête ne change que sur deux ou trois paramètres selon le type de défi. Ce tableau récapitule ce qui varie :

À noter : le dossier hCaptcha de l'arborescence ci-dessus n'est qu'un exemple d'organisation. CaptchaAI ne prend pas encore en charge hCaptcha ni FunCaptcha (Arkose Labs) ; inutile donc d'y consacrer une requête de soumission. Côté types pris en charge, vous couvrez reCAPTCHA v2 et v3, reCAPTCHA Enterprise, Cloudflare Turnstile et Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille.

Insomnia ou Postman pour CaptchaAI

Les deux clients font le travail. Insomnia mise sur une interface épurée et un usage hors ligne complet ; Postman offre plus d'outils de test au prix d'une prise en main plus lourde.

Partager la collection avec votre équipe

Une collection Insomnia bien rangée devient vite un actif d'équipe, à condition de partager la structure sans partager les secrets. Sous l'angle RGPD comme sous l'angle sécurité, la règle est la même : minimisez ce que vous exposez et ne laissez jamais une vraie clé sortir de son environnement privé.

Exporter la collection

1. Faites un clic droit sur l'espace de travail
2. Sélectionnez Export Data
3. Choisissez le format : Insomnia v4 (JSON) ou HAR
4. Retirez les clés API du fichier exporté avant de le transmettre

Synchroniser via Git

Insomnia s'intègre à Git :

1. Ouvrez les paramètres de l'espace de travail
2. Configurez le dépôt Git
3. Validez et poussez votre collection de requêtes
4. Chaque membre clone le dépôt et renseigne ses propres variables d'environnement, avec sa propre clé API

Note de sécurité : ne validez jamais un fichier d'environnement contenant de vraies clés API dans un dépôt partagé. Utilisez les environnements privés d'Insomnia ou ajoutez le fichier au .gitignore.

Enchaîner soumission et interrogation

Recopier l'ID de tâche à la main entre deux requêtes est fastidieux et source d'erreurs. Insomnia sait extraire une valeur d'une réponse précédente et l'injecter automatiquement dans la suivante : vous reproduisez ainsi le workflow soumission → interrogation en deux clics.

Étape 1 : repérer la réponse de soumission

Après avoir envoyé la requête de soumission, gardez-la de côté : c'est elle qui contient l'ID de tâche que la requête d'interrogation devra réutiliser.

Étape 2 : injecter l'ID de tâche dans l'interrogation

Dans le paramètre id de la requête d'interrogation :

1. Appuyez sur Ctrl+Space dans le champ de valeur
2. Sélectionnez Response → Body Attribute
3. Configurez : - Request : la requête de soumission - Filter : $.request (le JSONPath qui extrait l'ID de tâche) - Trigger Behavior : « When Expired » ou « Always »

Désormais, chaque envoi de la requête d'interrogation reprend automatiquement l'ID de la soumission la plus récente.

FAQ

Insomnia ou Postman pour tester l'API CaptchaAI ?

Les deux conviennent. Choisissez Insomnia pour une interface légère, un usage hors ligne complet et un enchaînement de requêtes simple ; préférez Postman si vous voulez des scripts de test intégrés et des espaces cloud partagés. Pour valider rapidement les endpoints CaptchaAI, Insomnia suffit largement.

Comment partager une collection Insomnia sans exposer ma clé API ?

Gardez la clé dans un environnement privé, jamais dans les requêtes. À l'export, retirez les clés du fichier ; en Git sync, ajoutez le fichier d'environnement au .gitignore pour que chacun renseigne la sienne. La structure des requêtes se partage, les secrets restent locaux.

Puis-je enchaîner automatiquement la soumission et l'interrogation dans Insomnia ?

Oui. La référence de réponse (Response → Body Attribute avec le filtre $.request) injecte l'ID de tâche de la soumission directement dans le paramètre id de l'interrogation. Vous relancez l'interrogation sans jamais recopier l'identifiant à la main.

Insomnia peut-il remplacer mon code d'intégration en production ?

Non. Insomnia est un outil interactif de mise au point : idéal pour tester, déboguer et documenter vos requêtes. Pour l'interrogation répétée des résultats ou une exécution planifiée, exportez vos requêtes en commandes cURL et faites-les tourner dans un pipeline CI/CD.

Articles connexes

• Sécuriser vos clés API par liste blanche d'IP
• La rotation régulière de vos clés API CaptchaAI
• Cartographier les endpoints de l'API face aux concurrents

Prochaines étapes

Montez votre espace de travail Insomnia pour tester l'API CaptchaAI avant de coder votre intégration : récupérez votre clé API pour commencer.

Guides associés :

• Inspecter le trafic de l'API avec Fiddler
• L'outil CLI CaptchaAI pour résoudre en ligne de commande
• La référence des codes d'erreur CaptchaAI