---
title: Prévention de la fraude — API de données
---

# API de données de prévention de la fraude

L’API de données est le pendant côté serveur du [SDK Web](./web-sdk). Utilisez-la pour
récupérer les verdicts, agréger des statistiques et exporter des données pour le
**reporting et le rapprochement** — en obtenant les chiffres sur lesquels vos propres
systèmes s’accordent.

## URL de base

```
https://apiv1.captcha.la
```

## Authentification

Toutes les requêtes de l’API de données sont authentifiées avec les identifiants de votre
application de prévention de la fraude, envoyés dans les en-têtes :

```
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, aux
applications mobiles ni aux dépôts publics. Le SDK de page n’utilise que la clé publique
`appKey`.
:::

## Points de terminaison

### Récupérer un verdict

Récupérez le verdict d’une visite unique (par ex. pour rapprocher une visite précise).

```bash
GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

Le champ `data` de la réponse est un objet [`BotVerdict`](./verdict-reference) :

```json
{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}
```

### Statistiques agrégées

Récupérez des comptages en paliers sur une plage de temps — totaux, part de bots et
répartition par `action`/`level` — pour les tableaux de bord et les rapports de qualité.

```bash
GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

```json
{
  "code": 0,
  "data": {
    "from": "2026-06-01",
    "to": "2026-06-30",
    "total": 124500,
    "bots": 18230,
    "bot_rate": 0.146,
    "by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
    "by_level":  { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
  }
}
```

### Export

Exportez les lignes de verdict par visite sur une plage de temps, pour un rapprochement
hors ligne.

```bash
GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

Chaque ligne porte l’identifiant de la visite, l’horodatage et les champs du verdict
(`is_bot`, `score`, `level`, `action`), afin que vous puissiez la rapprocher de vos propres
journaux.

::: tip Rapprochement par clic
Pour les scénarios de trafic payant, une seule visite peut être reliée à un clic livré
précis afin que deux parties puissent se régler dessus. Cela s’appuie sur un jeton de clic
et est traité dans le guide [Fraude publicitaire](./scenarios/ad-fraud).
:::

## Référence du jeton de clic (pour les fournisseurs de trafic)

Un fournisseur de trafic signe un **jeton de clic** sur son propre serveur et l’ajoute à l’URL de destination, afin que le verdict de la visite résultante lui soit attribué. La signature se fait hors ligne — aucun appel d’API.

### Obtenir vos identifiants de signature
Dans le tableau de bord, ouvrez votre application → Fraud Prevention → **Émettre une clé de signature**. Vous recevez :
- `bot_kid` — l’identifiant de votre clé publique (placé dans le jeton sous `pkid`).
- `bot_hmac_secret` — votre secret de signature, affiché **une seule fois**. Conservez-le côté serveur.

### Format du jeton
```
ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>
```
`body` est le base64url de la charge utile JSON ; la signature est calculée sur cette chaîne `body`.

### Champs de la charge utile
| champ | requis | description |
|---|---|---|
| `pkid` | oui | votre `bot_kid` ; le backend l’utilise pour retrouver votre secret et vérifier la signature |
| `cid` | oui | identifiant unique de ce clic ; la clé de réconciliation. Générez une valeur nouvelle et unique pour chaque clic |
| `aud` | non | l’`app_key` de l’**annonceur ciblé**. Lorsqu’il est défini, le jeton n’est honoré que sur la page de cet annonceur. Omettez-le pour qu’une page de n’importe quel annonceur l’accepte |
| `click_ts` | non | secondes unix correspondant au moment du clic |
| `exp` | non | secondes unix d’expiration ; les jetons expirés sont rejetés |

### L’ajouter au lien
Ajoutez le jeton comme paramètre de requête `_ctk` à l’URL de destination de l’annonceur :
```
https://advertiser.example/lp?_ctk=ct.<...>.<...>
```
Le SDK de l’annonceur lit `_ctk` automatiquement (configurable via `tokenParam`). Un `cid` ne peut être réclamé qu’une seule fois (protection contre le rejeu). Voir le [Modèle de sécurité](./scenarios/ad-fraud#modele-de-securite).

### Exemple (pseudo-code)
```js
const payload = { pkid, cid, aud: advertiserAppKey, click_ts: now, exp: now + 900 }
const body  = base64url(JSON.stringify(payload))
const sig   = base64url(hmacSha256(body, botHmacSecret))
const token = `ct.${body}.${sig}`
const url   = `${destination}?_ctk=${encodeURIComponent(token)}`
```

## Étapes suivantes

- [Référence du verdict](./verdict-reference) — les champs renvoyés par ces points de terminaison
- [SDK Web](./web-sdk) — collectez les verdicts sur votre page