Introduction
Les méthodes de suivi basées sur le navigateur échouent de plus en plus : les bloqueurs de cookies, les politiques ITP/ETP et les restrictions des cookies tiers entraînent des pertes de données d'attribution. Pour les marchands, cela provoque des règles de paiement de commissions incertaines et une augmentation des coûts liés aux impressions non ciblées. Le Server‑to‑Server (S2S) et la Conversions API (CAPI) complètent le suivi côté client et garantissent que les conversions sont capturées, validées et transmises de manière exploitable pour les commissions. Ce guide explique comment configurer S2S/CAPI avec Affilentra, mapper correctement les payloads d'événements, éviter les doublons et définir les priorités de fallback pour le processus de commission.
Vue d'ensemble : architecture et rôles
Affilentra fournit la plateforme avec séparation des rôles : le marchand (Merchant) rapporte les conversions, les affiliés fournissent les identifiants de clic / Click‑IDs, et la plateforme gère le suivi, la validation et la facturation. Pour un fonctionnement résilient, nous recommandons une architecture hybride :
- Suivi côté client (Pixel/JS) comme voie primaire et légère pour transmettre les Click‑IDs.
- Événements côté serveur (S2S/CAPI) comme source fiable pour les confirmations de conversion et de paiement.
- Mécanismes de postback pour les partenaires qui envoient leurs propres événements serveur.
Étape 1 — Configuration de base de l'interface S2S
Préparations :
- SSL/TLS obligatoire pour tous les endpoints.
- Attribution d'une clé API ou d'une clé HMAC à votre compte Affilentra (self‑hosted : gérable localement).
- Définition d'un schéma d'événement contraignant et gestion des versions (p. ex. v1, v2).
Recommandations d'implémentation :
- Exposez un endpoint POST sécurisé côté marchand qui accepte les conversions et les relaie à Affilentra, ou envoyez‑les directement à Affilentra si votre infrastructure le prend en charge.
- Authentification via l'en‑tête Authorization (API‑Key) ou signature HMAC dans les en‑têtes + horodatage pour empêcher les attaques de rejeu.
- Les réponses de confirmation doivent renvoyer un ID d'événement serveur unique que Affilentra utilisera pour les audits.
Étape 2 — Mapping des payloads : champs obligatoires et enrichissements pertinents
Un mapping cohérent réduit les erreurs de matching. Les champs suivants devraient être présents dans chaque événement S2S :
- event_type : p. ex. purchase, refund, lead
- event_id : ID globalement unique (UUIDv4 ou similaire) pour la déduplication
- transaction_id : numéro de commande/paiement de la boutique
- click_id / affiliate_id : ID issu du suivi d'affiliation (si disponible)
- amount et currency : montant brut et devise
- status : authorized, paid, refunded — pour décider du droit à la commission
- timestamp : horodatage ISO8601 en UTC
- user_identifiers : e‑mail haché (SHA256), ID client (optionnel) — jamais d'e‑mails en clair
Champs optionnels pertinents :
- item_lines : SKU, quantity, unit_price — pour les commissions basées sur les produits
- client_ip, user_agent — pour des vérifications forensiques et des contrôles d'anomalies
- payment_method, shipping_status — pour des commissions dépendantes du temps
Étape 3 — Déduplication et validation des conversions
Objectif : n'accepter chaque conversion qu'une seule fois pour le calcul des commissions tout en harmonisant les signaux légitimes reçus plusieurs fois.
Stratégie de déduplication recommandée :
- Clé primaire : event_id. Si event_id est présent et nouveau, accepter et enregistrer.
- Clé de secours : transaction_id + affiliate_id + fenêtre. Si event_id manque, le système vérifie transaction_id combiné à affiliate_id dans une fenêtre temporelle configurable.
- Priorité des sources : attribuez à chaque source un niveau de confiance (voir la section suivante). En cas de conflit, gagne la source avec la priorité la plus élevée.
- Vérification de la signature : HMAC ou signature comparable pour valider la source.
Règles de validation pour l'éligibilité à la commission :
- Seuls les événements avec status = paid (ou un statut de paiement explicitement confirmé) déclenchent le versement des commissions.
- En cas de remboursements ou de rétrofacturations : marquer automatiquement et bloquer ou récupérer la commission, selon votre pratique commerciale.
- Vérifier que click_id / affiliate_id est plausible et correspond à la campagne.
Étape 4 — Priorités de secours dans le processus de commission
Légende : les sources peuvent être client (pixel côté navigateur), serveur (S2S/CAPI) ou partenaire (postback d'affiliation). Recommandation de priorités pour la plupart des commerçants :
- 1. Confirmation de paiement côté serveur (Shop -> Affilentra) : confiance la plus élevée, car le statut de paiement provient de la base de données.
- 2. Postback partenaire avec signature validée et transaction_id : preuve directe du système d'affiliation.
- 3. Événements Server‑CAPI contenant des Click‑IDs et signés.
- 4. Pixel/événement JS côté client : utile pour le temps réel, mais confiance réduite en cas de perte de cookies.
- 5. Imports manuels/par lots : priorité la plus faible et uniquement pour la réconciliation.
Règles essentielles :
- Une conversion déjà confirmée par une priorité supérieure ne doit pas être remplacée par un signal ultérieur de priorité inférieure.
- Consigner les conflits et les rendre visibles dans les processus de réconciliation.
- Fenêtres temporelles configurables : par ex. attribution initiale par le client et statut final par le serveur dans les 24–72 heures (ajustable).
Sécurité et protection des données
Recommandations :
- Transmettez les données personnelles uniquement hachées (p. ex. SHA256 de l'e‑mail avec sel, si nécessaire).
- Authentifiez chaque requête S2S et vérifiez le timestamp + nonce pour prévenir les attaques par rejeu.
- Journalisez uniquement les données nécessaires au dépannage et anonymisez les informations sensibles.
- Documentez les versions de schéma et proposez une stratégie de migration (éviter les breaking changes).
Flux opérationnel et monitoring
Comment garantir la sécurité opérationnelle et la traçabilité :
- Implémentez un système de dead‑letter pour les événements rejetés/erronés.
- Alertes en cas d'anomalies (p. ex. baisse soudaine des événements S2S ou augmentation des doublons).
- Rapprochements réguliers entre les commandes du shop, le prestataire de paiement et les rapports Affilentra.
- Logs d'audit documentant les modifications des règles de commission et les ajustements manuels.
Cas pratique : mappage d'une confirmation d'achat
Payload minimal acceptable (champs d'exemple) :
- event_type: purchase
- event_id: uuid-xyz
- transaction_id: 2026‑000123
- click_id: abc123
- amount: 129.90
- currency: EUR
- status: paid
- timestamp: 2026-10-23T12:34:56Z
- user_identifiers: {email_hash: "sha256:..."}
Important : Si le click_id fait défaut, l'événement peut néanmoins être traité — mais avec une priorité d'attribution plus faible et une vérification supplémentaire sur la transaction_id.
Résumé
Les événements S2S/CAPI sont indispensables pour capter les conversions de manière fiable lorsque les méthodes côté client échouent. Mettez en place une interface S2S signée et protégée par TLS, utilisez des event_ids uniques, mappez de manière cohérente les champs obligatoires et implémentez une priorité de source claire pour les commissions. Le monitoring, les rapprochements et des règles de hachage conformes à la protection des données complètent le dispositif. La combinaison pixel client + S2S/CAPI avec une validation de déduplication constitue la base la plus robuste pour une facturation transparente via Affilentra.
Étape suivante
Essayer Affilentra vous‑même
Plateforme unifiée qui regroupe de manière transparente la mise à disposition des produits, le suivi, la validation des conversions, le calcul des commissions et le versement des paiements selon des rôles clairement distincts ; option d'installation auto‑hébergée avec licence perpétuelle sans participation aux revenus ; les commerçants conservent le contrôle des produits, des conditions et des supports publicitaires ; les partenaires reçoivent des liens de suivi personnels et un historique des paiements traçable.