Appeler l’API CAPTCHA depuis Laravel

1. 1.

   Activer le profil de site

   Configurez le nom d’hôte cible dans la console pour que votre espace de travail dispose d’un profil reCAPTCHA actif. Envoyer un nom d’hôte dans une tâche ne crée pas de profil. Consultez la configuration du profil de site.

2. 2.

   Ajouter la configuration du serveur

   Ajoutez l’entrée solvethree de l’exemple au tableau existant dans config/services.php. Définissez SOLVETHREE_API_KEY, CAPTCHA_SITE et SOLVETHREE_PROXY dans l’environnement de votre serveur. Gardez ces valeurs hors du code du navigateur ; CAPTCHA_SITE est le nom d’hôte, pas une URL complète.

3. 3.

   Utiliser l’action correspondant à la cible

   L’exemple envoie login. Remplacez cette valeur par l’action utilisée par la requête cible prévue. Il fournit un seul proxy ; n’envoyez pas également proxyCandidates.

<?php
// app/Services/CaptchaApi.php — configure services.solvethree in config/services.php.
namespace App\Services;

use Illuminate\Support\Facades\Http;
use InvalidArgumentException;

final class CaptchaApi
{
    private function client()
    {
        return Http::baseUrl('https://api.solvethree.com/v1')
            ->withToken(config('services.solvethree.key'))
            ->acceptJson()->asJson()->connectTimeout(10)->timeout(25);
    }

    public function create(string $requestId): array
    {
        if (!preg_match('/^[A-Za-z0-9_-]{1,64}$/', $requestId)) {
            throw new InvalidArgumentException('Invalid logical request ID');
        }
        // The caller keeps this requestId; do not generate another on a timeout.
        return $this->client()->post('/tasks?waitMs=0', [
            'site' => config('services.solvethree.site'),
            'action' => 'login',
            'proxy' => config('services.solvethree.proxy'),
            'requestId' => $requestId,
        ])->throw()->json();
    }

    public function retrieve(string $taskId): array
    {
        if (!preg_match('/^[A-Za-z0-9_-]{1,128}$/', $taskId)) {
            throw new InvalidArgumentException('Invalid task ID');
        }
        return $this->client()->get('/tasks/'.rawurlencode($taskId), ['waitMs' => 15000])
            ->throw()->json();
    }
}
// config/services.php entry:
// 'solvethree' => ['key' => env('SOLVETHREE_API_KEY'),
//   'site' => env('CAPTCHA_SITE'), 'proxy' => env('SOLVETHREE_PROXY')],
// Invoke from your authenticated controller/job. Poll retrieve only while pending
// or solving; ready contains the solution, failed is terminal. Never use retry()
// on create without preserving both this ID and the exact original inputs.

withToken envoie la clé de l’espace de travail pour l’authentification Bearer. Le corps du POST est plat : site, action, proxy et requestId sont des champs de premier niveau. N’ajoutez pas de champ type ou url pour reCAPTCHA. Omettre recaptchaType sélectionne la valeur par défaut documentée enterprise-v3.

Les deux méthodes appellent throw() avant json(). Le client HTTP de Laravel ne lève pas d’exception par défaut pour les réponses HTTP non réussies ; cela empêche donc l’appelant de traiter le contenu d’une erreur HTTP comme une réponse de tâche réussie. Le service définit des délais de connexion et de requête et ne réessaie délibérément pas les POST automatiquement.

1. 1.

   Créer une seule fois pour chaque résolution logique

   Dans votre contrôleur ou votre job authentifié, conservez un requestId généré par l’appelant avant d’appeler create. Il doit contenir 1–64 lettres ASCII, chiffres, traits de soulignement ou traits d’union. Enregistrez séparément l’ID de tâche renvoyé : l’ID de requête logique sert à récupérer une création ; l’ID de tâche est celui qu’accepte retrieve.

2. 2.

   Récupérer la tâche existante

   Appelez retrieve avec l’ID de tâche enregistré. Si le statut est pending ou solving, prévoyez une récupération ultérieure plutôt qu’une boucle intensive dans le contrôleur. Fixez un délai d’attente global pour l’appelant ; le délai HTTP du service limite chaque requête, pas la durée de vie de la résolution. Atteindre cette limite ne justifie pas la création d’une autre tâche.

3. 3.

   Traiter le résultat terminal

   Pour failed, arrêtez les récupérations et examinez errorCode et error ; les résolutions échouées sont remboursées. Pour ready, utilisez le jeton de solution renvoyé. Soumettez-le avec l’identité userAgent et secChUa renvoyée et le même proxy que celui utilisé pour la résolution. Une solution prête doit encore être acceptée par la cible.

Distinguez les erreurs HTTP des échecs de tâche. Une réponse HTTP non réussie est traitée par throw() ; une réponse réussie contenant failed nécessite un traitement au niveau de la tâche. Ne réessayez pas avec des paramètres invalides inchangés et ne supposez pas que tout échec signifie un crédit insuffisant. Consultez la gestion des erreurs de l’API.

Un délai de connexion dépassé ne vous dit pas si solvethree a créé la tâche. Si vous avez déjà son ID de tâche, récupérez-la. Sinon, répétez la création avec le même requestId et exactement les mêmes paramètres de tâche pour récupérer la tâche existante.