Appeler le solveur depuis un Route Handler Next.js

• Utilisez Node.js 22+ et le SDK JavaScript officiel. Suivez la procédure d’installation par URL de paquet dans la documentation ; ne supposez pas qu’un paquet est disponible sur le registre npm.
• Définissez SOLVETHREE_API_KEY, CAPTCHA_SITE, SOLVETHREE_PROXY et INTEGRATION_KEY dans l’environnement du serveur. Ne donnez le préfixe NEXT_PUBLIC_ à aucun des deux secrets.
• Activez un profil pour le nom d’hôte cible dans votre espace de travail avant d’appeler la route. Définir CAPTCHA_SITE ne crée pas de profil ; consultez la configuration du profil de site.
• Remplacez l’action login de l’exemple par celle requise pour votre intégration. La requête utilise un seul proxy et reCAPTCHA Enterprise v3 par défaut ; elle n’a pas besoin des champs type ou url.

Placez l’exemple dans app/api/captcha/route.js. Il exporte des gestionnaires HTTP App Router et sélectionne explicitement l’environnement d’exécution Node.js pour le SDK. Conservez-le comme route serveur exécutée à chaque requête, et non comme ressource générée statiquement.

import { Solvethree, SolvethreeError } from '@solvethree/sdk';
export const runtime = 'nodejs';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
function authorized(request) {
  const key = process.env.INTEGRATION_KEY;
  return Boolean(key) && request.headers.get('x-integration-key') === key;
}
function failure(error) {
  return error instanceof SolvethreeError
    ? Response.json({ requestId: error.requestId, taskId: error.taskId }, { status: 502 })
    : Response.json({ error: 'Invalid task input or ID' }, { status: 400 });
}
export async function POST(request) {
  if (!authorized(request)) return new Response('Unauthorized', { status: 401 });
  try {
    return Response.json(await client.createTask({
      site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
      requestId: request.headers.get('x-request-id') ?? undefined,
    }, { waitMs: 0, signal: AbortSignal.timeout(20000) }));
  } catch (error) { return failure(error); }
}
export async function GET(request) {
  if (!authorized(request)) return new Response('Unauthorized', { status: 401 });
  const id = new URL(request.url).searchParams.get('id');
  if (!id) return Response.json({ error: 'Provide id' }, { status: 400 });
  try {
    return Response.json(await client.getTask(id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
  } catch (error) { return failure(error); }
}

POST appelle createTask avec waitMs: 0 et renvoie donc la réponse de la tâche sans attendre de solution. Enregistrez l’ID de tâche renvoyé. GET exige cet ID existant et appelle getTask ; il ne crée jamais de tâche.

GET demande une attente allant jusqu’à 15 secondes, avec une annulation distincte de la requête après 25 secondes. POST annule la requête après 20 secondes. Ces limites s’appliquent à chaque requête, pas à la durée de vie de la tâche.

Pour un accès depuis le navigateur, utilisez l’authentification réelle de votre application côté serveur plutôt que de distribuer INTEGRATION_KEY. L’authentification seule ne suffit pas : accepter n’importe quel ID de tâche fourni par un utilisateur authentifié lui permettrait toujours de demander le résultat d’un autre utilisateur.

1. 1.

   Associer la création à l’appelant

   Après qu’un POST authentifié a créé une tâche, enregistrez son ID en l’associant à l’utilisateur ou au tenant authentifié avant de le renvoyer. Associez également le requestId logique à ce propriétaire, afin de ne pas perdre l’enregistrement de propriété lors de la récupération.

2. 2.

   Vérifier la propriété avant la récupération

   Lors d’un GET, authentifiez l’appelant et vérifiez l’ID fourni dans cet enregistrement de propriété avant d’appeler getTask. Rejetez les ID qui n’appartiennent pas à l’appelant et ne renvoyez les résultats qu’une fois cette vérification réussie.

Gardez le site, l’action et le proxy sous le contrôle du serveur, sauf si votre application autorise explicitement les appelants à les choisir. Les valeurs d’environnement fixes de cet exemple empêchent le client de modifier ces paramètres.

1. 1.

   Continuer à interroger les tâches non terminées

   Pour pending ou solving, récupérez à nouveau le même ID, dans la limite du délai global de votre application. La fin d’une attente GET ne justifie pas la création d’une autre tâche.

2. 2.

   S’arrêter sur ready ou failed

   Seul ready contient une solution utilisable. Pour failed, arrêtez les interrogations et examinez errorCode et error ; les résolutions échouées sont remboursées. Traitez les réponses HTTP non réussies avant d’interpréter une réponse comme une tâche. Le gestionnaire catch de la route ne remplace pas la vérification du statut de tâche renvoyé.

3. 3.

   Récupérer la création après un délai de connexion dépassé

   Choisissez et conservez un x-request-id avant le POST. Si vous avez reçu un ID de tâche, récupérez cette tâche. Si la réponse de création a été perdue, répétez le POST avec le même ID de requête et les mêmes paramètres de tâche pour récupérer la tâche existante. Les ID de requête acceptent 1–64 lettres ASCII, chiffres, traits de soulignement ou traits d’union ; réutiliser un ID avec des paramètres différents provoque un conflit.

Une tâche ready signifie que solvethree a généré une solution, pas que la cible l’a acceptée. Le SDK ne la soumet pas à votre place. Lors de la soumission, utilisez les valeurs userAgent et secChUa renvoyées avec le proxy ayant permis la résolution — le proxy configuré dans cet exemple à proxy unique. Ne passez pas à une identité de navigateur ou à une IP sans rapport.

En cas d’erreur de requête ou d’échec terminal, consultez la référence des erreurs de l’API avant de payer une nouvelle résolution. Réessayer avec des paramètres invalides inchangés ne les corrigera pas.