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

Une seule URL de base

Tous les endpoints de cette page sont sur apiv1.captcha.la. Les hôtes de secours (bypass.*, fallbackapiv1.*) sont des cibles de bascule que les SDK contactent d'eux-mêmes pendant une panne — y pointer votre intégration renvoie service_online.

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.

bash

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" }

client_ip est facultatif mais recommandé : l'IP de l'utilisateur final issue de votre requête entrante, utilisée pour des contrôles de risque supplémentaires. Vous pouvez l'omettre sans problème.

json

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}

L'objet captcha_args est purement informatif (pour vos logs / votre analyse de risque) :

Champ	Description
`platform`	Plateforme depuis laquelle le challenge a été résolu.
`user_ip`	IP enregistrée au moment de la résolution.
`referer`	URL de référence de la page du challenge.
`pkg`	Identifiant de package de l'app (mobile), le cas échéant.
`solved_at`	Horodatage Unix de la résolution.
`risk_score`	Score de risque de la session de résolution.

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.

bash

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

json

{
  "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.

Endpoints de secours hors ligne

CaptchaLa maintient un service de secours sur des hôtes distincts afin que la vérification continue de fonctionner quand l'API principale est injoignable :

Hôte	Appelé par	Rôle
`bypass.captchala.com` · `bypass.captcha-cdn.net`	SDK web / natif (côté utilisateur final)	Effectue la vérification hors ligne et émet un pass token `offline_` pendant la panne
`fallbackapiv1.captchala.com` · `fallbackapiv1.captcha-cdn.net`	SDK serveur	Valide les tokens `offline_` (`POST /api/validate`)

Ce sont des cibles de bascule, pas une API alternative. Les SDK y basculent seuls, uniquement après un échec réel de l'API principale, et reviennent dès qu'elle est rétablie. Rien dans votre configuration ne doit pointer dessus.

`service_online` (HTTP 503)

json

{ "code": -1, "error": "service_online", "message": "Main API is online, please use main API" }

Vous obtenez cette erreur tant que l'API principale fonctionne : le service de secours ne sert du trafic que pendant une panne. La requête est arrivée sur bypass.* au lieu de https://apiv1.captcha.la — corrigez l'URL, réessayer ne changera rien.

Causes fréquentes :

Cause	Correctif
Option SDK `apiServer` pointant vers un hôte bypass	La remettre sur `https://apiv1.captcha.la`, ou la supprimer et laisser le SDK choisir
`bypassServers` surchargé à la main	Retirer la surcharge, sauf si nous vous avons donné des hôtes précis
Un client HTTP maison a repris une URL bypass (par ex. depuis les devtools pendant un incident)	Appeler `https://apiv1.captcha.la` et laisser le SDK gérer la bascule — le service de secours n'accepte pas le trafic de challenge normal
Load balancer / proxy / DNS qui réécrit l'hôte de l'API	Repointer l'upstream sur `apiv1.captcha.la`

TIP

La validation côté serveur n'a pas non plus besoin de l'hôte de secours : POST /v1/validate sur apiv1.captcha.la suffit, et les SDK serveur PHP / Go vérifient automatiquement les tokens offline_ auprès de l'API de secours.

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.
`service_online`	La requête a atteint le service de secours hors ligne alors que l'API principale est en ligne. Utilisez `https://apiv1.captcha.la` — voir Endpoints de secours hors ligne.

Référence de l'API ​

URL de base ​

Authentification ​

API de validation côté serveur ​

Validation de token côté serveur ​

Token de challenge émis par le serveur ​

Émettre un server token ​

Paramètres du corps (form-urlencoded) ​

Initialiser un challenge ​

Endpoints de secours hors ligne ​

service_online (HTTP 503) ​

Codes d'erreur ​

Référence de l'API

URL de base

Authentification

API de validation côté serveur

Validation de token côté serveur

Token de challenge émis par le serveur

Émettre un server token

Paramètres du corps (form-urlencoded)

Initialiser un challenge

Endpoints de secours hors ligne

`service_online` (HTTP 503)

Codes d'erreur