Comment construire une web app pour l'attribution des revenus partenaires

Ce que l'attribution des revenus partenaires doit accomplir

L'attribution des revenus partenaires est le système qui répond à une question simple : quel partenaire doit recevoir le crédit (et combien) pour un événement générateur de revenus ? Dans une application web, cela signifie que vous ne comptez pas seulement les clics : vous reliez le parrainage d'un partenaire à une conversion ultérieure, vous le transformez en un chiffre de revenu clair et vous rendez le tout auditable.

Définissez “attribution des revenus partenaires” pour votre activité

Commencez par écrire une définition en une phrase qui inclut (1) ce qui est attribué, (2) à qui, et (3) selon quelles règles. Par exemple :

• “Attribuer le revenu d'abonnement au partenaire qui a généré le premier clic éligible dans les 30 jours.”
• “Attribuer la première commande payante au lien de parrainage d'un partenaire, en excluant les conversions uniquement liées aux coupons.”

Cette définition devient l'ancre de vos exigences, de votre modèle de données et des litiges que vous aurez à résoudre plus tard.

Clarifiez qui compte comme partenaire

“Partenaire” regroupe souvent plusieurs groupes avec des attentes et des flux différents :

• Affiliés : volume élevé, tracking basé sur les liens, paiements fréquents.
• Agences : moins d'opérations, cycles de vente plus longs, parfois des conditions négociées.
• Revendeurs : peuvent « posséder » un compte, nécessitent souvent de la facturation plutôt que paiements automatiques.
• Influenceurs/créateurs : préfèrent les codes, les liens courts et des rapports mobile-first.

Évitez d'imposer dès le départ un seul flux pour tous. Vous pouvez utiliser un système unifié (partenaires, programmes, contrats) tout en supportant plusieurs méthodes de parrainage (liens, codes, accords manuels).

Les résultats que vous devez prendre en charge

Une application pratique d'attribution des revenus partenaires doit fournir de manière fiable quatre résultats :

1. Tracking : capturer les points de contact du partenaire (clics, utilisation de codes, parrainages) et les relier aux conversions.
2. Reporting : montrer aux partenaires et à votre équipe ce qui s'est passé — clics, conversions, revenus et statut (pending/approved/paid).
3. Paiements : calculer les commissions, gérer les retenues/remboursements, et produire des états prêts pour paiement.
4. Litiges : expliquer « pourquoi cette conversion a été (ou n'a pas été) créditée », avec suffisamment de détails pour résoudre les conflits.

Si l'un de ces éléments est faible, les partenaires ne feront pas confiance aux chiffres — même si les calculs sont corrects.

Fixez l'objectif de ce guide (et de votre première version)

Pour un guide de construction exploitable, l'objectif n'est pas de débattre de la philosophie d'attribution — c'est de vous aider à livrer un système fonctionnel. Une première version réaliste devrait :

• Tracker les liens/click_id et les conserver jusqu'à l'inscription/au checkout
• Enregistrer les conversions côté serveur quand c'est possible
• Appliquer une règle d'attribution claire (même simple)
• Produire un reporting visible par les partenaires et une réconciliation interne

Vous pourrez ajouter des fonctionnalités avancées (attribution multi-touch, stitching cross-device, scoring anti-fraude complexe) une fois que les bases seront fiables et testables.

Exigences et questions clés à répondre

Avant de choisir un modèle d'attribution ou de concevoir une base de données, clarifiez ce que l'application doit prouver à l'entreprise. L'attribution des revenus partenaires est finalement un ensemble de réponses auxquelles les gens font assez confiance pour payer.

Identifiez vos utilisateurs (et ce que “succès” signifie pour chacun)

La plupart des équipes construisent d'abord pour les “partenaires” et découvrent ensuite que les finances ou le support ne peuvent rien vérifier. Listez vos utilisateurs principaux et les décisions qu'ils prennent :

• Partenaire (affilié/parrain) : veut voir les conversions créditées, le revenu et le statut des paiements.
• Marketing/Croissance : veut savoir quels partenaires performent et où investir.
• Finance : a besoin de calculs de paiement audités et de réconciliation avec le revenu réel.
• Support/gestionnaires partenaires : doit expliquer pourquoi une conversion a été ou n'a pas été créditée.
• Ingénierie/Data : a besoin d'événements fiables, de règles claires et d'opérations peu exigeantes.

Les 5–8 questions centrales auxquelles votre application doit répondre

Formulez-les comme des requêtes en langage simple que votre UI et vos rapports doivent supporter :

1. Quel partenaire (le cas échéant) a généré cette commande/abonnement ?
2. Quelle preuve relie la conversion à ce partenaire ? (click ID, coupon, code de parrainage, etc.)
3. Quand le clic/lead a-t-il eu lieu par rapport à la conversion ? (dans la fenêtre autorisée ?)
4. Cette conversion est-elle éligible à une commission ? (nouveau client uniquement, exclusions produit, minimum dépensé)
5. Quel est le montant et le taux de commission, et quelle règle l'a déterminé ?
6. La conversion a-t-elle changé après coup ? (remboursement, chargeback, annulation, downgrade)
7. Que devons-nous à chaque partenaire pour une période donnée, et qu'a-t-on payé ?
8. Les conversions pilotées par les partenaires se comparent-elles aux autres canaux ? (pour le reporting marketing)

Définissez les événements à capturer

Au minimum, prévoyez : click, lead, début d'essai, achat, renouvellement, et remboursement/chargeback. Décidez lesquels sont « commissionnables » et lesquels servent de preuves de support.

Choisissez les types d'attribution à supporter en premier

Commencez avec un jeu de règles clair — fréquemment last-touch dans une fenêtre configurable — puis ajoutez le multi-touch seulement si vous avez de forts besoins de reporting et des données propres. Gardez la première version simple à expliquer et à auditer.

Choisir un modèle d'attribution et des règles

Avant d'écrire le moindre code, décidez ce qui « obtient le crédit » et quand ce crédit expire. Si vous ne définissez pas les règles en amont, vous vous retrouverez à débattre des cas limites (et des plaintes partenaires) à chaque cycle de paiement.

Modèles d'attribution courants (vue d'ensemble)

Dernier clic attribue 100 % du crédit au clic partenaire le plus récent avant la conversion. C'est simple et largement compris, mais peut sur-récompenser le trafic coupon en fin de parcours.

Premier clic attribue 100 % du crédit au premier partenaire qui a introduit le client. Il privilégie les partenaires de découverte, mais peut sous-récompenser ceux qui ferment la vente.

Linéaire répartit le crédit de manière égale entre tous les points de contact partenaires qualifiants dans la fenêtre. Cela peut sembler “équitable”, mais est plus difficile à expliquer et dilue les incitations.

Décroissance temporelle assigne plus de crédit aux touches proches de la conversion tout en reconnaissant l'influence antérieure. C'est un compromis, mais nécessite plus de calculs et un reporting plus clair.

Choisissez un défaut, puis documentez les exceptions

Choisissez un modèle par défaut pour la plupart des conversions (beaucoup d'apps démarrent avec dernier clic parce qu'il est plus facile à expliquer et à rapprocher). Documentez ensuite explicitement les exceptions afin que le support et la finance puissent les appliquer de manière cohérente :

• Codes promo : décidez si un coupon valide annule l'historique des clics, partage le crédit, ou ne s'applique que si le partenaire a aussi généré un clic.
• Trafic direct : précisez si les visites directes « cassent la chaîne » (réinitialisent l'attribution) ou simplement ne comptent pas comme touch.
• Renouvellements : décidez si les abonnements récurrents continuent à payer le partenaire original, paient seulement pendant une période limitée ou nécessitent une réengagement.

Définir les fenêtres d'attribution et la réengagement

Fixez une ou plusieurs fenêtres comme 7 / 30 / 90 jours. Une approche pratique est une fenêtre standard (par ex. 30 jours) plus des fenêtres plus courtes pour les partenaires coupons si nécessaire.

Définissez aussi des règles de réengagement : si un client clique un autre lien partenaire dans la fenêtre, changez-vous immédiatement le crédit (dernier clic), le partagez-vous, ou conservez-vous le partenaire initial sauf si le nouveau clic est dans une « fenêtre proche » (par ex. 24 heures) ?

Gérer upgrades, downgrades, remboursements et chargebacks

Décidez ce que vous attribuez : l'achat initial seulement, ou le revenu net dans le temps.

• Upgrades : typiquement commissionnables ; spécifiez si vous payez sur le delta ou sur le montant total du nouveau plan.
• Downgrades : réduisent généralement les commissions futures ; définissez si vous récupérez les paiements antérieurs.
• Remboursements/chargebacks : définissez une politique de clawback (annulation totale vs partielle) et un timing (immédiat vs cycle de paiement suivant).

Rédigez ces règles dans un court document « Politique d'attribution » et liez-le dans votre portail partenaire pour que le comportement système corresponde aux attentes des partenaires.

Concevoir le modèle de données pour l'attribution

Un modèle de données propre fait la différence entre « nous pensons que ce partenaire a généré la vente » et « nous pouvons le prouver, le rapprocher et payer correctement ». Commencez par un petit ensemble d'entités cœur et rendez explicites les relations via des IDs immuables.

Entités cœur (et ce qu'elles représentent)

• Partner : à qui vous payez (éditeur, influenceur, agence). Stockez partner_id, statut, conditions de paiement, devise par défaut.
• Campaign : un regroupement pour le reporting et les règles (promo saisonnière, gamme produit). Clé : campaign_id, dates de début/fin.
• Link : une URL traçable fournie à un partenaire. Clé : link_id, appartient à partner_id et optionnellement à campaign_id.
• Click : une interaction trackée unique. Clé : click_id, référence link_id et partner_id.
• Visitor : une identité que vous pouvez reconnaître entre sessions. Clé : visitor_id (souvent dérivée d'un ID de cookie first-party).
• Conversion : l'événement attribué (lead, signup, achat). Clé : conversion_id, référence click_id (quand disponible) et visitor_id.
• Order : l'enregistrement commercial utilisé pour l'argent. Clé : order_id, référence customer_id et liée à conversion_id.
• Payout : ce que vous devez et quand. Clé : payout_id, référence partner_id et agrége les commandes éligibles.

Comment les IDs se connectent (la “chaîne de custody”)

Votre parcours idéal est :

partner_id → link_id → click_id → visitor_id → conversion_id → order_id → payout_id

Conservez customer_id aux côtés de order_id afin que les achats répétés puissent suivre vos règles (par ex. « première commande seulement » vs « à vie »). Stockez à la fois vos IDs internes et externes (par ex. shopify_order_id) pour la réconciliation.

Champs monétaires et ajustements

Les commandes évoluent. Modélisez cela explicitement :

• Stockez les montants en entiers en unités mineures (ex. cents) : gross_amount, tax_amount, shipping_amount, fee_amount, discount_amount.
• Ajoutez currency_code ainsi qu'un fx_rate_to_payout_currency (et l'horodatage/source de ce taux).
• Représentez les remboursements/chargebacks comme des lignes d'ajustement liées à order_id (ex. order_adjustment_id, type = partial_refund). Cela préserve un historique auditable et évite de réécrire les totaux.

Auditabilité et qualité des données

Ajoutez des champs d'audit partout : created_at, updated_at, ingested_at, source (web, server-to-server, import), et des identifiants immuables.

Pour l'analyse anti-fraude sans stocker de données personnelles brutes, conservez des champs hachés comme ip_hash et user_agent_hash. Enfin, gardez un journal de changements léger (entité, entity_id, valeurs old/new, acteur) afin que les décisions de paiement puissent être expliquées ultérieurement.

Implémenter le suivi des clics et les liens partenaires

Le suivi des clics est la base de l'attribution des revenus partenaires : chaque lien partenaire devrait créer un enregistrement de “click” durable que vous pourrez ensuite relier à une conversion.

Définissez une structure de lien claire (et prévisible)

Utilisez un format de lien canonique unique que les partenaires peuvent copier/coller partout. Dans la plupart des systèmes, le lien côté partenaire ne devrait pas inclure un click_id — votre serveur le génère.

Un schéma propre est :

/r/{partner_id}?campaign_id=...&utm_source=...&utm_medium=partner&utm_campaign=...

Conseils pratiques pour les paramètres :

• partner_id : requis ; propriétaire principal du clic.
• campaign_id : optionnel mais recommandé ; sépare les offres, emplacements ou promos.
• utm_* : conservez-les pour les outils analytics et le reporting marketing. Traitez-les comme métadonnées, pas comme source de vérité.

Préférez le tracking côté serveur via un endpoint de redirection

Routez tout le trafic partenaire via un endpoint de redirection (ex. /r/{partner_id}) :

1. Recevoir la requête entrante et lire les paramètres.
2. Générer un click_id unique (UUID/ULID) et stocker une ligne click côté serveur (partner_id, campaign_id, user agent, ip_hash, timestamp, landing URL).
3. Définir un cookie first-party (et optionnellement localStorage) contenant le click_id.
4. 302 redirect vers la page de destination finale.

Cela rend la création du clic cohérente, empêche les partenaires de falsifier les click_id, et centralise l'application des règles.

Cookie vs localStorage vs sessions côté serveur

• Cookies : envoyés à chaque requête ; meilleurs pour le matching côté serveur. Peuvent être bloqués/limités par les navigateurs et les règles de consentement.
• localStorage : persistance facile côté page, mais pas automatiquement envoyée au serveur ; vous devez la lire côté client.
• Stockage de session côté serveur : ne fonctionne que si le navigateur conserve un identifiant de session ; bon pour les fenêtres courtes, moins fiable pour des fenêtres d'attribution longues.

La plupart des équipes utilisent cookie comme primaire, localStorage en fallback, et les sessions côté serveur uniquement pour les flux de courte durée.

Considérations mobile et app-to-web

Pour le web mobile, les cookies peuvent être moins fiables, utilisez donc l'endpoint de redirection et stockez le click_id à la fois en cookie et en localStorage.

Pour app-to-web, supportez :

• Deep links (ouvrir l'app avec le contexte partenaire).
• Attribution différée (deferred attribution) : si l'app n'est pas installée, routez vers le store web/app, puis transmettez un token à courte durée de vie afin que le premier lancement de l'app puisse l'échanger contre le click_id original.

Documentez précisément les règles de lien dans votre portail partenaire (voir /blog/partner-links) pour que les partenaires n'« inventent » pas des paramètres.

Capturer les conversions de manière fiable

Le suivi des conversions est l'endroit où les systèmes d'attribution gagnent ou perdent la confiance. Votre objectif est d'enregistrer un événement de “conversion” canonique par achat réel (ou par inscription), avec suffisamment de contexte pour le connecter à un clic partenaire.

Choisissez vos sources de conversion (et privilégiez-en une canonique)

La plupart des produits peuvent observer les conversions depuis plusieurs endroits :

• Page “thank you” du checkout (client-side) : facile à implémenter, mais peut être bloquée, perdue, ou déclenchée deux fois.
• Service de commande backend (server-side) : source la plus fiable car elle reflète le système de référence.
• Webhooks des fournisseurs de paiement (server-side) : utiles lorsque la confirmation de paiement est asynchrone (ex. 3DS, virements bancaires), mais il faut gérer les retries.

Recommandation : traitez votre service de commande backend comme l'enregistreur canonique des conversions, et utilisez éventuellement les webhooks de paiement comme signal de confirmation/mise à jour (ex. passer une commande de pending à paid). Les événements côté client peuvent servir au debugging ou à l'analytics de funnel, pas pour l'attribution de niveau paiement.

Enregistrez les conversions côté serveur (et persistez le contexte d'attribution)

Pour attribuer le revenu plus tard, l'événement de conversion a besoin d'un identifiant stable et d'un moyen de lier à un clic.

Approche commune :

1. Quand quelqu'un arrive via un lien partenaire, générez/conservez un click_id.
2. Persistez-le dans un cookie first-party et/ou dans la base de données lié à une session/utilisateur.
3. Au moment de l'achat, faites en sorte que le backend attache le click_id à la commande (par ex. depuis l'état de session, le record client, ou un token signé envoyé par le client).

Mapper les conversions aux clics (avec règles de secours claires)

Votre jointure primaire doit être conversion.click_id → click.id. Si click_id manque, définissez des règles de secours explicites, telles que :

• Si l'utilisateur est connecté : utilisez le clic éligible le plus récent pour cet utilisateur dans votre fenêtre d'attribution.
• Sinon : utilisez le clic de session éligible le plus récent.
• Si plusieurs clics existent : décidez à l'avance si « dernier touch wins » ou si vous autorisez le multi-touch.

Rendez ces règles visibles dans les outils d'administration afin que le support puisse expliquer les résultats sans deviner.

Gérer les retries et les doublons avec idempotence

Les webhooks et appels client vont retry. Vous devez pouvoir recevoir la même conversion plusieurs fois sans double-comptabiliser.

Implémentez des clés d'idempotence en utilisant une valeur unique stable, telle que :

• order_id (meilleur si globalement unique)
• ou payment_provider_charge_id

Stockez la clé sur le record de conversion avec une contrainte d'unicité. En cas de retry, retournez un succès et ne créez pas une seconde conversion. Ce seul choix évite les bugs les plus courants de revenus fantômes lors des paiements.