Le guide du développeur pour le suivi des affiliés côté serveur

Résumé rapide : Le suivi des affiliés côté serveur remplace les pixels dépendants du navigateur par des appels API directs depuis votre backend, capturant chaque conversion indépendamment des bloqueurs de publicités, des paramètres de confidentialité iOS ou des restrictions de cookies.

• Le suivi S2S stocke un ID de clic sur le serveur et envoie un postback à Tapfiliate lorsqu’une conversion se produit
• L’API REST de Tapfiliate gère cela avec deux appels principaux : POST /clicks/ à l’arrivée, POST /conversions/ à l’achat
• La partie la plus complexe n’est pas l’appel API, mais le stockage correct de l’ID de clic lors du premier chargement de la page utilisateur
• Une fois en production, les conversions attribuées augmentent de 60–70 % (pixel, mobile) à une précision quasi totale

Votre tableau de bord affilié affiche 847 conversions ce mois-ci. Votre système de gestion des commandes en affiche 1 203.

La différence représente 356 ventes que votre programme d’affiliation n’a pas pu attribuer. Cela équivaut à 356 commissions calculées sur des estimations, ou 356 ventes générées par des affiliés non récompensés parce qu’un pixel n’a pas été déclenché.

Dans les deux cas, quelqu’un perd de l’argent. Lorsque l’équipe marketing demande pourquoi les chiffres ne correspondent pas, la réponse est toujours la même : « le pixel ».

Ce guide explique pourquoi les pixels échouent, comment le suivi côté serveur résout le problème au niveau de l’architecture et comment l’implémenter avec l’API REST de Tapfiliate en utilisant un code fonctionnel.

Au final, l’écart entre votre nombre de commandes et vos conversions attribuées sera définitivement éliminé.

Pourquoi les pixels échouent (et pourquoi les développeurs sont blâmés)

Les trois modes d’échec du suivi côté client

Un pixel de suivi est déclenché depuis le navigateur de l’acheteur lorsqu’il arrive sur votre page de confirmation. En pratique, il échoue de trois manières distinctes et prévisibles.

Bloqueurs de publicités. Des extensions comme uBlock Origin et Privacy Badger bloquent par défaut les scripts de suivi. L’adoption des bloqueurs de publicités a dépassé 40 % sur desktop en 2025 et continue de croître.

iOS et Safari ITP. La prévention intelligente du suivi d’Apple limite la durée de vie des cookies tiers à 24 heures après la dernière interaction de l’utilisateur avec le tracker. Un acheteur qui clique sur un lien affilié lundi et convertit mercredi n’aura pas de cookie traçable. Le pixel est déclenché, mais il n’y a rien à lire.

Abandon de page avant chargement. Sur des connexions mobiles lentes, les pages de confirmation lourdes en JavaScript peuvent mettre de trois à cinq secondes à se charger complètement. Les acheteurs rapides ferment l’onglet. Le script du pixel ne s’exécute jamais.

Le coût réel de l’écart d’attribution

La différence entre les conversions suivies par pixel et les commandes réelles peut atteindre 30–40 % sur un trafic majoritairement mobile, en cumulant expiration des cookies ITP, bloqueurs de publicités et abandon de page.

Dans un programme versant une commission moyenne de 20 $ pour 1 000 conversions mensuelles, cet écart représente 6 000–8 000 $ de commissions mal attribuées. Les affiliés reçoivent du crédit pour des ventes qu’ils n’ont pas générées ou ne reçoivent pas de crédit pour celles qu’ils ont générées. Aucun de ces scénarios n’est viable.

Le suivi côté serveur élimine totalement la dépendance au navigateur. L’événement de conversion est envoyé de votre serveur à l’API de Tapfiliate. Pas de pixel. Pas de dépendance au navigateur. Pas d’écarts.

Comment fonctionne le suivi des affiliés côté serveur

Le cycle de vie de l’ID de clic

Tout dans le suivi des affiliés côté serveur découle d’un concept : l’ID de clic. Comprendre son cycle de vie rend l’implémentation évidente.

Voici le flux complet de bout en bout :

1. Un utilisateur clique sur un lien affilié. L’URL contient le code de référence de l’affilié, par exemple, ?ref=sarah123.
2. Votre serveur reçoit la requête de la page de destination et détecte le paramètre ref dans l’URL.
3. Votre backend effectue un appel POST /clicks/ à l’API REST de Tapfiliate, transmettant le code de référence.
4. Tapfiliate crée un enregistrement de clic et renvoie un ID de clic unique pour cet événement spécifique.
5. Votre backend stocke l’ID de clic, lié à la session serveur de l’utilisateur ou à une ligne de base de données.
6. L’utilisateur finalise un achat. Votre gestionnaire de confirmation de commande effectue un appel POST /conversions/, transmettant l’ID de clic stocké.
7. Tapfiliate associe l’ID de clic à l’affilié d’origine, calcule la commission et crédite le compte de l’affilié.
8. L’affilié voit la commission apparaître en temps réel sur son tableau de bord Tapfiliate.

Les étapes 1 à 5 se déroulent lors de la requête de la page de destination. Les étapes 6 à 8 ont lieu lors de l’événement de confirmation de commande. Le navigateur de l’acheteur n’intervient que lors de l’étape 1, pour transmettre le paramètre ref dans l’URL.

Côté client vs côté serveur : la différence structurelle

Dans le suivi côté client, le navigateur de l’acheteur est la source de vérité. Il détient le cookie, déclenche le pixel et rapporte la conversion. Toute défaillance sur l’appareil de l’acheteur entraîne une attribution perdue.

Dans le suivi côté serveur, votre backend est la source de vérité. Il capture le code de parrainage à l’arrivée, crée le clic, stocke l’ID du clic et déclenche l’événement de conversion à l’achat. Les paramètres du navigateur de l’acheteur sont sans importance, qu’il s’agisse de cookies, de blocage de JavaScript ou du contexte web vs application.

	Côté client (Pixel)	Côté serveur (API S2S)
Source du signal de conversion	Navigateurs de l’acheteur	Votre serveur backend
Impact du bloqueur de publicités	Bloque le script de suivi	Aucun impact
Impact de l’ITP iOS	Expiration du cookie en 24h	Aucun impact
Précision de l’attribution (mobile)	60–70 %	Presque complète
Suivi multi-appareils	Non	Oui (via session/compte)
Complexité de mise en œuvre	Faible	Moyenne
Exposition au RGPD	Plus élevée (données stockées dans le navigateur)	Moins élevée (contrôlé côté serveur)

L’API REST Tapfiliate : votre boîte à outils d’implémentation

Authentification

Chaque requête à l’API REST Tapfiliate nécessite un en-tête :

X-Api-Key: YOUR_API_KEY

Votre clé API est disponible dans votre compte Tapfiliate sous Paramètres. Stockez-la dans une variable d’environnement. Ne la codez jamais directement dans le code source. Ne l’envoyez jamais dans un dépôt de contrôle de version. Ne l’exposez jamais dans le JavaScript côté client.

La clé API permet de créer des conversions et d’approuver des commissions. Une clé exposée représente un risque financier, pas seulement un risque de suivi.

# Correct: environment variableexport TAPFILIATE_API_KEY="your_key_here"# Wrong: hardcodedconst apiKey = "tap_live_abc123xyz"; // Do not do this

Tous les endpoints utilisent Content-Type : application/json. Toutes les réponses sont en JSON. L’API est actuellement en version 1.6. Pour une référence complète des endpoints, consultez la documentation de l’API REST Tapfiliate.

Une checklist rapide de sécurité pour votre clé API avant d’écrire une seule ligne de code de suivi :

• Stockez la clé dans une variable d’environnement ou un gestionnaire de secrets (AWS Secrets Manager, Vault, GCP Secret Manager).
• Renouvelez la clé si elle a déjà été envoyée dans un dépôt, même brièvement, même dans un dépôt privé.
• Configurez une alerte si la clé est détectée dans un nouveau commit via un outil comme GitGuardian ou le scanner de secrets de GitHub.
• Utilisez des clés distinctes pour staging et production. Un test en staging déclenché avec une clé de production génère des commissions réelles.

Rien de tout cela n’est spécifique à Tapfiliate. Cela s’applique à toutes les clés API que votre backend gère. Mais les clés des plateformes d’affiliation sont particulièrement sensibles, car elles se situent à l’intersection entre l’argent et la confiance des partenaires.

Les trois endpoints essentiels

Pour le suivi d’affiliation côté serveur, vous avez besoin de deux endpoints principaux et d’un endpoint optionnel :

POST /clicks/
Crée un enregistrement de clic lorsqu’un utilisateur arrive via un lien d’affilié. Envoyez le code de parrainage de l’affilié. Tapfiliate retourne un objet clic contenant l’ID du clic.

POST /conversions/
Enregistre une conversion liée à un ID de clic stocké. Tapfiliate attribue la conversion à l’affilié correct et met la commission en file d’attente pour paiement. Envoyez votre ID de commande interne comme external_id pour éviter les doublons.

POST /customers/ (optionnel)
Crée un enregistrement client persistant. Pertinent pour les programmes d’abonnement et SaaS où vous suivez la valeur vie client et souhaitez une attribution récurrente des commissions sur plusieurs événements de facturation, pas seulement sur le premier achat.

Tapfiliate supporte également l’attribution secondaire via code de parrainage ou code promo directement dans le POST /conversions/. Si un utilisateur arrive sans le paramètre ref, mais utilise un coupon affilié lors du paiement, vous pouvez envoyer le code promo dans l’appel de conversion et l’attribution sera précise.

Guide d’implémentation : configuration complète S2S

Ce guide utilise Node.js. Le même modèle s’applique pour Python, Go, Ruby ou tout autre langage backend. Remplacez les appels fetch par votre client HTTP préféré.

Étape 1 : Capturez le paramètre ref de l’affilié à l’arrivée

Chaque visiteur de votre site peut ou non contenir un code de parrainage affilié dans l’URL. Votre middleware de landing doit vérifier cela à chaque requête et créer un clic lorsqu’il est présent.

// Express.js middleware, runs on every incoming page requestapp.use(async (req, res, next) => {  const affiliateRef = req.query.ref || req.query.tap_a;  if (affiliateRef) {    try {      const click = await createTapfiliateClick(affiliateRef);      // Store the click ID in the server-side session      req.session.tapClickId = click.id;    } catch (err) {      // Non-blocking: log the failure, do not prevent page load      console.error('Tapfiliate click creation failed:', err.message);    }  }  next();});

Le bloc try/catch ici est intentionnel et crucial. La création du clic ne doit jamais bloquer le chargement de la page. Si l’API Tapfiliate est lente ou temporairement indisponible, l’utilisateur accède toujours à votre site. Vous enregistrez l’échec et continuez.

Étape 2 : Stockez l’ID du clic côté serveur

La fonction createTapfiliateClick appelle POST /clicks/ et retourne l’ID du clic.

async function createTapfiliateClick(referralCode) {  const response = await fetch('https://api.tapfiliate.com/1.6/clicks/', {    method: 'POST',    headers: {      'Content-Type': 'application/json',      'X-Api-Key': process.env.TAPFILIATE_API_KEY,    },    body: JSON.stringify({      referral_code: referralCode,    }),  });  if (!response.ok) {    throw new Error(`Tapfiliate API returned ${response.status}`);  }  return response.json(); // Returns { id: "click_abc123...", ... }}

Le champ id dans la réponse est l’ID du clic. Stockez-le dans la session serveur, dans un cookie signé avec les flags HttpOnly et Secure activés, ou dans une ligne de base de données liée à l’identifiant de session utilisateur.

Ne stockez pas dans un cookie accessible côté client ni dans le localStorage. Ce stockage est visible par les extensions de navigateur et peut être manipulé.

Étape 3 : Déclenchez le postback de conversion

Lorsqu’un achat est finalisé, appelez POST /conversions/ depuis votre gestionnaire de commandes backend. Ne l’appelez jamais depuis un script frontend ou un gestionnaire de tags.

async function recordTapfiliateConversion(clickId, orderId, orderValue) {  const response = await fetch('https://api.tapfiliate.com/1.6/conversions/', {    method: 'POST',    headers: {      'Content-Type': 'application/json',      'X-Api-Key': process.env.TAPFILIATE_API_KEY,    },    body: JSON.stringify({      click_id:    clickId,      external_id: orderId,    // Your internal order ID (used for deduplication)      amount:      orderValue, // Order value in your program's base currency    }),  });  if (!response.ok) {    const errorBody = await response.text();    console.error(`Tapfiliate conversion failed [${response.status}]: ${errorBody}`);    // Add to retry queue; do not silently discard  }}

Intégrez ceci à votre webhook post-paiement ou gestionnaire de confirmation de commande :

// Post-payment webhook endpointapp.post('/webhooks/payment-confirmed', async (req, res) => {  const { orderId, orderValue, sessionId } = req.body;  // Look up the click ID stored during the user's landing visit  const clickId = await getClickIdForSession(sessionId);  if (clickId) {    await recordTapfiliateConversion(clickId, orderId, orderValue);  }  res.sendStatus(200);});

Selon mon expérience, l’erreur d’implémentation la plus courante est de déclencher cet appel de conversion sur la page « merci » frontend via script ou déclencheur GTM. Si l’acheteur ferme l’onglet avant que la page ne soit complètement chargée (ce qui arrive plus souvent qu’on ne le pense), la conversion est silencieusement perdue. Déclenchez toujours depuis l’événement de confirmation de paiement backend.

Étape 4 : Vérifiez dans le tableau de bord Tapfiliate

Après votre première transaction test, connectez-vous à votre compte Tapfiliate et accédez à Conversions. Confirmez que la conversion apparaît avec le bon affilié, la valeur de la commande et le statut « En attente ».

Une réponse 400 au POST /conversions/ signifie généralement que l’ID du clic est invalide ou expiré. Un 401 indique que l’en-tête de la clé API est absent ou incorrect. Pour la liste complète des codes d’erreur et paramètres supplémentaires, y compris comment joindre des métadonnées ou des IDs clients aux conversions, consultez les guides d’intégration développeurs de Tapfiliate.

Cas extrêmes rencontrés par les développeurs

IDs de clic manquants (trafic direct et dark social)

Tous les visiteurs n’arrivent pas via un lien affilié. Le trafic direct, les newsletters par e-mail, les campagnes SMS et les partages dark social ne contiennent pas de paramètre ref. Votre middleware ne trouve rien, aucun ID de clic n’est stocké et aucun affilié n’est enregistré.

J’ai constaté que les équipes oublient souvent de gérer explicitement ce cas. Les IDs de clic nuls envoyés au POST /conversions/ génèrent des erreurs 400 qui semblent être des échecs d’intégration. Ce n’est pas le cas. Ce sont des situations attendues qui nécessitent une branche conditionnelle.

// In your payment confirmation handlerif (clickId) {  await recordTapfiliateConversion(clickId, orderId, orderValue);} else {  // No affiliate referral detected; organic or direct conversion  logger.info('Conversion recorded without affiliate attribution', { orderId });}

Pour les acheteurs arrivant sans paramètre ref mais utilisant un code promo affilié au paiement, vous pouvez envoyer directement le code promo dans l’appel de conversion au lieu d’un ID de clic. Tapfiliate résout l’attribution à partir du coupon.

Prévention des conversions en double

Les retards réseau provoquent des renvois de webhooks. Sans déduplication, un seul achat déclenche deux ou trois événements de conversion. Votre programme d’affiliation crédite plusieurs fois la même vente.

La solution est le champ external_id dans le POST /conversions/. Tapfiliate rejette toute conversion envoyée avec un external_id déjà existant dans votre compte.

body: JSON.stringify({  click_id:    clickId,  external_id: orderId,   // Your stable internal order ID (safe to retry)  amount:      orderValue,}),

Utilisez toujours votre ID interne de commande comme external_id. Toujours. Ne générez jamais un nouvel ID à chaque tentative de renvoi. Un ID de commande stable garantit que le point de terminaison est idempotent. Vous pouvez essayer autant de fois que nécessaire sans créer de commissions en double.

Attribution multitouch et inter-sessions

Un utilisateur interagit souvent avec plusieurs liens affiliés avant de convertir. Il clique sur une publication Instagram de l’affilié A le lundi. Il clique sur un lien de blog de l’affilié B le jeudi. Il réalise l’achat le vendredi.

Le modèle standard de Tapfiliate attribue la commission au dernier clic, c’est-à-dire à l’affilié B. Si votre modèle de programme utilise l’attribution au premier contact, vous pouvez conserver le premier ID de clic stocké en vérifiant s’il existe déjà dans la session avant de l’écraser :

// Only store a click ID if one is not already present for this sessionif (!req.session.tapClickId) {  const click = await createTapfiliateClick(affiliateRef);  req.session.tapClickId = click.id;}

Le modèle que vous utilisez dépend des règles de votre programme. L’implémentation est identique dans les deux cas. La différence réside dans le fait d’écraser ou non l’ID de clic stocké lors des visites ultérieures sur des liens affiliés.

Confidentialité, sécurité et RGPD

Ne divulguez jamais votre clé API côté client

L’en-tête X-Api-Key authentifie les requêtes qui créent des conversions et valident les commissions. Ce n’est pas un jeton en lecture seule pour l’analyse.

Si la clé apparaît dans une requête réseau du navigateur (un composant React, une balise HTML personnalisée GTM ou une fonction source Segment), tout utilisateur peut l’extraire via les outils de développement du navigateur. Il pourrait alors générer des conversions frauduleuses pour n’importe quel affilié de votre programme.

Toutes les appels à l’API REST de Tapfiliate doivent provenir de votre backend. Votre JavaScript frontend n’a aucune raison légitime d’appeler l’API Tapfiliate. Si vous utilisez un gestionnaire de balises côté client avec votre implémentation S2S, assurez-vous que l’intégration du gestionnaire utilise une couche de données distincte et isolée. Ne transmettez jamais votre clé API via celle-ci.

RGPD et minimisation des données pour les identifiants de clic

Un identifiant de clic est un identifiant pseudonymisé qui, combiné à d’autres données, peut être relié à une personne. Selon le contexte du traitement, il peut être considéré comme une donnée personnelle au sens du RGPD.

Mesures pratiques de conformité :

1. Définissez une limite de conservation. La fenêtre d’attribution standard de Tapfiliate est de 30 jours. Supprimez les identifiants de clic stockés dans votre session ou base de données après 30 jours sans conversion.
2. Évitez les liens inutiles. Ne stockez pas les identifiants de clic dans la même ligne de base de données que des données directement identifiables (nom, e-mail) sans base légale documentée.
3. Incluez la gestion des identifiants de clic dans votre Contrat de Traitement des Données avec Tapfiliate. Le DPA couvre les données que Tapfiliate traite en votre nom.
4. Répondez aux demandes de suppression. Les demandes de droit à l’effacement doivent inclure la suppression des identifiants de clic stockés liés à cet utilisateur.

Pour les programmes avec des utilisateurs de l’UE, documentez le traitement des identifiants de clic dans vos Registres des Activités de Traitement. Pour une lecture approfondie sur l’intégration S2S dans le suivi des programmes d’influenceurs, consultez le suivi hybride des influenceurs avec un logiciel d’affiliation.

Tester votre implémentation S2S

Validation du suivi parallèle

Avant de désactiver votre suivi par pixel existant, faites fonctionner les deux systèmes en parallèle pendant au moins 48 heures. Cela permet de comparer les comptages de conversion et de détecter les problèmes de stockage des identifiants de clic sans perte de données d’attribution.

Le protocole de test :

1. Activez votre code postback S2S en parallèle avec le pixel côté client existant.
2. Générez de 10 à 20 transactions de test contrôlées en utilisant vos propres liens d’affiliés.
3. Comparez le nombre de conversions dans Tapfiliate avec celui de votre système de gestion des commandes.
4. Si les comptages correspondent pour les 10 à 20 commandes de test : le S2S fonctionne correctement. Désactivez le pixel.
5. En cas de divergence : vérifiez d’abord la logique de récupération des identifiants de clic dans le gestionnaire de paiement. La cause la plus fréquente est l’expiration de la session entre l’accès et l’achat pour les achats nécessitant plus de temps de décision.

Une méthode pratique pour tester sans commandes réelles : utilisez le compte affilié de test Tapfiliate et un environnement de préproduction. Créez un affilié test, cliquez sur votre propre lien affilié en mode navigation privée, effectuez un achat test, puis vérifiez si la conversion apparaît dans le tableau de bord Tapfiliate. Cela offre un test complet de bout en bout sans affecter les données de production.

Un dernier point à vérifier : assurez-vous que votre déduplication external_id fonctionne. Envoyez deux fois le même ID de commande test et confirmez que le second appel retourne un code 409 ou un rejet similaire pour duplication. Si les deux appels réussissent, votre déduplication ne fonctionne pas et vous accumulerez des commissions en double lors de nouvelles tentatives de webhook.

La liste des conversions de Tapfiliate affiche la source d’attribution de chaque enregistrement. Vous pouvez filtrer par plage de dates et confirmer que les conversions sont passées par l’API S2S. Si des conversions via le chemin JavaScript apparaissent pendant le test parallèle, votre middleware S2S ne capture pas correctement l’identifiant de clic sur la page d’atterrissage.

Pour les programmes plus importants migrés d’une autre plateforme d’affiliation, consultez le guide de migration des programmes d’affiliation Tapfiliate.

FAQ

Qu’est-ce que le suivi d’affiliation côté serveur ?

Le suivi des affiliés côté serveur envoie les événements de conversion directement depuis votre serveur backend vers l’API de la plateforme d’affiliation, sans dépendre d’un pixel déclenché dans le navigateur de l’acheteur. Comme le signal de conversion provient de votre serveur, il n’est pas affecté par les bloqueurs de publicités, les restrictions de cookies sur iOS ou l’abandon de page avant le chargement du JavaScript.

Qu’est-ce qu’une URL de postback en marketing d’affiliation ?

Une URL de postback est le point de terminaison API que votre serveur appelle pour signaler une conversion réalisée. Lorsqu’un acheteur effectue un achat, votre backend envoie l’ID du clic stocké vers le point de terminaison de la plateforme d’affiliation. La plateforme associe cet ID au clic initial, attribue la conversion à l’affilié correspondant et calcule la commission due.

Qu’est-ce qu’un ID de clic dans le suivi des affiliés ?

Un ID de clic est un identifiant unique généré lorsqu’un utilisateur clique sur un lien d’affiliation. Votre backend capture le code de référence dans l’URL, effectue un appel POST /clicks/ et reçoit en retour l’ID de clic. Vous le stockez sur le serveur. Au moment de l’achat, vous l’envoyez avec l’événement de conversion, servant de preuve reliant un clic spécifique à une vente spécifique sans utiliser de cookies.

Comment implémenter le suivi S2S sans cookies ?

Capturez le paramètre ref de l’URL lors de la première requête sur la page de destination de l’utilisateur. Effectuez un appel POST /clicks/ avec le code de référence et stockez l’ID de clic retourné dans la session serveur ou dans la base de données. Lorsque l’utilisateur convertit, effectuez un appel POST /conversions/ avec l’ID de clic stocké depuis votre gestionnaire de paiement backend. Aucun cookie n’est utilisé à aucune étape. Consultez la documentation de l’API REST de Tapfiliate pour une référence complète des paramètres et schémas de réponse.

Le suivi des affiliés côté serveur est-il conforme au RGPD ?

Oui, lorsqu’il est correctement implémenté. Le suivi S2S n’utilise pas de cookies tiers et offre un contrôle direct sur les identifiants stockés, leur durée et leur base légale. Vous devez documenter le traitement des IDs de clic dans vos Registres des Activités de Traitement, respecter les demandes de suppression et appliquer la minimisation des données. Comparé au suivi par pixel, le suivi côté serveur réduit généralement votre exposition au RGPD, car le navigateur n’est plus le point de collecte des données.

Comblez l’écart

Votre système de gestion des commandes détient déjà la vérité. Chaque achat confirmé y est enregistré.

La seule question est de savoir si votre programme d’affiliation est également informé.

Trois appels API séparent un taux d’attribution de 65 % d’une attribution quasi complète. POST /clicks/ sur la page de destination. ID de clic stocké en session. POST /conversions/ à la confirmation d’achat.

L’affilié qui a généré 847 de ces 1 203 ventes mérite une attribution précise pour ces 847. Votre programme mérite les données pour identifier quelles sources de trafic convertissent réellement et lesquelles ne convertissent pas.

Commencez votre essai gratuit sur Tapfiliate et connectez directement votre backend à l’API REST de Tapfiliate. Aucune carte de crédit requise. Adopté par plus de 69 500 professionnels du marketing et équipes techniques.