Tracking des clics

Flux de tracking

Le parcours d'un clic à la conversion suit ces étapes :

1. L'affilié génère un lien via POST /api/affiliate-links/generate
2. L'acheteur clique sur le lien /go/{linkId}
3. Le clic est enregistré avec IP hashée, user-agent, pays et référent
4. Un cookie first-party est posé avec l'ID affilié, le lien et l'offre
5. L'acheteur est redirigé vers la page du vendeur
6. La conversion est ingérée via POST /conversions/ingest
7. L'attribution last-click est calculée dans la fenêtre définie
8. Le postback est envoyé à l'affilié si configuré

Générer un lien affilié

Pour créer un lien tracké, l'affilié doit d'abord être approuvé pour l'offre ciblée. Le lien généré utilise un identifiant opaque qui ne révèle ni l'affilié ni l'offre.

Demander l'affiliation à une offre

curl -X POST https://flendra.com/api/offers/{offerId}/affiliation-requests \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "message": "Je souhaite promouvoir cette offre à mon audience."
  }'

Générer le lien tracké

curl -X POST https://flendra.com/api/affiliate-links/generate \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "offerId": "off_abc123",
    "sub1": "newsletter",
    "sub2": "janvier-2026"
  }'

Réponse :

{
  "success": true,
  "data": {
    "id": "link_xyz789",
    "offerId": "off_abc123",
    "affiliateUserId": "usr_aff456",
    "url": "https://flendra.com/go/link_xyz789",
    "shortUrl": "https://flendra.com/go/link_xyz789",
    "sub1": "newsletter",
    "sub2": "janvier-2026",
    "createdAt": "2026-06-17T10:30:00.000Z"
  }
}

Redirection et enregistrement du clic

Le endpoint GET /go/:linkId est le cœur du tracking. Il est public, rate-limité à 30 requêtes/minute par IP, et effectue les opérations suivantes de manière asynchrone :

• Validation du lien (existence, statut actif)
• Vérification de la destination (allowlist SSRF)
• Enregistrement du clic avec hash IP + user-agent
• Positionnement du cookie d'attribution first-party
• Redirection 302 vers la page du vendeur

Paramètres de requête optionnels

Cookie d'attribution

Après l'enregistrement du clic, un cookie first-party est posé sur le domaine du vendeur. Ce cookie contient :

Set-Cookie: _nraff=eyJhZmZpbGlhdGVVc2VySWQiOiJ1c3JfYWZmNDU2IiwibGlua0lkIjoibGlua194eXo3ODkiLCJvZmZlcklkIjoib2ZmX2FiYzEyMyIsImNvcnJlbGF0aW9uSWQiOiJjb3JyLWFiYy0xMjMifQ==; Path=/; Max-Age=2592000; Secure; SameSite=Lax

Propriétés du cookie :

• Nom : _nraff
• Durée : 30 jours (configurable)
• Flags : Secure, SameSite=Lax
• Contenu : Base64 de { affiliateUserId, linkId, offerId, correlationId }

Modèle d'attribution

Flendra utilise un modèle last-click dans une fenêtre configurable (défaut : 30 jours). Le dernier clic affilié avant la conversion reçoit la commission. Le système gère :

• Déduplication : les clics avec la même clé d'idempotence sont ignorés
• Vélocité : les clics excessifs d'un même affilié sont signalés
• Anti-fraude : détection d'IP hopping, fingerprints anormales

Ingester une conversion

Lorsqu'un achat est confirmé sur la page du vendeur, la conversion doit être ingérée via l'API :

curl -X POST https://flendra.com/api/conversions/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_votrecleapi" \
  -d '{
    "orderId": "CMD-2026-001",
    "orderAmount": 4999,
    "currency": "EUR",
    "buyerEmail": "acheteur@exemple.com",
    "clickId": "clk_abc123",
    "items": [
      {
        "productId": "prod_xyz",
        "offerId": "off_abc123",
        "quantity": 1,
        "unitPrice": 4999
      }
    ]
  }'

Réponse (nouvelle conversion) :

{
  "success": true,
  "data": {
    "status": "INGESTED",
    "conversionId": "conv_def456",
    "attribution": {
      "affiliateUserId": "usr_aff456",
      "linkId": "link_xyz789",
      "offerId": "off_abc123",
      "clickId": "clk_abc123",
      "commissionAmount": 1500,
      "commissionType": "percentage",
      "currency": "EUR",
      "explanation": "Last-click attribution within 30-day window"
    }
  }
}

Sous-identifiants (sub1-sub5)

Les sous-identifiants permettent aux affiliés de segmenter leurs campagnes. Ils sont transmis dans le postback et visibles dans les rapports :

{
  "sub1": "newsletter",
  "sub2": "janvier-2026",
  "sub3": "facebook",
  "sub4": "video-tutorial",
  "sub5": "variant-a"
}