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

L’API de données est le pendant côté serveur du SDK Web. 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).

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 :

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

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

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

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.

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.

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

Exemple (pseudo-code)

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 — les champs renvoyés par ces points de terminaison
• SDK Web — collectez les verdicts sur votre page