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.

Étapes suivantes

• Référence du verdict — les champs renvoyés par ces points de terminaison
• SDK Web — collectez les verdicts sur votre page