Guide du module Programme d'affiliation pour Larapen

Laissez d’autres personnes vendre pour vous. Les partenaires reçoivent un lien de parrainage, une bibliothèque de bannières prêtes à l’emploi et leur propre tableau de bord ; chaque vente apportée par leur lien leur crédite une commission dont vous fixez le montant, la retient jusqu’à l’expiration du délai de remboursement, puis la leur verse lorsqu’ils la demandent.

Cas d’utilisation

• Programme de partenaires. Blogueurs, testeurs et consultants vous envoient des clients et touchent une part de chaque vente.
• Parrainage de clients. Vos clients partagent leur lien avec leurs collègues et gagnent un crédit à déduire de leur propre facture.
• Revendeurs de cours et de formations. Des formateurs promeuvent vos cours et sont rémunérés à chaque inscription, à un taux différent de celui de votre boutique.
• Parrainages hors ligne et en personne. Un partenaire distribue un code de réduction ; la vente lui est créditée même si aucun lien n’a jamais été cliqué.
• Taux propres à une campagne. Un produit rapporte 30 % pendant un mois de lancement tandis que tout le reste conserve le taux standard.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• Des comptes utilisateurs activés sur le front-end : un affilié se connecte pour voir son tableau de bord

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Télécharger un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez Affiliate & Referral dans la liste et cliquez sur Activer. Ses tables de base de données et ses permissions sont mises en place automatiquement, et les pages du programme répondent immédiatement.

Étape 3 : Définir vos conditions

Allez dans Admin → Affiliés → Paramètres et définissez la commission que vous versez, la fenêtre de suivi, la période de retenue et le versement minimum. Voir Démarrage rapide.

Code d’achat (clé de licence)

Affiliate & Referral est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence), distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez Affiliate & Referral dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée : acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque dans votre compte Gumroad.

3. Envato Market (CodeCanyon)

• Envato délivre lui-même le code d’achat. Nous ne l’envoyons jamais par e-mail, car nous ne le recevons pas.
• Récupérez-le depuis votre compte Envato : Downloads → trouvez l’article → License certificate & purchase code (la version texte comme la version PDF le contiennent).
• Il ressemble à xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Démarrage rapide

Cinq minutes entre l’activation et un programme opérationnel.

1. Définissez ce que vous versez. Admin → Affiliés → Paramètres → Commissions. Choisissez un pourcentage de la vente ou un montant fixe, et définissez la période de retenue (30 jours est une valeur par défaut raisonnable : elle couvre la plupart des délais de remboursement).
2. Définissez la durée de validité d’un clic. Paramètres → Suivi. Trente jours signifie qu’un visiteur qui suit un lien aujourd’hui rapporte encore une commission à son parrain s’il achète dans trois semaines.
3. Définissez le seuil de versement. Paramètres → Versements. Les partenaires ne peuvent pas demander de versement en dessous, ce qui vous évite de traiter une série de minuscules virements.
4. Rédigez vos conditions. Paramètres → Programme → Conditions du programme. Elles apparaissent sur la page publique des conditions et sont liées depuis le formulaire de candidature, que les candidats doivent cocher pour les accepter.
5. Ajoutez une ou deux bannières. Admin → Affiliés → Bannières. Facultatif, mais les partenaires vous promeuvent bien plus volontiers lorsque le matériel est prêt à coller.
6. Mettez le programme en lien. Ajoutez /affiliates à un menu (voir Ajouter le programme à un menu) pour que les visiteurs puissent le trouver.

Affiliés

Un affilié est l’un de vos utilisateurs auquel est rattaché un code de parrainage. Un utilisateur, un compte d’affilié.

Candidatures

Un visiteur connecté postule depuis /affiliates/apply. Le formulaire lui demande son site web (facultatif), comment il compte vous promouvoir, comment il souhaite être payé, et exige qu’il accepte vos conditions.

La suite dépend d’un paramètre :

• Approuver les candidatures automatiquement : désactivé (par défaut) : la candidature est enregistrée En attente d’examen, les administrateurs sont notifiés, et rien n’est suivi pour cette personne tant que vous ne l’avez pas approuvée.
• Approuver les candidatures automatiquement : activé : le candidat gagne des commissions dès qu’il envoie le formulaire. Adapté à un système de parrainage de clients, risqué pour un programme de partenaires ouvert.

Vous pouvez aussi ajouter un partenaire manuellement depuis Affiliés → Ajouter un affilié, ce qui permet d’intégrer une personne avec qui vous avez convenu des conditions hors ligne.

Pour ne plus accepter de nouveaux venus tout en maintenant le programme pour les partenaires existants, désactivez Accepter les nouvelles candidatures. Les pages du programme restent en ligne et les commissions continuent de s’accumuler ; seul le formulaire de candidature est fermé.

Statuts

Codes de parrainage

Chaque affilié reçoit un code court : huit caractères, sans les caractères ambigus (0/O, 1/I), car ces codes sont lus à voix haute et imprimés. Vous pouvez remplacer un code par quelque chose de mémorable lorsque vous créez ou modifiez l’affilié : lettres et chiffres uniquement.

Émettre un nouveau code sur la page de l’affilié révoque immédiatement l’ancien. Tout lien déjà partagé avec celui-ci cesse de rapporter : ne l’utilisez donc que lorsqu’un code a fuité.

Suivi des parrainages

Liens & liens courts

Un affilié dispose de deux formes du même lien :

• Le lien court : https://your-site.example/r/THEIRCODE. Assez court pour une carte de visite ou la description d’une vidéo.
• Un lien suivi vers n’importe quelle page : toute URL de votre site se terminant par ?ref=THEIRCODE. Son tableau de bord les construit pour lui : il colle un chemin, et obtient en retour le lien complet.

Les deux enregistrent le clic et déposent le même cookie : peu importe donc celui qu’utilise un partenaire. Le lien court peut aussi porter une destination : /r/THEIRCODE?to=/shop amène le visiteur dans votre boutique. Seuls les chemins de votre propre site sont suivis : tout ce qui pointe ailleurs mène à la page d’accueil.

La fenêtre de suivi

Un clic est mémorisé pendant la durée définie dans Paramètres → Suivi → Fenêtre de suivi (30 jours par défaut). Pendant cette fenêtre, toute vente réalisée par le visiteur rapporte une commission. En dehors, rien n’est crédité.

La fenêtre est conservée à deux endroits : dans un cookie du navigateur du visiteur et, dès qu’il se connecte, sur son compte. Le second compte vraiment : un paiement confirmé par un prestataire de paiement quelques minutes plus tard arrive sans navigateur ni cookie, et c’est l’enregistrement sur le compte qui permet à cette vente de retrouver malgré tout son parrain.

Modèle d’attribution

Lorsqu’un visiteur suit les liens de deux partenaires différents, l’un d’eux doit l’emporter :

• Le dernier clic l’emporte (par défaut) : le lien le plus récent obtient la vente. Le choix habituel, et celui qu’attendent les partenaires.
• Le premier clic l’emporte : celui qui a amené le visiteur le garde pendant toute la fenêtre, quoi qu’il arrive ensuite. Plus juste envers le partenaire qui a fait le travail de découverte.

Codes promo

Liez un code de réduction à un affilié depuis sa page, sous Codes promo liés. Toute vente réalisée avec ce code lui est créditée même si aucun lien de parrainage n’a jamais été suivi : c’est ainsi qu’un partenaire qui travaille hors ligne, dans un podcast ou sur un prospectus imprimé, est rémunéré.

Créez le code de réduction lui-même là où vous le faites habituellement ; cet écran enregistre seulement à qui il appartient. Un lien de parrainage a toujours la priorité : le code promo n’est consulté que lorsqu’aucun clic n’est trouvé.

Auto-parrainage

Un affilié n’est jamais rémunéré pour son propre achat. C’est vérifié au moment du clic puis de nouveau lors de la vente : ni se connecter plus tard, ni utiliser son propre code promo ne permet de contourner la règle.

Commissions

D’où viennent les ventes

Le programme ne vend rien lui-même : il écoute les add-ons qui vendent. Chacun d’eux est facultatif, et un add-on qui n’est pas installé ne signale tout simplement jamais rien.

Règles de commission

Admin → Affiliés → Règles de commission. Sans aucune règle, chaque vente rapporte le taux par défaut du programme. Ajoutez des règles pour payer différemment sur une partie de votre catalogue, pour une source ou pour un partenaire.

Les règles sont examinées de la plus spécifique à la plus générale, et la première qui correspond l’emporte :

1. Un affilié : un taux convenu nommément avec un partenaire.
2. Un produit : un taux de lancement sur un seul article.
3. Une catégorie : tout ce qui se trouve dans une section de votre catalogue.
4. Une source : toutes les inscriptions aux cours, ou toutes les recharges.
5. Tout : votre taux maison.

Deux règles du même type sont départagées par la Priorité : la plus élevée en premier. Une règle peut aussi comporter un montant de vente minimum, en dessous duquel elle est ignorée et la règle suivante s’applique.

Paliers de volume

Admin → Affiliés → Paliers de volume. Facultatif. Un palier augmente automatiquement le taux d’un partenaire dès que le total de ses ventes parrainées dépasse un seuil : 12 % à partir de 2 500 $, 15 % à partir de 10 000 $, et ainsi de suite.

Un partenaire est toujours placé dans le palier le plus élevé qu’il a atteint, et son tableau de bord indique à quelle distance il se trouve du suivant. Les paliers ne sont consultés que lorsqu’aucune règle de commission ni aucun taux propre à l’affilié ne s’applique.

La période de retenue

Une nouvelle commission est En attente. Elle le reste pendant le nombre de jours défini dans Paramètres → Commissions → Période de retenue, qui doit couvrir la période pendant laquelle un acheteur peut encore demander à être remboursé.

Une fois la retenue écoulée, une tâche nocturne la passe à Approuvée, c’est-à-dire payable. Pour examiner plutôt chaque commission manuellement, désactivez Approuver automatiquement après la retenue ; elles vous attendent alors sur l’écran Commissions.

Pressé ? Libérer les commissions validées sur cet écran approuve tout ce dont la retenue est déjà passée, sans attendre l’exécution nocturne.

Remboursements & annulations

Lorsqu’une vente quitte l’état payé (remboursée, annulée ou contestée), sa commission est annulée et retirée du solde du partenaire. C’est à cela que sert la période de retenue : dans le cas normal, l’argent n’a jamais été payable au départ.

Une commission déjà versée n’est jamais récupérée automatiquement. L’argent est parti, et la conduite à tenir relève d’une décision humaine, pas d’une règle.

Vous pouvez aussi annuler ou refuser manuellement une commission depuis l’écran Commissions, avec un motif.

Versements

Fonctionnement du solde

Trois chiffres, qui ont des significations différentes :

• En attente : gagné, encore dans le délai de remboursement. Pas encore payable.
• Disponible : les commissions approuvées, moins ce que couvre déjà une demande de versement en cours. C’est ce qu’un partenaire peut demander immédiatement.
• Versé à ce jour : ce qui a réellement été remis.

Demander un versement réserve immédiatement le montant : un partenaire ne peut donc pas demander deux fois les mêmes commissions pendant le traitement de la première demande.

Modes de versement

Désactivez tout mode que vous ne proposez pas et les partenaires ne le verront pas. Les coordonnées fournies par un partenaire (compte bancaire, adresse PayPal) sont stockées chiffrées, et une copie est figée sur chaque demande de versement : les modifier plus tard ne peut donc pas réécrire l’historique d’un versement déjà effectué.

Régler un versement

1. La demande arrive dans Admin → Affiliés → Versements et les administrateurs sont notifiés.
2. Marquez-la éventuellement Approuvée pendant que vous préparez le virement, utile lorsque plusieurs personnes se partagent le travail.
3. Payez-la, puis cliquez sur Marquer comme payé et enregistrez la référence de la transaction pour que le partenaire puisse la rapprocher de ses propres relevés.

Le marquage comme payé passe les commissions couvertes à l’état Payée, les rattache au versement, met à jour les totaux du partenaire et lui envoie un e-mail. Un versement en crédits de portefeuille effectue son crédit à ce même moment.

Exporter en CSV vous fournit la sélection en cours sous forme de tableur (noms, montants, modes et coordonnées de versement), c’est-à-dire ce qu’attend le formulaire de virements groupés d’une banque.

Bannières & liens

Admin → Affiliés → Bannières. Tout ce que vous publiez ici apparaît dans le tableau de bord de chaque partenaire approuvé, portant déjà son propre code de parrainage. Trois types :

• Bannière image : choisissez une image et indiquez sa taille. Les partenaires copient un extrait prêt à l’emploi dans lequel l’image est enveloppée dans leur lien suivi.
• Extrait HTML : rédigez vous-même le balisage ; {link} est remplacé par le lien du partenaire. Adapté à un bouton stylisé ou à un petit encart promotionnel.
• Lien texte : simplement l’URL suivie, avec une formulation suggérée pour une newsletter ou une signature.

Page d’arrivée détermine où la bannière envoie le visiteur, sous forme de chemin (/shop, par exemple). Laissez-le vide pour votre page d’accueil. Les titres et descriptions sont traduisibles : un partenaire les voit donc dans sa propre langue.

L’espace affilié

Les partenaires connectés disposent de quatre pages qui leur sont propres, accessibles depuis le menu du compte :

Les pages publiques sont /affiliates (ce que rapporte le programme et comment le rejoindre) et /affiliates/terms. Ces deux pages sont indexables ; aucune page personnelle ne l’est.

Ajouter le programme à un menu

Allez dans Admin → Apparence → Menus, ouvrez le menu souhaité (le pied de page est l’emplacement habituel d’un programme de partenaires), et ajoutez un élément de type URL personnalisée pointant vers /affiliates.

Le tableau de bord de l’affilié ne demande aucun travail sur les menus : Compte affilié est ajouté automatiquement au menu déroulant du compte connecté tant que l’add-on est actif.

Notifications

Six notifications, chacune activable ou désactivable dans Admin → Paramètres → Notifications :

Chacune est envoyée par e-mail et sous forme de notification (cloche) dans le panneau. Les trois qui portent une décision concernant le compte de quelqu’un (approuvée, refusée, versement effectué) sont toujours envoyées, car un partenaire doit en être informé.

Multilingue

Chaque écran, e-mail et page publique est traduit dans les langues fournies avec l’add-on, et suit automatiquement la langue du visiteur.

Deux éléments que vous rédigez vous-même sont traduisibles par langue :

• Les conditions du programme, dans Paramètres → Programme.
• Les titres, descriptions et textes des bannières, sur chaque bannière.

Utilisez le sélecteur de langue au-dessus de ces champs pour changer de langue. Une langue laissée vide se rabat sur votre langue par défaut.

Confidentialité & conservation

• Les adresses ne sont jamais stockées. Un clic conserve un hachage à sens unique de l’adresse IP du visiteur : suffisant pour reconnaître une visite répétée, jamais suffisant pour retrouver l’adresse.
• Les coordonnées de versement sont chiffrées. Les coordonnées bancaires et PayPal sont chiffrées dans la base de données et affichées uniquement aux administrateurs autorisés à voir les versements.
• Les clics sont purgés. Les clics qui n’ont jamais abouti à une vente sont supprimés après le nombre de jours défini dans Paramètres → Suivi → Conserver les clics pendant (180 par défaut ; 0 les conserve indéfiniment). Les clics qui ont abouti à une conversion sont conservés, car ils constituent la preuve d’une commission.
• Le cookie de suivi ne contient rien d’autre qu’une référence interne, est limité à votre propre site et expire avec la fenêtre de suivi.

Paramètres

Admin → Affiliés → Paramètres, en cinq onglets.

Programme

Suivi

Commissions

Versements

En-tête de page

Remplace l’apparence de l’en-tête sur les pages publiques du programme (hauteur, arrière-plan, couleurs) sans toucher au reste de votre site.

Permissions

L’add-on enregistre ses propres permissions, attribuables par rôle dans Admin → Utilisateurs → Rôles.

Tâches planifiées

Une tâche s’exécute chaque jour et fait deux choses : elle approuve les commissions dont la période de retenue est écoulée, et elle supprime les clics qui n’ont jamais abouti et qui ont dépassé leur durée de conservation.

Elle s’exécute dans le cadre du planificateur de votre site : il n’y a donc rien à configurer tant que le planificateur lui-même fonctionne. Sinon, les commissions restent simplement En attente jusqu’à ce que vous cliquiez sur Libérer les commissions validées sur l’écran Commissions : rien n’est perdu, cela ne se fait simplement pas tout seul.

Mise à jour

Téléversez le nouveau ZIP depuis Admin → Extensions → Add-ons, exactement comme la première fois. Les fichiers sont remplacés, les éventuelles nouvelles modifications de la base de données sont appliquées, et vos affiliés, commissions, versements, règles, paliers, bannières et paramètres sont tous conservés.

Désactivation

Éteindre l’add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Affiliate & Referral et cliquez sur Désactiver.

• Ses routes, vues, entrées du menu d’administration et permissions ne sont plus enregistrées ; les pages du programme et les liens /r/<code> cessent de répondre.
• Les liens de parrainage ne sont plus suivis et aucune nouvelle commission n’est enregistrée.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées (chaque affilié, commission et versement) et ses fichiers restent sous extensions/addons/affiliate/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est lui aussi conservé : réactiver l’add-on ne vous le redemande donc pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le réactiver. Les migrations en attente sont réexécutées et le programme reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux étapes :

1. Désactivez Affiliate & Referral (voir Désactivation).
2. Cliquez sur Supprimer sur sa carte et confirmez.

Le panneau d’administration effectue alors, en une seule passe :

• l’exécution du hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• la révocation des permissions déclarées dans son addon.json ;
• l’annulation de ses migrations (cela supprime ses tables de base de données et toutes les lignes qu’elles contiennent, y compris chaque compte d’affilié, chaque commission jamais enregistrée et l’historique complet des versements) et la purge de ses entrées dans la table migrations, pour qu’une réinstallation ultérieure reparte de zéro ;
• la suppression de ses assets publiés : public/addons/affiliate/, public/vendor/affiliate/ et storage/app/public/addons/affiliate/ ;
• la suppression du répertoire de l’add-on extensions/addons/affiliate/ ;
• la suppression de sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et le vidage du cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/affiliate/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le répertoire et sur son parent, puis réessayez.

Supprimer le dossier par FTP ou SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne dans addons sont toutes laissées en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

Une vente n’a pas été créditée au partenaire qui a envoyé l’acheteur

• Vérifiez que l’affilié est Approuvé. Les partenaires en attente, refusés ou suspendus ne gagnent rien.
• Vérifiez que le clic se trouve encore dans la fenêtre de suivi. Un visiteur qui a cliqué il y a six semaines avec une fenêtre de 30 jours n’est plus attribué.
• Vérifiez qu’il ne s’agit pas d’un auto-parrainage : un partenaire qui achète avec son propre lien n’est jamais rémunéré.
• Vérifiez que l’acheteur n’a pas suivi plus récemment le lien d’un autre partenaire, avec Le dernier clic l’emporte.
• Si l’acheteur ne s’est jamais connecté et que son navigateur bloque les cookies, il ne reste rien pour attribuer la vente. Un code promo est la solution de repli fiable dans ce cas.

Les commissions restent bloquées en attente

• Elles ne sont validées qu’une fois la période de retenue écoulée. Leur ligne indique la date.
• Approuver automatiquement après la retenue est peut-être désactivé, auquel cas elles vous attendent volontairement.
• Le planificateur ne fonctionne peut-être pas. Utilisez Libérer les commissions validées sur l’écran Commissions en attendant.

Un partenaire ne peut pas demander de versement

• Son solde Disponible doit être supérieur ou égal au versement minimum. Les commissions encore en attente ne comptent pas.
• Il a peut-être déjà une demande en cours, qui réserve le montant qu’elle couvre jusqu’à son règlement.
• Au moins un mode de versement doit être activé et, pour le virement bancaire ou PayPal, il doit avoir renseigné ses coordonnées.

Les versements en crédits de portefeuille ne sont pas proposés

Les crédits de portefeuille nécessitent l’add-on portefeuille installé et actif. Sans lui, ce mode est masqué aux partenaires et ne peut pas être activé dans les paramètres.

Les pages du programme renvoient “page introuvable”

• L’add-on est peut-être désactivé. Vérifiez Admin → Extensions → Add-ons.
• Programme d’affiliation est peut-être désactivé dans les paramètres, ce qui masque les pages publiques.

Un libellé traduit ne s’affiche pas

• Choisissez la langue dans le sélecteur au-dessus du champ et vérifiez qu’il est renseigné pour cette langue : chacune est stockée séparément.
• Les traductions vides se rabattent sur votre langue par défaut, ce qui est généralement le comportement souhaité.