Référence de l'API

CaptchaLa fournit une API RESTful pour toutes les intégrations côté serveur.

URL de base

https://apiv1.captcha.la

Authentification

Toutes les requêtes API exigent des en-têtes d'authentification :

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret est réservé au côté serveur. Ne l'exposez jamais aux navigateurs, applications mobiles ou dépôts publics.

API de validation côté serveur

💡 Utilisez un SDK serveur pour éviter le code répétitif. Il encapsule l'endpoint, gère les tentatives et expose des erreurs typées :

• PHP — Captcha-La/captchala-php (中文)
• Go — go get github.com/Captcha-La/captchala-go · README

Une fois que l'utilisateur a passé le CAPTCHA côté frontend, votre serveur doit valider le token renvoyé par le SDK. Voici les endpoints de validation côté serveur.

Validation de token côté serveur

Validez le pass_token issu du SDK frontend (préfixe pt_). Nécessite les en-têtes X-App-Key et X-App-Secret.

POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

TIP

Vérifiez que data.valid === true et que data.action correspond à la scène attendue (rejetez si un token issu d'un flux pay est présenté sur /login). Les tokens sont à usage unique.

Token de challenge émis par le serveur

Émettez un server_token à durée de vie courte depuis votre backend. Le navigateur transmet ensuite ce token lors de l'initialisation d'un challenge, prouvant que la requête provient de votre serveur de confiance.

Émettre un server token

Appelez cet endpoint uniquement depuis votre propre serveur. Nécessite X-App-Key + X-App-Secret. La réponse contient un server_token (préfixe sct_) que le frontend transmet à l'initialisation du challenge.

POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4

{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}

Paramètres du corps (form-urlencoded)

Champ	Description
action	Scène métier, par ex. login, register, pay. Doit correspondre à l'action utilisée lors de l'initialisation du challenge.
ttl	Durée de vie du token en secondes. Valeur par défaut 300, maximum 900.
max_uses	Nombre maximal d'utilisations autorisées du token. Valeur par défaut 10.
bind_ip	Lie le token à une IP cliente. L'initialisation depuis une autre IP est rejetée.
bind_device_id	Lie le token à un identifiant d'appareil spécifique.
bind_fingerprint	Lie le token à une empreinte de navigateur spécifique.

Initialiser un challenge

Appelé par le SDK pour démarrer un challenge CAPTCHA. Accepte un server_token optionnel émis par /v1/server/challenge/issue.

Champ	Description
app_key	Votre App Key publique.
action	Scène métier. Doit correspondre à l'action utilisée lors de l'émission du server_token.
server_token	Optionnel ; requis lorsque l'application a server_token_required = true.

INFO

Si server_token_required est activé pour cette application dans le tableau de bord, l'initialisation du challenge rejettera toute requête ne portant pas de server_token valide.

Codes d'erreur

Code	Description
invalid_app_key	App Key invalide
invalid_app_secret	App Secret invalide
challenge_expired	Challenge expiré
challenge_not_found	Challenge introuvable
invalid_answer	Réponse invalide
token_expired	Token expiré
token_already_used	Token déjà utilisé
token_not_found	Token introuvable
quota_exceeded	Quota dépassé
rate_limited	Limite de débit atteinte
rate_limit_exceeded	Trop de requêtes d'émission pour cette application. Patientez puis réessayez.