Installation

Cette page installe les deux moitiés de Perfex CRM Integration for WHMCS. Suivez-la dans l'ordre. L'ensemble du processus se fait depuis deux onglets de navigateur et le gestionnaire de fichiers de votre panneau d'hébergement. Ni SSH ni ligne de commande ne sont nécessaires.

Vous devez avoir décompressé upload.zip (themesic.com/marketplace/whmcs-perfex.zip), ce qui vous donne deux fichiers :

Fichier	Destination
🧩 perfex-module/module.zip	Perfex CRM
⚙️ whmcs-addon/addon.zip	WHMCS

Installation rapide (version courte)

Pour un administrateur d'hébergement expérimenté, toute l'opération tient en cinq gestes. Effectuez-les dans cet ordre.

1. 🧩 Perfex d'abord. Dans Perfex CRM, allez dans Setup > Modules > Upload Module, téléversez module.zip, puis Activate. Installer le côté Perfex en premier garantit que le point de réception existe avant même que WHMCS n'envoie quoi que ce soit.
2. ⚙️ Module complémentaire WHMCS. Téléversez et extrayez addon.zip dans modules/addons/ de manière à obtenir modules/addons/perfexbridge/perfexbridge.php, puis activez Perfex CRM Bridge sous System Settings > Addon Modules.
3. 🔓 Cochez Access Control. Sur l'écran Configure du module complémentaire, cochez Full Administrator (ainsi que tout autre rôle censé l'utiliser) et cliquez sur Save Changes. Sans cela, le module est invisible - il n'apparaît pas du tout dans le menu Addons.
4. 🔗 Appairez les deux côtés. Ouvrez Addons > Perfex CRM Bridge, collez le Connection code copié depuis Perfex dans le champ Quick setup, puis cliquez sur Connect. Détails dans Configuration.
5. ✅ Vérifiez. Créez un client de test dans WHMCS, cliquez sur Run Sync Now et confirmez qu'il apparaît dans Perfex sous Customers.

Chaque clic, chaque ligne de la checklist et la vérification complète de bout en bout figurent dans la Procédure détaillée ci-dessous.

Procédure détaillée

L'ordre a son importance

Installez d'abord le compagnon Perfex. C'est lui qui crée le point de réception. Si vous installez d'abord le module complémentaire WHMCS et lancez la synchronisation, tous les événements échouent tant que le côté Perfex n'existe pas, et vous perdrez du temps à lire des journaux d'erreurs pour un problème que vous n'avez pas encore créé.

Étape 1 : installer le module compagnon Perfex CRM

Le compagnon Perfex est gratuit, ne comporte aucune clé de licence et s'installe entièrement depuis l'administration Perfex.

1. Connectez-vous à Perfex CRM en tant qu'Administrator.
2. Allez dans Setup > Modules.
3. Cliquez sur le bouton Upload Module.
4. Sélectionnez module.zip dans le sélecteur de fichiers et téléversez-le.
5. Perfex affiche le module sous le nom WHMCS Bridge. Cliquez sur Install si l'invite apparaît, puis sur Activate.

Si le téléversement est refusé pour cause de taille

Le bouton Upload Module transmet l'archive via PHP : les limites upload_max_filesize et post_max_size de votre serveur doivent donc toutes deux être supérieures à la taille du fichier. Si le téléversement échoue, augmentez ces limites dans votre configuration PHP, ou utilisez la solution de repli manuelle ci-dessous.

Solution de repli manuelle : extrayez module.zip sur votre ordinateur et téléversez le dossier whmcs_bridge obtenu dans le répertoire modules/ de votre installation Perfex, par FTP ou via le gestionnaire de fichiers de votre panneau d'hébergement. Le résultat doit être modules/whmcs_bridge/whmcs_bridge.php. Retournez ensuite dans Setup > Modules et cliquez sur Activate.

Vérifier que le côté Perfex est correctement installé

• Une nouvelle entrée WHMCS Bridge apparaît dans le menu Setup de Perfex. C'est sur cette page que vous générerez le secret partagé au chapitre suivant.

Étape 2 : installer le module complémentaire WHMCS

WHMCS ne propose aucun installateur de modules intégré à l'administration. Vous placez vous-même les fichiers sur le disque, puis vous activez le module depuis l'administration. Le gestionnaire de fichiers de votre panneau d'hébergement suffit à tout faire.

1. Ouvrez le gestionnaire de fichiers de votre panneau d'hébergement et accédez au répertoire modules/addons/ de votre installation WHMCS.
2. Téléversez addon.zip dans modules/addons/.
3. Utilisez l'action Extract du gestionnaire de fichiers sur l'archive téléversée, en extrayant dans ce même répertoire modules/addons/.
4. Vérifiez que le résultat est bien modules/addons/perfexbridge/perfexbridge.php. Si vous obtenez modules/addons/perfexbridge/perfexbridge/perfexbridge.php, l'extraction a créé un niveau d'imbrication de trop. Remontez le dossier interne d'un niveau et supprimez l'enveloppe vide.
5. Supprimez du serveur l'archive addon.zip une fois l'extraction réussie.

Variante FTP

Extrayez d'abord addon.zip sur votre propre ordinateur, puis téléversez le dossier perfexbridge obtenu dans modules/addons/ par FTP. Le résultat final est identique.

Activez-le maintenant :

6. Dans WHMCS, allez dans System Settings > Addon Modules.
7. Repérez Perfex CRM Bridge dans la liste et cliquez sur Activate.

Étape 3 : cocher Access Control, sinon le module reste invisible

C'est le signalement « il ne s'est pas installé » le plus fréquent

Après l'activation, WHMCS affiche le panneau de configuration du module avec une section Access Control listant vos rôles d'administration. Vous devez cocher au minimum Full Administrator, ainsi que tout autre rôle censé utiliser le module, puis cliquer sur Save Changes.

Tant qu'aucun rôle n'est coché, le module n'apparaît pas du tout dans le menu Addons de gauche. Le module est bien installé, ses tables existent et sa page de paramètres fonctionne parfaitement, mais aucun lien n'y mène nulle part dans l'administration. Neuf fois sur dix, « le module ne s'est pas installé » signifie que cette case n'a jamais été cochée.

Concrètement :

1. Toujours dans System Settings > Addon Modules, cliquez sur Configure à côté de Perfex CRM Bridge. WHMCS ouvre généralement ce panneau automatiquement juste après l'activation.
2. Sous Access Control, cochez Full Administrator. Cochez également tout autre rôle d'administration devant pouvoir ouvrir et configurer la passerelle.
3. Cliquez sur Save Changes.
4. Actualisez l'administration. Perfex CRM Bridge apparaît désormais dans le menu Addons.

Access Control est la seule chose présente sur l'écran Configure

Tous les véritables paramètres de ce module se trouvent sur sa propre page, dans Addons > Perfex CRM Bridge, et non sur l'écran Configure de WHMCS. L'écran Configure ne conserve qu'Access Control, car cette section est rendue par le cœur de WHMCS et ne peut pas être déplacée. Si vous ouvrez Configure à la recherche de l'URL Perfex ou de la clé de licence, vous êtes au mauvais endroit. Consultez Configuration.

Étape 4 : ouvrir la page du module

Allez dans Addons > Perfex CRM Bridge.

La page s'ouvre sur la Setup checklist. Sur une installation neuve, elle se présente ainsi :

Ligne de la checklist	État attendu à ce stade
Module tables present	🟢 coche verte
Connection configured	🔴 croix rouge, aucun appairage effectué
Connection verified	⚪ tiret gris, jamais vérifié
Sync enabled	🔴 croix rouge jusqu'à ce que vous cochiez Enable Sync
Cron delivering	🔴 croix rouge, aucune activité cron enregistrée
License / plan	⚪ tiret gris, offre Free

C'est l'état correct pour une passerelle fraîchement installée et non configurée. Chaque ligne est expliquée dans Configuration.

Passez maintenant à l'appairage des deux côtés : Configuration.

Étape 5 : vérifier la première synchronisation de bout en bout

Faites-le une fois, immédiatement après l'appairage, avant de confier de vraies données à la passerelle. Cela prend deux minutes et valide toute la chaîne.

1. Réalisez l'appairage décrit dans Configuration. Les lignes Connection configured et Connection verified de la checklist doivent toutes deux être vertes.
2. Sur la même page, sous Settings > Sync behaviour, assurez-vous que Enable Sync est coché, puis cliquez sur Save Settings. La ligne Sync enabled passe au vert.
3. Dans WHMCS, créez un client de test. N'importe quel nom et adresse e-mail conviennent, par exemple une société nommée Bridge Test Ltd.
4. Revenez dans Addons > Perfex CRM Bridge. Le compteur Queue pending en haut de page doit afficher au moins 1.
5. Cliquez sur Run Sync Now. Cela force une tentative de livraison immédiate sans attendre le cron. La page indique combien d'événements ont été envoyés, ont échoué ou sont passés en rebut.
6. Dans Perfex CRM, ouvrez Customers. Le client de test y figure désormais comme client, avec le nom et l'adresse e-mail du client WHMCS comme contact principal.
7. Vérifiez que les deux journaux l'ont enregistré :
   • Côté WHMCS : le tableau Recent activity, plus bas sur la page du module, affiche une ligne client.upsert avec le statut ok.
   • Côté Perfex : Setup > WHMCS Bridge, panneau Recent inbound events, affiche une ligne client.upsert correspondante avec un badge vert ok.
8. Supprimez le client de test des deux systèmes si vous ne souhaitez pas le conserver.

« Run Sync Now » ne prouve pas que votre cron fonctionne

Run Sync Now valide la livraison. En revanche, cela ne fait pas passer au vert la ligne Cron delivering de la checklist, car cette ligne suit délibérément l'activité réelle du cron système WHMCS. Si cette ligne est toujours rouge ou orange une heure plus tard, votre cron système WHMCS n'est pas actif et rien ne se synchronisera automatiquement. Corrigez le cron avant la mise en production. Consultez Dépannage.

Mettre à jour vers une version plus récente

Les deux modules portent le même numéro de version et doivent toujours être mis à jour ensemble.

Côté Perfex. Téléversez le nouveau module.zip via Setup > Modules > Upload Module, en écrasant le module existant, puis chargez n'importe quelle page d'administration. Le compagnon détecte la version de base de données obsolète et applique ses propres migrations sur place. Si vous préférez, désactivez puis réactivez le module. Les deux méthodes sont sûres : chaque instruction de migration est protégée, une nouvelle exécution ne modifie donc rien de ce qui est déjà correct.

Côté WHMCS. Téléversez et extrayez le nouveau addon.zip par-dessus modules/addons/perfexbridge/. WHMCS exécute la routine de mise à niveau du module dès qu'il détecte le nouveau numéro de version. En cas de doute, désactivez puis réactivez le module dans System Settings > Addon Modules.

Vos paramètres survivent à une mise à niveau

Les paramètres, le secret partagé, la clé de licence, la table de correspondance des entités et les journaux résident tous dans des tables de base de données que les mises à niveau ne suppriment jamais. Désactiver le module complémentaire WHMCS n'efface pas non plus ses données.

Désinstallation

1. WHMCS : System Settings > Addon Modules > Perfex CRM Bridge > Deactivate, puis supprimez modules/addons/perfexbridge/ du disque.
2. Perfex : Setup > Modules, désactivez WHMCS Bridge, puis supprimez le module.
3. Si vous souhaitez également supprimer les données, supprimez les tables de base de données du module dans chaque système (effectuez d'abord une sauvegarde).
4. Si une licence Pro était active, supprimez la clé avant la désinstallation afin de libérer l'emplacement d'activation et de pouvoir réutiliser la licence ailleurs. Consultez Licences et activation Pro.