Aller au contenu

Référence API

API antifraude

Un SDK navigateur pour l'identification, des webhooks signés pour les événements en temps réel et une Server API en lecture seule pour l'historique. Tout ce qu'il vous faut pour stopper la fraude au niveau de l'appareil.

Obtenir une clé APIAPI Playground

Endpoints

SDK@tracio/sdk

Identifiez un visiteur dans le navigateur avec le SDK client. Renvoie un identifiant visiteur stable et un verdict de bot sans aller-retour serveur. La clé publique peut être livrée en toute sécurité dans le code côté client.

Requête

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

Réponse

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}
POST/webhook/tracio

TRACIO délivre un événement signé à votre endpoint à chaque identification. Vérifiez l'en-tête X-Tracio-Signature, puis agissez sur le payload JSON à plat. C'est la surface push : vous n'avez pas à l'interroger. Et si vous devez relire une visite après coup, la Server API répond par requestId.

Requête

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Payload-Version: 2
X-Tracio-Event-Type: identification
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

Réponse

{
  "version": 2,
  "event": "identification",
  "eventId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9:primary",
  "requestId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9",
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "timestamp": "2026-03-12T16:00:00Z",
  "bot": { "result": "human", "score": 2 },
  "identification": { "confidence": 0.95, "incognito": false },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "real", "riskScore": 4 }
}
GET/.well-known/webhook-keys

Récupérez les clés publiques Ed25519 de la plateforme utilisées pour vérifier les livraisons webhook. Cette route ne demande aucune authentification et est mise en cache pendant cinq minutes. Le kid dans l'en-tête de signature vous indique quelle clé utiliser.

Requête

curl https://api.tracio.ai/.well-known/webhook-keys

Réponse

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}
GET/v1/visitors/{visitorId}

Lisez l'historique d'un visiteur depuis la Server API avec votre clé secrète. Disponible à partir du plan Pro. La fenêtre est bornée par votre plan et celle que vous avez réellement obtenue est indiquée dans meta. Prend en charge les demandes de droit d'accès au titre du RGPD.

Requête

# Server API — available on the Pro plan and above
curl "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

Réponse

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-03-01T08:11:00Z",
  "lastSeenAt": "2026-03-16T14:22:01Z",
  "visits": 12,
  "incognitoVisits": 1,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "risk": { "maxRiskScore": 63, "lastDecision": "real" },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true
  },
  "meta": {
    "plan": "pro",
    "retentionDays": 30,
    "from": "2026-02-14T00:00:00Z",
    "to": "2026-03-16T14:30:00Z"
  }
}

Authentification

TRACIO utilise trois identifiants, un par surface : une clé publique pour le SDK navigateur, une clé secrète (tracio_sk_…) envoyée en Authorization: Bearer pour la Server API, et un secret de signature HMAC pour vérifier les livraisons webhook. La clé secrète est créée dans le tableau de bord, affichée une seule fois, et ne doit jamais atteindre un navigateur — la Server API ne renvoie délibérément aucun en-tête CORS.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Server API — secret key, created in the dashboard and shown once
Authorization: Bearer tracio_sk_XXXX...XXXX
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

Limites de débit

Les limites sont par espace de travail. Les appels à la Server API sont comptés séparément des identifications : relire votre propre historique ne consomme jamais le quota que vous payez. Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, plus Retry-After sur un 429. La Server API ne fait pas partie du plan Free.

PlanDébit Server APIServer API par jourEndpoints webhookFenêtre de consultation
GratuitNon inclusNon inclus07 days
Pro10 req/s10,000530 days
Business50 req/s100,0002090 days
Enterprise200 req/sIllimité100365 days

Codes d'erreur

Toutes les erreurs renvoient la même enveloppe : un objet error avec un code sous forme de chaîne, un message lisible et le requestId de l'appel en échec.

400Bad RequestParamètres de requête malformés, fenêtre non prise en charge, ou identifiant qui n'est pas un visitor ID valide.
401UnauthorizedIdentifiants manquants ou invalides — clé publique (SDK), clé secrète (Server API) ou signature webhook.
402Upgrade RequiredVotre plan n'inclut pas l'accès à la Server API. Elle commence avec le plan Pro.
404Not FoundAucun visiteur ni session avec cet identifiant dans la fenêtre de consultation de votre plan.
405Method Not AllowedLa Server API est en lecture seule. Chaque route répond en GET et rien d'autre.
429Rate LimitedTrop de requêtes par seconde, ou quota quotidien épuisé. Vérifiez l'en-tête Retry-After et les limites de votre plan.
500Internal ErrorErreur serveur. Réessayez avec un backoff exponentiel. Si le problème persiste, contactez le support avec le requestId.
503Service UnavailableL'API est temporairement incapable de répondre. Réessayez avec un backoff exponentiel.

Format de la réponse d'erreur

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

Commencez à développer

Obtenez votre clé API et effectuez votre première requête d'identification en moins de 5 minutes.

Obtenir une clé APIDocumentation API complète