---
title: Référence de l'API
---

# 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`](https://github.com/Captcha-La/captchala-php) ([中文](https://github.com/Captcha-La/captchala-php/blob/main/README_zh.md))
> - **Go** — `go get github.com/Captcha-La/captchala-go` · [README](https://github.com/Captcha-La/captchala-go)

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 {#server-token}

É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.
:::

## 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. |