Checklist avant chaque appel à l'API CaptchaAI

Avant chaque appel à l'API CaptchaAI, cinq points décident si votre intégration tient en production ou casse à la première exécution non surveillée : les entrées exactes de la tâche, la cadence d'interrogation du résultat, la continuité de session, le budget de retry et le suivi de l'acceptation en aval. Gardez cette checklist en revue de code : un flux qui « marche » dans un notebook n'a rien prouvé tant qu'il ne tient pas en CI, en tâche planifiée et derrière une file d'attente interne.

Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni la résolution de protections que vous ne contrôlez pas.

Ce que vérifie cette checklist

Chaque ligne ci-dessous correspond à une panne réelle rencontrée en montée de version : une entrée mal capturée, un polling trop agressif, un token appliqué dans la mauvaise session. L'objectif est de rendre le flux assez prévisible pour l'automatisation, la QA et la production — pas de le faire fonctionner une seule fois.

Les cinq contrôles avant l'appel

L'ordre compte : chaque étape prépare la suivante.

1. Capturez exactement les entrées attendues. Ne conservez que les paramètres dont la famille de CAPTCHA a besoin (sitekey, URL de la page, action, proxy éventuel). Stocker davantage crée de fausses pistes de débogage.
2. Envoyez la tâche à https://ocr.captchaai.com/in.php avec json=1. Traitez tout statut différent de 1 comme une erreur : journalisez la réponse complète et remontez-la vers votre supervision.
3. Interrogez le résultat sur https://ocr.captchaai.com/res.php. Attendez 15 s avant la première interrogation, puis toutes les 5 s, avec un plafond strict de 120 s par tâche.
4. Appliquez le token dans la même session que celle qui a déclenché le défi : même contexte de navigateur, même client HTTP, même cookie jar. Une session qui ne correspond pas est la première cause de rejet après résolution.
5. Suivez la latence, les retries et l'acceptation en aval. La réussite du solveur et celle du workflow sont deux métriques distinctes : mesurez les deux.

Gestion de la clé API

La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager) ou dans un secret de CI, jamais dans le code source ; le déploiement la monte en variable d'environnement au runtime. Que vous hébergiez vos workers chez OVHcloud, Scaleway ou sur une région AWS européenne comme eu-west-3 (Paris), prévoyez une rotation de clé sans coupure et une alerte de solde — pour ne pas découvrir un ERROR_ZERO_BALANCE en pleine campagne.

Exemple : lecture du solde

Exemple côté client, tiré de votre propre suite de tests, pour vérifier l'authentification et le solde avant de lancer un lot :

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']

def get_balance() -> float:
    resp = requests.post(
        'https://api.captchaai.com/getBalance',
        json={'clientKey': API_KEY},
        timeout=15,
    )
    resp.raise_for_status()
    return float(resp.json().get('balance', 0))

Le déroulé reste identique en Python, Node.js, Go ou Java : même logique d'envoi puis d'interrogation via HTTP.

Observabilité et KPI

Ce que vous ne mesurez pas, vous ne pouvez pas le défendre. Instrumentez chaque appel CAPTCHA pour obtenir des signaux exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry) pour rejouer un scénario à partir d'un identifiant unique. Côté conformité, minimisez les données personnelles journalisées et vérifiez vos obligations RGPD.

Les valeurs ci-dessous sont des cibles internes indicatives ; les résultats varient selon l'environnement, le volume et le moment de la journée.

Liste de contrôle avant merge

• Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI est stockée dans un secret de CI ou un coffre, jamais dans le code source.
• Les entrées de la tâche sont validées contre le HTML réel de la page.
• Les durées d'appel et les codes retour sont tracés pour chaque exécution.
• Une stratégie de retry idempotent, avec backoff exponentiel borné, est en place.
• Les tableaux de bord distinguent la réussite du solveur de l'acceptation en aval.

Dépannage

Les erreurs ci-dessous couvrent la majorité des tickets de support ; chaque ligne se corrige sans quitter votre éditeur.

FAQ

À quel moment dérouler cette checklist ?

Avant chaque fusion d'une intégration qui touche un appel à l'API, et comme grille de revue de code. Le coût est de quelques minutes ; il évite les régressions qui n'apparaissent qu'en exécution non surveillée, en CI ou en tâche planifiée.

Comment dimensionner le budget de retry ?

Trois tentatives, un backoff exponentiel borné (doublement du délai à chaque essai, plafond à 30 s), et une journalisation de chaque échec terminal avec son identifiant de tâche. Les retries infinis masquent les vrais défauts et consomment le solde.

Faut-il suivre séparément la résolution et l'acceptation ?

Oui. Une tâche résolue n'est pas un workflow réussi : le token peut être correct et pourtant refusé en aval. Suivez le code HTTP en aval indépendamment de la réussite du solveur et alertez sur l'écart entre les deux.

Les coûts augmentent-ils avec le volume ?

La facturation CaptchaAI est basée sur les threads — BASIC à $15/mois, 5 threads, avec résolutions illimitées par thread — et non par résolution. Les vrais postes de coût sont les boucles de mauvais paramètres et les tempêtes de retry, couverts par la liste de contrôle ci-dessus.

Guides connexes

• Le guide de démarrage rapide CaptchaAI
• La QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• L'intégration des CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.