---
type: how-to
title: Migrer depuis reCAPTCHA
summary: "Échange reCAPTCHA contre Caputchin avec des changements minimaux : la même forme en deux parties (un widget client plus une vérification côté serveur) se mappe presque un pour un, voici l'avant-après exact pour chaque pièce."
---

Caputchin utilise le même modèle en deux parties que reCAPTCHA, un widget sur la page qui produit un token, et une vérification côté serveur qui le confirme, donc migrer est surtout un échange mécanique, pas une réécriture. L'échange serveur en particulier reflète à dessein la forme `siteverify` de reCAPTCHA. Ce guide donne l'avant-après pour chaque pièce.

Si tu n'as pas encore créé de compte Caputchin et de clé de site, fais d'abord [créer ton compte](/docs/getting-started/create-your-account) ; tu auras besoin d'une **clé publique** (`cpt_pub_...`) pour la page et d'un **secret** (`cpt_sec_...`) pour ton backend, le même partage que la clé de site et la clé secrète de reCAPTCHA.

## Le modèle mental est inchangé

```mermaid
flowchart LR
  A["Widget sur ta page"] -->|token| B["Ton formulaire / ta requête"]
  B -->|token| C["Ton backend"]
  C -->|secret + token| D["Point de terminaison siteverify"]
  D -->|réussi ?| C
```

Tout ce que tu as déjà bâti autour de reCAPTCHA, rendre un widget, collecter un token, le POSTer vers ton serveur, le vérifier avant de faire confiance à la requête, reste. Seuls les noms et les points de terminaison changent.

## 1. Échange l'extrait client

| | reCAPTCHA (case à cocher v2) | Caputchin |
|---|---|---|
| Script | `<script src="https://www.google.com/recaptcha/api.js" async defer>` | `<script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js">` |
| Élément | `<div class="g-recaptcha" data-sitekey="...">` | `<caputchin-widget sitekey="cpt_pub_...">` |
| Champ de token dans un formulaire | `g-recaptcha-response` (auto-injecté) | `caputchin-token` (auto-injecté) |
| Lire le token en JS | `grecaptcha.getResponse()` | le `detail.token` de l'[événement `pass`](/docs/references/widget-methods-and-events) |

Comme reCAPTCHA, le widget Caputchin **auto-injecte un champ de token caché** dans le formulaire où il se trouve, donc si ton formulaire faisait déjà un POST normal, tu ne changes que l'élément et le nom du champ que ton backend lit. Vois [ajouter le widget](/docs/getting-started/add-the-widget) pour la configuration client complète et [le choix CDN contre npm](/docs/integration-guides/cdn).

## 2. Échange la vérification serveur

C'est là que les deux sont les plus proches, les formes de requête et de réponse s'alignent presque champ pour champ.

| | reCAPTCHA | Caputchin |
|---|---|---|
| Point de terminaison | `POST https://www.google.com/recaptcha/api/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| Champs de requête | `secret`, `response` | `secret`, `response` (identiques) |
| Réponse | `{ success, challenge_ts, hostname, "error-codes" }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| Règle de confiance | agis seulement si `success === true` | agis seulement si `success === true` (identique) |

Dans la plupart des stacks, le seul changement à ton code de vérification est l'URL et la valeur du secret. La référence complète requête/réponse, y compris les codes d'erreur, est sur [vérifier un token sur ton backend](/docs/integration-guides/verify-on-your-backend) ; les extraits par framework sont dans [exemples backend](/docs/integration-guides/backend-examples).

## 3. Mappe le score, si tu utilisais reCAPTCHA v3

reCAPTCHA v3 renvoie un `score` (0.0 à 1.0) et te demande de choisir un seuil, tu devines à quel point une requête semblait humaine. Caputchin ne fonctionne **pas** comme ça : `success` est un réussite/échec faisant autorité, parce que la vérification a réellement été réussie (une vérification de proof of work, ou une [manche de jeu re-dérivée sur le serveur](/docs/understanding-caputchin/gaming-anti-cheat)), pas une probabilité.

Si ton code avait `if (data.score >= 0.5)`, remplace-le par `if (data.success)`. Le champ `score` de Caputchin n'existe que pour les manches de jeu et est le score du **jeu** (informatif, pour tes propres tableaux des scores), jamais une probabilité de bot, donc ne fonde pas l'accès dessus.

## Ce qui s'améliore dans le passage

- **Aucune collecte de données visiteur.** reCAPTCHA profile tes visiteurs ; Caputchin ne collecte ni IP, ni User-Agent, ni empreinte, ni télémétrie comportementale, le protocole n'a nulle part où mettre un identifiant de visiteur. Vois la [philosophie](/docs/understanding-caputchin/philosophy).
- **Un widget, pas v2-contre-v3.** Il n'y a pas de produit invisible/score séparé entre lesquels choisir ; un élément couvre la case à cocher et le jeu optionnel.
- **Un jeu optionnel.** Au lieu d'une grille de feux de circulation, tu peux transformer la vérification en un court jeu que tes visiteurs jouent réellement. Vois [ajouter un jeu](/docs/getting-started/add-a-game).
- **Une CSP stricte reste stricte.** Caputchin tourne sous une Content-Security-Policy serrée ; tu autorises quelques origines plutôt que de relâcher ta politique. Vois [comment Caputchin met les jeux en bac à sable](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page).

## Pièges

- **Deux clés, deux foyers.** La clé publique (`cpt_pub_...`) va sur la page ; le secret (`cpt_sec_...`) reste côté serveur uniquement, exactement la discipline reCAPTCHA. Ne livre pas le secret au navigateur.
- **Le token est à usage unique.** Comme reCAPTCHA, un token se vérifie une fois. Ne le mets ni en cache ni en rejeu.
- **Change le nom du champ que ton backend lit.** Le champ caché est `caputchin-token`, pas `g-recaptcha-response`, un oubli d'une ligne courant.

## Voir aussi

- [Ajouter le widget](/docs/getting-started/add-the-widget) : la configuration client complète.
- [Vérifier un token sur ton backend](/docs/integration-guides/verify-on-your-backend) : la référence `siteverify` faisant autorité.
- [Exemples backend](/docs/integration-guides/backend-examples) : l'appel de vérification dans chaque langage.
- [Ajouter un jeu](/docs/getting-started/add-a-game) : transformer la vérification en un jeu.