Résolution de CAPTCHAs depuis un Encore.ts Resource

Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni la neutralisation de protections, ni l'évasion de systèmes anti-bot.

Depuis une ressource Encore.ts, la résolution de CAPTCHA se réduit à trois responsabilités : appeler l'API CaptchaAI en HTTPS, récupérer un token, puis l'injecter dans la session qui a déclenché le défi. Tout le reste — secrets, journalisation, nouvelles tentatives — est ce qui distingue une démo qui fonctionne une fois d'une intégration qui tient en production. Voici comment les câbler proprement.

Pourquoi structurer l'intégration dès le départ

Encore.ts pousse vers des services typés et des ressources déclarées explicitement : isolez l'appel au solveur dans un composant interne testable. Le piège classique consiste à glisser un simple fetch au milieu d'un handler. Cela passe dans un notebook, puis casse dès que le job tourne sans surveillance en CI, dans un cron ou derrière une file d'attente interne. Ce qu'il vous faut est prévisible : une latence stable, des modes d'échec propres et un code relu en cinq minutes. CaptchaAI répond à ce besoin avec une API unique pour toutes les familles prises en charge et une facturation au thread.

Architecture cible depuis une ressource Encore.ts

Votre ressource interne appelle CaptchaAI en HTTPS pour obtenir un token, puis l'injecte dans votre formulaire ou votre route d'API. Centralisez cet appel dans un service Encore.ts dédié plutôt que de le disperser : vous regroupez ainsi journalisation, délais d'expiration et politique de retry. Tracez chaque étape — soumission, interrogation, injection — pour repérer une régression au moindre changement de version ou de famille de CAPTCHA.

Le contrat submit puis polling

Le déroulé reste identique quel que soit le type de CAPTCHA, ce qui rend le code portable :

1. Capturez uniquement les paramètres attendus par la famille visée (sitekey, URL de la page, action, proxy éventuel). En stocker davantage crée de fausses pistes de débogage.
2. Soumettez la tâche à l'endpoint 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 canal de supervision.
3. Interrogez le résultat sur 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. Injectez le token dans la session qui a déclenché le défi — même contexte, même client HTTP, même cookie jar. Une session différente est la première cause de rejet après résolution.
5. Mesurez séparément la réussite du solveur et celle du workflow : ce sont deux métriques distinctes.

Exemple de code

Voici un appel HTTP côté serveur, encapsulé dans une fonction de votre propre service :

import fetch from 'node-fetch';

const API_KEY = process.env.CAPTCHAAI_KEY;

export async function createTurnstileTask(siteKey, pageUrl) {
  const res = await fetch('https://api.captchaai.com/createTask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientKey: API_KEY,
      task: {
        type: 'TurnstileTaskProxyless',
        websiteURL: pageUrl,
        websiteKey: siteKey,
      },
    }),
  });
  const data = await res.json();
  return data.taskId;
}

Gestion des secrets et configuration

La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de CI, jamais dans le code source. Encore.ts expose ses propres secrets typés : déclarez la clé comme secret et laissez le déploiement la monter en variable d'environnement au runtime.

Que vous hébergiez vos workers chez OVHcloud, Scaleway ou dans une région AWS européenne comme eu-west-3 (Paris) pour réduire la latence, la règle ne change pas : la clé n'apparaît ni dans un dépôt, ni dans un log. La facturation étant en dollars US, le plan BASIC ($15/mois, 5 threads) suffit pour démarrer une intégration mono-worker.

Observabilité et journalisation

Instrumentez chaque appel CAPTCHA pour disposer de métriques 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 (développement, préproduction, production) et corrélez les identifiants à votre traçage distribué (OpenTelemetry, par exemple) : vous rejouez alors un scénario complet depuis un identifiant unique, ce qui accélère nettement le diagnostic. Si vos journaux touchent des données personnelles, minimisez ce que vous conservez et vérifiez vos obligations RGPD.

Points de contrôle avant la fusion

Une checklist de revue de code avant de fusionner l'intégration.

Dépannage

FAQ

Comment déclarer la clé CaptchaAI comme secret dans Encore.ts ?

Utilisez le mécanisme de secrets typés d'Encore.ts et référencez la valeur au runtime, jamais en dur. En local, alimentez-la depuis votre coffre ou un secret de CI ; en production, laissez la plateforme l'injecter en variable d'environnement.

Faut-il vraiment injecter le token dans la même session que le défi ?

Oui. Le token est lié au contexte qui a chargé le CAPTCHA : mêmes cookies, même client HTTP. Injecté ailleurs, il est très souvent refusé côté serveur. Conservez la résolution et la soumission dans une seule et même session pour éviter ce rejet.

Ce guide couvre-t-il l'automatisation de sites tiers ?

Non. Tous les exemples portent sur vos propres applications ou des environnements de test autorisés par écrit. Si votre projet implique une source externe, validez d'abord les conditions d'utilisation et la base juridique avant toute automatisation.

Que faire en cas d'erreur transitoire de l'API ?

Appliquez un backoff exponentiel borné (trois tentatives, doublement du délai, plafond à 30 s) et journalisez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez la configuration réseau (DNS, certificats) et les quotas de votre clé.

Guides connexes

• le démarrage rapide CaptchaAI
• la QA CAPTCHA en environnements autorisés
• tester l'endpoint API sur vos formulaires
• l'intégration CAPTCHA en CI
• résoudre reCAPTCHA v2 via l'API

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