Configuration

Tout ce qui suit part du principe que les deux modules sont installés et activés, et que vous pouvez atteindre Addons > Perfex CRM Bridge dans WHMCS ainsi que Setup > WHMCS Bridge dans Perfex CRM. Si l'un des deux est absent, revenez à l'Installation. Dans WHMCS, la cause habituelle est la case Access Control non cochée.

Comment les deux côtés s'authentifient

Les deux points de terminaison authentifient chaque requête à l'aide d'une signature HMAC-SHA256 dérivée d'un secret partagé.

En clair : l'expéditeur signe le corps de la requête avec le secret et l'horodate. Le destinataire recalcule la signature avec sa propre copie du secret et rejette toute requête dont la signature ne correspond pas, ou dont l'horodatage date de plus de 300 secondes. Cette fenêtre temporelle est ce qui empêche quelqu'un de rejouer plus tard une requête interceptée.

Conséquence : le secret doit être identique octet pour octet des deux côtés, faute de quoi chaque requête échoue avec une erreur 401. Chaque point de terminaison refuse également tout trafic tant que son propre secret est vide : une passerelle à moitié configurée est donc fermée plutôt qu'ouverte.

Les deux côtés suppriment les espaces en début et en fin de chaîne avant utilisation : un espace ou un saut de ligne parasite récupéré lors d'un copier-coller ne vous posera donc pas de problème. Tout ce qui se trouve entre les deux doit correspondre exactement.

Traitez le secret partagé comme un identifiant de connexion

Le secret partagé donne un accès en écriture aux clients et contacts Perfex, et, avec une licence Pro, aux factures, paiements, commandes et tickets des deux côtés. Renouvelez-le immédiatement des deux côtés si l'une des bases de données, ou l'une de leurs sauvegardes, venait à être exposée. Les secrets sont stockés en clair dans tbladdonmodules (WHMCS) et tbloptions (Perfex), ce qui est la pratique standard dans les deux écosystèmes : toute personne ayant accès à la base de données dispose donc du secret.

Appairage : la méthode rapide (recommandée)

Vous n'avez pas besoin de recopier des paramètres d'un côté à l'autre. Perfex génère un unique Connection code qui contient à la fois l'URL Perfex et le secret partagé, et WHMCS le consomme en un seul collage.

Étape 1 : générer le secret dans Perfex

1. Dans Perfex CRM, allez dans Setup > WHMCS Bridge.
2. À côté de Shared Secret, cliquez sur Generate. Le champ se remplit d'un secret aléatoire robuste de 64 caractères et devient visible pour que vous puissiez voir ce que vous vous apprêtez à enregistrer. Le bouton en forme d'œil permet de masquer à nouveau la valeur.
3. Cliquez sur Save.

Étape 2 : copier le Connection code

La page se recharge et affiche désormais un champ Connection code en lecture seule. Sa valeur est une chaîne unique commençant par PBC1..

Cliquez sur Copy. Le bouton affiche brièvement « Copied! » lorsque le code est dans votre presse-papiers.

Le Connection code est un mot de passe

Le code est constitué de PBC1. suivi d'un JSON encodé en base64url contenant votre URL Perfex et votre secret partagé. Il s'agit d'un encodage, pas d'un chiffrement. Quiconque obtient ce code peut dialoguer avec vos points de terminaison. Ne le collez jamais dans un ticket public, un canal de discussion, une capture d'écran ou une demande d'assistance.

Si aucun Connection code n'apparaît

Le code ne s'affiche que lorsque deux conditions sont réunies : votre installation Perfex est servie en HTTPS, et le secret partagé enregistré compte au moins 32 caractères. Avoir cliqué sur Generate sans cliquer sur Save en est la cause habituelle. La page vous indique quelle condition n'est pas remplie :

• « not served over HTTPS » - l'appairage nécessite HTTPS. Utilisez la configuration manuelle à la place, ou corrigez le certificat.
• « shorter than 32 characters » - cliquez sur Generate, puis sur Save, et le code apparaît.

Étape 3 : le coller dans WHMCS

1. Dans WHMCS, ouvrez Addons > Perfex CRM Bridge.
2. Repérez l'encadré vert Quick setup en haut de la page.
3. Collez le code dans le champ.
4. Cliquez sur Connect.

Ce que fait réellement Connect

En une seule étape, et dans cet ordre :

1. Il décode le code et le valide rigoureusement : le préfixe PBC1., un base64url strict, un objet JSON bien formé, une URL commençant par https:// et passant la validation d'URL, et un secret d'au moins 32 caractères.
2. Il envoie un ping signé à votre installation Perfex en utilisant l'URL et le secret décodés, et attend le pong.
3. Ce n'est que si ce ping aboutit qu'il enregistre l'URL Perfex CRM et le Shared Secret du côté WHMCS.
4. Lors du premier appairage uniquement, le ping transporte également l'URL de base de votre installation WHMCS, de sorte que le champ WHMCS URL du côté Perfex est renseigné pour vous. Cela ne se produit que si votre WHMCS est servi en HTTPS, et n'écrase jamais une valeur déjà définie.
5. Il enregistre la vérification réussie, ce qui fait passer au vert la ligne Connection verified de la checklist dès le même chargement de page.

En cas de succès, une bannière verte indique l'URL Perfex avec laquelle l'appairage a été réalisé. En cas d'échec, une bannière rouge explique précisément ce qui n'a pas fonctionné, et rien n'est enregistré. Un code dont la vérification échoue ne peut jamais écraser une configuration qui fonctionne.

Réappairer plus tard

Une fois WHMCS configuré, l'encadré Quick setup devient un discret formulaire Re-pair. Collez-y un nouveau code chaque fois que vous renouvelez le secret ou que vous déplacez Perfex vers un nouveau domaine. La même règle s'applique : un code dont la vérification échoue ne change rien.

Renouvelez le secret, puis réappairez, dans cet ordre

Si vous cliquez sur Generate puis sur Save du côté Perfex, toutes les requêtes WHMCS existantes commencent instantanément à échouer avec une erreur HTTP 401 jusqu'à ce que vous colliez le nouveau code dans WHMCS. Enchaînez les deux étapes. Un ancien code copié avant le renouvellement sera rejeté, et la bannière vous indiquera que Perfex a répondu 401.

Appairage : la solution de repli manuelle

Le Connection code est une commodité, pas une formule magique. Tout ce qu'il fait peut être fait à la main, et vous aurez besoin de cette méthode si votre installation Perfex n'est pas encore en HTTPS, ou si vos procédures interdisent de coller un identifiant combiné.

1. Générez un secret aléatoire robuste d'au moins 32 caractères. Utilisez le bouton Generate de la page de paramètres Perfex, ou votre propre outil, par exemple openssl rand -hex 32.
2. Dans Perfex, sur Setup > WHMCS Bridge, collez-le dans Shared Secret et cliquez sur Save.
3. Dans WHMCS, ouvrez Addons > Perfex CRM Bridge, faites défiler jusqu'à Settings > Connection, puis :
   • renseignez Perfex CRM URL avec l'URL de base de votre installation Perfex, par exemple https://crm.example.com, en HTTPS et sans chemin final ;
   • collez le même secret dans Shared Secret.
4. Cliquez sur Save Settings.
5. Cliquez sur Test Connection en haut de la page. Vous devez obtenir la bannière verte « Connection OK ».
6. Pour la synchronisation bidirectionnelle Pro, renseignez également WHMCS URL sur la page de paramètres Perfex. L'appairage l'aurait fait à votre place.

Les paramètres WHMCS, section par section

Tous les paramètres se trouvent sur la page du module

Ouvrez Addons > Perfex CRM Bridge et faites défiler jusqu'à Settings. Ne cherchez pas sur l'écran Configure de WHMCS, sous System Settings > Addon Modules ; cet écran ne conserve qu'Access Control, rendu par le cœur de WHMCS et impossible à déplacer.

Cliquez sur Save Settings pour appliquer. Le formulaire fonctionne en tout ou rien : une saisie invalide, par exemple une URL non HTTPS, fait rejeter l'ensemble de la soumission et ne modifie rien.

Les deux champs de secret n'affichent jamais la valeur enregistrée

Shared Secret et Pro License Key sont toujours rendus vides, afin qu'un identifiant stocké ne se retrouve jamais dans le code source de la page pour tous les administrateurs pouvant ouvrir le module. Laissez un champ vide pour conserver sa valeur actuelle. Saisissez-y quelque chose pour remplacer cette valeur. Pour supprimer entièrement une clé Pro, cochez Remove the stored key.

Connection

Paramètre	Rôle	Valeur recommandée
Perfex CRM URL	L'URL de base de votre installation Perfex, par exemple https://crm.example.com. Doit être en HTTPS : la passerelle refuse d'émettre en HTTP simple.	Définie automatiquement par l'appairage
Shared Secret	Le secret HMAC. Doit correspondre au secret configuré dans Perfex sous Setup > WHMCS Bridge. Laissez vide pour conserver la valeur enregistrée.	Définie automatiquement par l'appairage

Sync behaviour

Paramètre	Rôle	Valeur recommandée
Enable Sync	L'interrupteur principal. Décochez-le pour suspendre toute livraison sortante. Les événements continuent d'être mis en file d'attente pendant la pause, rien n'est donc perdu ; ils sont livrés au premier passage suivant la réactivation.	Activé, une fois la configuration terminée
Order Sync Target (Pro)	Ce que devient une commande WHMCS dans Perfex. lead crée un prospect Perfex par commande. note ajoute une note sur le client Perfex à la place. off ne synchronise pas les commandes du tout.	lead
Two-Way Conflict Policy (Pro)	Quel côté l'emporte lorsque les deux systèmes ont modifié le même client ou contact depuis la dernière synchronisation. Voir ci-dessous.	newest_wins

Les options de politique de conflit, en une ligne chacune :

• newest_wins (par défaut) - compare l'heure de l'événement Perfex entrant à celle de la dernière synchronisation : la modification la plus récente l'emporte.
• whmcs_wins - conserve les données WHMCS et écarte la modification Perfex conflictuelle.
• perfex_wins - applique la modification Perfex par-dessus les données WHMCS.

La politique de conflit ne s'applique qu'en cas de conflit réel

Elle s'applique uniquement lorsque les deux côtés ont modifié le même enregistrement depuis la dernière synchronisation réussie. Une modification ordinaire d'un seul côté, l'autre côté restant inchangé, est toujours appliquée. Vous ne choisissez pas quel système « gagne » de manière générale, seulement comment départager une égalité.

Une remarque sur newest_wins et les horloges serveur

« Le plus récent » compare l'horodatage du serveur émetteur à l'heure de dernière synchronisation du serveur destinataire : les horloges des deux hôtes comptent donc. Maintenez les deux serveurs synchronisés par NTP. Si la dérive d'horloge entre votre hôte WHMCS et votre hôte Perfex échappe à votre contrôle, préférez whmcs_wins ou perfex_wins, qui sont déterministes.

Tickets

Paramètre	Rôle	Valeur recommandée
Ticket Reply Admin (Pro)	Le nom d'utilisateur de l'administrateur WHMCS utilisé lorsqu'une réponse d'un collaborateur Perfex est synchronisée vers un ticket WHMCS. Laissez ce champ vide pour attribuer plutôt la réponse au nom du collaborateur Perfex, publiée comme réponse non administrative.	Vide

Licence Pro

Paramètre	Rôle	Valeur recommandée
Pro License Key	Laissez vide pour l'offre Free. Collez ici votre clé Pro pour débloquer les fonctionnalités Pro. Les clés commencent par sk_. L'enregistrement d'une clé modifiée déclenche une vérification en ligne immédiate.	Vide (Free)
Remove the stored key	Une case à cocher qui n'apparaît que lorsqu'une clé est enregistrée. La cocher puis enregistrer fait revenir l'installation à Free et libère l'emplacement d'activation de ce site, permettant d'utiliser la licence ailleurs.	Décochée
Check licence now (bouton, en haut de page)	Force une nouvelle vérification immédiate de la clé déjà enregistrée, en ignorant la limitation à une vérification par jour.	-
Upgrade to Pro / Buy a Pro licence (liens)	Ouvrent le paiement. Sur une installation non Pro, ils apparaissent à côté du champ de clé, sur la ligne de licence de la checklist et dans les encarts de présentation Pro.	-

Tous les détails figurent dans Licences et activation Pro.

Les paramètres Pro peuvent être configurés en toute sécurité avec l'offre Free

Order Sync Target, Two-Way Conflict Policy et Ticket Reply Admin s'enregistrent parfaitement sur une installation Free. Ils n'ont simplement aucun effet tant qu'une licence valide n'est pas active, et la page le précise sous chaque champ. Configurez-les à l'avance si vous le souhaitez.

Les paramètres Perfex CRM, champ par champ

Ouvrez Setup > WHMCS Bridge dans l'administration Perfex, puis cliquez sur Save.

Connection

Champ	Rôle	Valeur par défaut / repli
Shared Secret	Doit correspondre au Shared Secret de WHMCS. Utilisez Generate pour en obtenir un robuste, puis Save. Le bouton en forme d'œil l'affiche ou le masque. Le point de terminaison rejette tout trafic tant que ce champ est vide.	Vide, point de terminaison fermé
Connection code	En lecture seule. Apparaît dès lors que le secret enregistré compte au moins 32 caractères et que Perfex est en HTTPS. Copiez-le dans l'encadré Quick setup de WHMCS.	Affiché automatiquement
WHMCS URL	L'URL de base de l'installation WHMCS exécutant le module complémentaire. Nécessaire uniquement pour le trafic Perfex vers WHMCS, qui est une fonctionnalité Pro. Doit commencer par https://, sans quoi elle n'est pas enregistrée.	Renseignée automatiquement au premier appairage, jamais écrasée ensuite

Synchronisation des tickets (Pro)

Champ	Rôle	Valeur par défaut / repli
Department mapping (WHMCS to Perfex)	Fait correspondre chaque département de tickets WHMCS à un département Perfex. S'affiche sous forme d'une liste déroulante par département WHMCS lorsque l'annuaire peut être récupéré, ou sous forme de zone de texte manuelle dans le cas contraire.	Vide, aucune correspondance définie
Default department for unmapped WHMCS tickets	Le département Perfex utilisé pour tout ticket WHMCS dont le département n'est pas présent dans la table de correspondance.	« Lowest department id (automatic) »
Staff author for synced WHMCS staff replies	Le collaborateur Perfex crédité comme auteur des réponses des collaborateurs WHMCS répliquées dans Perfex.	« First active admin (automatic) »
Create a Perfex task per synced ticket	Lorsque cette case est cochée, chaque ticket synchronisé reçoit une tâche Perfex associée, afin que vos collaborateurs puissent y imputer du temps via les feuilles de temps natives de Perfex.	Désactivé

Comment s'affiche la correspondance des départements

Le fonctionnement normal repose sur des listes déroulantes. Au chargement de la page de paramètres, celle-ci récupère l'annuaire de vos départements d'assistance WHMCS via la passerelle signée et affiche une ligne par département WHMCS, avec une liste déroulante de vos départements Perfex. Choisissez une cible pour chaque ligne, ou laissez-la sur - not mapped -, puis cliquez sur Save.

Cette récupération nécessite une connexion opérationnelle et un WHMCS sous licence Pro, car l'annuaire des départements est soumis à la même restriction de licence que la synchronisation des tickets. Lorsqu'elle ne peut pas aboutir, la page bascule automatiquement vers une zone de texte manuelle et vous indique pourquoi :

Ce que vous voyez	Ce que cela signifie
Des listes déroulantes, une par département WHMCS	Tout fonctionne
Une zone de texte, « Couldn't fetch WHMCS departments (needs Pro + working connection) »	La passerelle n'est pas encore configurée, WHMCS est injoignable depuis le serveur Perfex, ou l'installation WHMCS est sur l'offre Free
Une zone de texte, « Connection OK, but WHMCS has no support departments yet »	La récupération a fonctionné. Créez des départements dans WHMCS sous Support > Support Departments, puis rechargez cette page

La récupération est limitée à quelques secondes : un WHMCS injoignable ralentit donc légèrement la page de paramètres, mais ne la bloque jamais.

Le format manuel est d'une correspondance par ligne, l'ID du département WHMCS à gauche et l'ID du département Perfex à droite :

1=2
2=5
3=5

Lorsque les listes déroulantes sont affichées, le lien Advanced: edit the mapping manually ouvre cette même zone de texte. Tant que cet éditeur manuel est ouvert, c'est son contenu qui est enregistré, en remplacement des sélections des listes déroulantes.

L'ordre de résolution du département d'un ticket entrant est le suivant :

1. Une correspondance exacte dans la table de correspondance.
2. Sinon, le Default department configuré.
3. Sinon, l'ID de département Perfex le plus bas, choisi automatiquement.

Une erreur de saisie sur une ligne de correspondance retombe proprement sur la valeur de repli. Cela n'empêche ni l'enregistrement, ni la synchronisation.

Le temps imputé sur la tâche liée au ticket reste dans Perfex

La tâche Perfex optionnelle existe pour que vos collaborateurs puissent utiliser les feuilles de temps natives de Perfex sur un ticket. Ces saisies de temps ne sont pas synchronisées vers WHMCS, et la tâche n'est pas clôturée automatiquement lorsque le ticket est clôturé.

Les panneaux de la même page

La colonne de droite de Setup > WHMCS Bridge comporte trois panneaux en lecture seule :

• WHMCS plan - l'offre signalée en dernier lieu par le côté WHMCS (Pro, Free ou Unknown), la date de la dernière vérification de licence, et un bouton Upgrade to Pro lorsqu'il y a quelque chose à acheter.
• Outbound queue - les modifications issues de Perfex en attente d'envoi vers WHMCS, avec les compteurs pending et dead, le nombre de tentatives, l'heure de la prochaine tentative et la dernière erreur par ligne.
• Recent inbound events - ce que WHMCS a envoyé à cette installation Perfex, avec le statut et le message.

Ce sont vos outils de diagnostic côté Perfex. Consultez Fonctionnement et utilisation au quotidien.

La setup checklist, ligne par ligne

La page du module WHMCS s'ouvre sur une Setup checklist de six lignes. Chaque ligne porte une coche verte, un avertissement orange, une croix rouge ou un tiret gris, accompagné d'une indication d'une ligne. Tout au vert, avec du gris sur la ligne de licence si vous êtes sur Free, signifie que la passerelle est en bonne santé.

Ligne	Vert signifie	Toute autre couleur signifie
Module tables present	Les tables outbox, map et log existent toutes.	🔴 une table est manquante. Désactivez puis réactivez le module dans System Settings > Addon Modules pour la recréer.
Connection configured	L'URL Perfex et le secret partagé sont tous deux renseignés.	🔴 pas encore renseignés. Collez un Connection code dans Quick setup, ou remplissez les deux champs sous Settings > Connection.
Connection verified	Un ping signé a reçu un pong en retour, et la ligne indique depuis combien de temps.	🔴 la dernière vérification a échoué, et la ligne affiche l'erreur. Corrigez-la, puis cliquez sur Test Connection. ⚪ jamais vérifié, ou dernière vérification datant de plus de 24 heures. Cliquez sur Test Connection pour l'actualiser.
Sync enabled	La livraison sortante est active.	🔴 la synchronisation est en pause. Les événements continuent d'être mis en file d'attente mais ne sont pas livrés. Cochez Enable Sync sous Settings > Sync behaviour et enregistrez.
Cron delivering	Le cron système WHMCS a effectué un véritable travail de passerelle récemment, et la ligne indique à quel point c'est récent.	🟠 aucune activité cron depuis un moment. Vérifiez que le cron système WHMCS s'exécute. 🔴 aucune activité cron n'a jamais été enregistrée. Sur une installation toute neuve, c'est normal jusqu'à la première livraison ; si cela persiste, votre cron ne s'exécute pas.
License / plan	Pro est actif.	⚪ aucune clé de licence, c'est-à-dire l'offre Free, une manière parfaitement prise en charge d'utiliser ce module. 🔴 une clé est renseignée mais ne se valide pas. Vérifiez la clé, puis cliquez sur Check licence now.

La ligne « Cron delivering » est délibérément difficile à tromper

Seule une véritable exécution du cron système WHMCS fait passer cette ligne au vert. Run Sync Now livre vos événements en attente et prouve que la livraison fonctionne, mais ne touche pas à cette ligne. C'est précisément l'objectif : cette ligne répond à la question « est-ce que cela continuera de fonctionner quand personne ne regarde ? », et un clic sur un bouton ne peut pas répondre à cette question.

La ligne suit le travail réel de la passerelle : vidage de la file d'attente, purge des journaux et passes de réconciliation. Une installation longtemps inactive mais parfaitement saine peut donc rester en orange sans qu'il y ait quoi que ce soit à corriger, simplement parce qu'il n'y avait rien à faire.

Connect (appairage) et Test Connection actualisent tous deux la ligne Connection verified.

Et ensuite ?

• Vérifiez la chaîne de bout en bout : Installation, étape 5.
• Débloquez la synchronisation bidirectionnelle, les factures et les tickets : Licences et activation Pro.
• Comprenez ce qui est synchronisé et où se trouvent les journaux : Fonctionnement et utilisation au quotidien.