Fonctionnement et utilisation au quotidien
Une fois la passerelle appairée et la synchronisation activée, tout fonctionne tout seul. Cette page explique ce qui se passe réellement, afin que, lorsque quelque chose semble anormal, vous sachiez où regarder plutôt que de deviner.
Le moteur de synchronisation expliqué simplement
1. Une modification génère un événement
Chaque modification pertinente dans WHMCS déclenche un hook WHMCS : un client est ajouté ou modifié, un contact est créé, une facture est finalisée, un paiement arrive, une commande est passée, un service est provisionné ou suspendu, un ticket est ouvert ou reçoit une réponse.
Le hook n'effectue pas d'appel HTTP. Il écrit un petit événement dans une table outbox (mod_perfexbridge_outbox) et rend la main instantanément.
Si un hook WHMCS appelait Perfex directement, un serveur Perfex lent ou injoignable bloquerait une page d'administration WHMCS ou le paiement d'un client. Écrire dans une table locale prend une milliseconde et ne peut jamais échouer à cause du réseau de quelqu'un d'autre. Tout le reste se déroule en arrière-plan.
2. Le cron vide la file d'attente
À chaque exécution du cron système WHMCS, le répartiteur extrait de l'outbox un lot d'événements arrivés à échéance et les envoie un par un à votre installation Perfex en HTTPS via des requêtes POST.
Chaque requête transporte deux en-têtes en plus du corps JSON : un horodatage, et une signature HMAC-SHA256 calculée sur cet horodatage plus le corps exact de la requête, à l'aide de votre secret partagé. Perfex recalcule la signature avec sa propre copie du secret et rejette toute requête qui ne correspond pas, ou dont l'horodatage date de plus de 300 secondes.
Vous pouvez forcer un vidage immédiat à tout moment avec Run Sync Now, sur la page du module WHMCS.
3. Les échecs sont réessayés, puis mis au rebut
Un envoi en échec n'est pas perdu, et il n'est pas réessayé en boucle serrée. Il est reprogrammé avec un délai exponentiel : environ 60 secondes après le premier échec, puis 2 minutes, 4, 8, et ainsi de suite, plafonné à 6 heures entre deux tentatives.
Après 15 tentatives, ce qui représente environ 40 heures, la ligne est marquée dead. Les lignes en rebut ne sont jamais réessayées automatiquement ni purgées. Elles constituent votre tiroir de rebut : le compteur Dead events en haut de la page du module WHMCS vous indique combien il y en a, et la ligne du journal vous dit pourquoi.
La mise au rebut signifie que le même événement a échoué pendant près de deux jours pour la même raison. La cause est presque toujours l'une de ces quatre-là : une devise absente dans Perfex, un secret qui ne correspond pas, une offre Free qui bloque un événement Pro, ou Perfex hors ligne. Corrigez la cause et remettez le travail en file d'attente. Consultez Dépannage.
4. La mise en pause ne fait rien perdre
Décocher Enable Sync met en pause la livraison uniquement. Les hooks continuent d'écrire des événements dans l'outbox, rien n'est donc perdu pendant la pause. Réactivez la synchronisation et l'arriéré se vide à l'exécution suivante, ou immédiatement avec Run Sync Now.
5. La suppression d'écho évite les boucles infinies
La synchronisation bidirectionnelle crée un risque évident : WHMCS applique une modification venue de Perfex, cette écriture déclenche ses propres hooks WHMCS, et la modification repart aussitôt en sens inverse. Sans garde-fou, une seule modification ferait des allers-retours indéfiniment.
La passerelle empêche cela grâce à des protections superposées, appliquées des deux côtés :
- Un indicateur d'origine au sein de la requête, positionné pendant que la passerelle applique une modification entrante, afin que ses propres écritures ne soient pas prises pour de nouvelles modifications utilisateur.
- Une consultation de la table de correspondance des entités et des ID de réponses, afin qu'une réponse de ticket que la passerelle vient de créer soit reconnue au lieu d'être renvoyée comme nouvelle.
- Une comparaison de somme de contrôle, qui transforme un événement en opération neutre lorsque les données sont déjà identiques au dernier état synchronisé.
Chaque côté dispose de son propre indicateur d'origine, et la somme de contrôle sert de filet de sécurité si un indicateur venait à être contourné. Ces protections échouent délibérément « en mode ouvert » : si une protection ne peut pas trancher, un envoi supplémentaire inoffensif est préféré à une mise à jour silencieusement abandonnée.
6. Entretien courant
Les deux côtés exécutent une purge quotidienne autorégulée, au maximum une fois toutes les 24 heures :
- les lignes d'outbox livrées datant de plus de 7 jours sont supprimées ;
- les lignes de journal datant de plus de 90 jours sont supprimées ;
- les lignes pending et dead ne sont jamais purgées, car pending correspond à du travail non livré et dead constitue votre tiroir de rebut.
Ce qui se synchronise, et dans quel sens
De WHMCS vers Perfex CRM
| Données | Free | Pro | Ce qui arrive dans Perfex |
|---|---|---|---|
| 👥 Clients | ✅ | ✅ | Un client Perfex, ainsi qu'un contact principal portant le nom et l'adresse e-mail du client |
| 👤 Contacts | ✅ | ✅ | Des contacts supplémentaires rattachés au même client Perfex |
| 🗑️ Suppression de client | ✅ | ✅ | Le client Perfex est désactivé, et non détruit |
| 📄 Factures | ➖ | ✅ | Une facture Perfex avec ses lignes de détail, une ligne de taxe, des totaux identiques, le statut et le numéro de facture WHMCS dans la note d'administration |
| 💳 Paiements et transactions | ➖ | ✅ | Un enregistrement de paiement sur la facture répliquée, avec la passerelle de paiement et l'identifiant de transaction. Les doublons sont refusés |
| 💸 Remboursements | ➖ | ✅ | La copie Perfex est annulée et annotée |
| 🛒 Commandes | ➖ | ✅ | Un prospect Perfex par commande, ou une note sur le client, ou rien, selon Order Sync Target |
| 📦 Services | ➖ | ✅ | Des lignes sur l'onglet WHMCS du client : nom du produit, domaine, statut, cycle de facturation, montant et prochaine échéance |
| 🌐 Domaines | ➖ | ✅ | Des lignes sur le même onglet : bureau d'enregistrement, statut, expiration et prochaine échéance |
| 🎫 Tickets et réponses | ➖ | ✅ | Un ticket Perfex rattaché au client, dans le département correspondant, avec les réponses et le statut |
Avec l'offre Free, le statut et les notes d'un client circulent dans la charge utile mais ne sont pas écrits dans Perfex. Seule la suppression d'un client agit sur l'enregistrement Perfex, en désactivant le client.
De Perfex CRM vers WHMCS (Pro uniquement)
| Modification effectuée dans Perfex | Ce qui se passe dans WHMCS |
|---|---|
| Informations de société d'un client modifiées | La fiche client WHMCS est mise à jour, sous réserve de la politique de conflit |
| Contact principal modifié | Les champs d'identité du client WHMCS sont mis à jour, car le contact principal constitue l'identité du client |
| Contact non principal modifié | Le contact WHMCS correspondant est mis à jour |
| Un collaborateur répond à un ticket répliqué | La réponse apparaît sur le ticket WHMCS, attribuée à votre Ticket Reply Admin s'il est renseigné, sinon au nom du collaborateur Perfex |
| Statut d'un ticket modifié | Le statut du ticket WHMCS suit |
Supprimer un client ou un enregistrement dans Perfex ne supprime rien dans WHMCS. Les données de facturation sont préservées quoi qu'il arrive dans le CRM. C'est délibéré et non configurable.
Comportements connus à connaître avant de vous y fier
Ce sont des décisions documentées, pas des anomalies :
- Les tickets créés directement dans Perfex restent dans Perfex. Ils ne sont jamais créés dans WHMCS, car un ticket WHMCS a besoin d'un compte client et d'un département d'assistance dont un ticket créé côté CRM ne dispose pas nécessairement.
- Un changement de statut de ticket effectué via le formulaire complet de paramètres de ticket Perfex ne se propage pas. La liste déroulante de statut d'un ticket unique, les réponses, les changements de statut en masse et la clôture automatique se synchronisent tous correctement.
- Le temps imputé sur une tâche Perfex liée à un ticket n'est pas renvoyé vers WHMCS. Cette tâche existe pour les rapports de feuilles de temps natifs de Perfex.
- La périodicité des factures récurrentes n'est pas modélisée. Les factures WHMCS sont répliquées sous forme de simples factures Perfex ponctuelles.
- La fusion de deux clients WHMCS n'est pas gérée. Après une fusion, réassociez ou supprimez les lignes de correspondance du client absorbé.
- La réponse d'un collaborateur Perfex sur un ticket synchronisé peut générer deux e-mails au client, l'un depuis Perfex et l'autre depuis WHMCS. Si vos clients utilisent l'espace client WHMCS, désactivez le modèle d'e-mail Perfex
ticket-replysous Setup > Email Templates > Tickets.
Où se trouvent les journaux
C'est la section qui fait gagner le plus de temps. Les utilisateurs ont l'habitude de chercher au mauvais endroit.
Côté WHMCS : la page du module
Allez dans Addons > Perfex CRM Bridge et faites défiler jusqu'à Recent activity.
La passerelle n'écrit pas dans le WHMCS Activity Log, sous Utilities > Logs. Elle dispose de sa propre table, affichée dans le panneau Recent activity de la page du module, et c'est le seul endroit à consulter du côté WHMCS.
Le tableau affiche les 50 derniers événements, avec ces colonnes :
| Colonne | Signification |
|---|---|
| Time | Date et heure d'écriture de la ligne |
| Dir | out pour WHMCS vers Perfex, in pour Perfex vers WHMCS |
| Event | Par exemple client.upsert, invoice.upsert, cron.drain |
| Entity | client, contact, invoice, ticket, etc. |
| WHMCS ID | L'ID WHMCS de l'enregistrement |
| Status | ok en vert ou error en rouge |
| Message | Le résultat, ou le texte exact de l'erreur |
Juste au-dessus, la ligne d'en-tête affiche les compteurs Queue pending et Dead events. Ces deux nombres résument l'état de santé : pending doit retomber à zéro en un ou deux cycles de cron, et dead doit rester à zéro.
Côté Perfex : deux panneaux sur la page de paramètres
Allez dans Setup > WHMCS Bridge.
Recent inbound events liste ce que WHMCS a envoyé à cette installation Perfex, avec le type d'événement, l'ID WHMCS, l'ID Perfex auquel il a été associé, un badge de statut et un message. C'est ici qu'une requête rejetée apparaît sous forme de ligne auth.rejected, ce qui signale un problème de signature ou d'horodatage, presque toujours un secret qui ne correspond pas. Les lignes rejetées sont plafonnées à 10 par minute, afin qu'un afflux ne puisse pas saturer votre disque.
Outbound queue liste les modifications côté Perfex en attente d'envoi vers WHMCS, avec :
- les compteurs pending et dead dans l'en-tête du panneau ;
- une ligne par modification en file d'attente, indiquant l'événement, l'entité, le statut, le nombre de tentatives, l'heure de la prochaine tentative et la dernière erreur ;
- une explication en langage clair plutôt qu'une erreur brute lorsque la cause est connue. Une erreur 403 émise par un WHMCS sans licence s'affiche sous la forme « Two-way sync requires Pro on the WHMCS side » accompagnée d'un lien de mise à niveau, et non d'un vidage JSON.
Seules les 20 dernières lignes sont affichées. Les lignes livrées s'effacent d'elles-mêmes au bout de 7 jours ; les lignes pending et dead sont conservées.
Quel journal répond à quelle question
| Question | Où regarder |
|---|---|
| 📤 Ma modification WHMCS a-t-elle quitté WHMCS ? | WHMCS : Recent activity, direction out |
| 📥 Perfex l'a-t-il acceptée ? | Perfex : Recent inbound events |
| 🔑 Mon secret partagé est-il incorrect ? | Perfex : les lignes auth.rejected dans Recent inbound events |
| 🔁 Ma modification Perfex est-elle parvenue à WHMCS ? | Perfex : Outbound queue, puis WHMCS : Recent activity, direction in |
| ⏰ Le cron s'exécute-t-il ? | WHMCS : la ligne Cron delivering de la checklist |
| 🔇 Pourquoi la synchronisation bidirectionnelle est-elle muette ? | Perfex : le panneau WHMCS plan. S'il indique Free, vous avez votre réponse |
L'assistant de reprise (Pro)
La synchronisation en direct ne traite jamais que la nouvelle activité. Si vous installez la passerelle sur une installation WHMCS déjà établie, vos clients et factures existants ne se trouvent pas dans Perfex tant que vous ne les avez pas repris.
L'assistant de reprise se situe sur la page du module WHMCS, sous le formulaire de paramètres. Il met vos enregistrements existants en file d'attente dans la même outbox que celle utilisée par la synchronisation en direct : ils héritent donc de la même signature, des mêmes nouvelles tentatives, du même délai croissant et de la même mise au rebut.
Périmètres
Cochez un ou plusieurs éléments :
| Périmètre | Ce qui est mis en file d'attente |
|---|---|
| Clients + contacts | Tous les clients de la plage. Les contacts suivent automatiquement leur client |
| Invoices | Toutes les factures de la plage |
| Services + domains | Tous les services et domaines de la plage, ce qui alimente l'onglet WHMCS de Perfex |
Les tickets historiques ne se synchronisent pas. Seule la nouvelle activité de tickets circule une fois la passerelle en service. C'est une limitation documentée, et non un problème de configuration.
Modes
| Mode | Comportement |
|---|---|
| All history | Tous les enregistrements des périmètres choisis |
| Date range | Uniquement les enregistrements créés dans une fenêtre définie par une date de début et une date de fin au format YYYY-MM-DD. Une plage invalide, par exemple une date de début postérieure à la date de fin, est rejetée avec un message clair et rien n'est mis en file d'attente |
| Only new (not yet synced) | Ignore les enregistrements déjà associés. C'est le mode à utiliser pour les exécutions répétées |
La limite de 500 entités et comment reprendre
Chaque exécution met au maximum 500 entités en file d'attente, afin qu'une reprise sur une grande installation ne puisse ni saturer la file, ni bloquer votre cron.
Lorsque la limite est atteinte, l'assistant vous en informe. La procédure est la suivante :
- Cliquez sur Queue Backfill. Une bannière d'information indique combien d'enregistrements étaient prévus, combien ont été mis en file d'attente, combien ont échoué, et si l'exécution a été tronquée.
- Observez le compteur Queue pending en haut de la page se vider, soit par le cron, soit avec Run Sync Now.
- Relancez l'assistant en mode Only new (not yet synced).
- Répétez jusqu'à ce qu'une exécution ne prévoie plus rien de nouveau.
Il n'y a aucun risque de doublon. Les enregistrements déjà associés sont ignorés, et un événement dont les données correspondent déjà au côté Perfex reçoit une réponse d'opération neutre.
Deux règles d'ordonnancement qui vous feront gagner du temps
Un enregistrement enfant dont le client parent n'est pas encore dans Perfex reçoit la réponse « not mapped, will retry » et reste en file d'attente jusqu'à l'arrivée du parent. En général, l'ordonnancement de la file suffit à régler la question. Mais si vous reprenez uniquement des services ou des factures sur une installation dont les clients n'ont jamais été synchronisés, ces événements sont réessayés pendant environ 40 heures avant d'être mis au rebut.
Cochez donc Clients + contacts dans la même exécution, ou reprenez d'abord les clients.
Une facture libellée dans une devise que Perfex ne connaît pas est rejetée et réessayée, puis mise au rebut après environ 40 heures. Avant de reprendre vos factures, ajoutez dans Perfex toutes les devises utilisées par vos clients WHMCS, sous Setup > Finance > Currencies, en utilisant le code ISO exact.
Les factures historiques déjà payées
Les factures reprises qui étaient déjà payées dans WHMCS sont soldées dans Perfex par un enregistrement de paiement synthétique, afin qu'elles apparaissent comme Paid plutôt qu'en retard. Relancer une reprise ne crée pas de paiements en double.
Exploitation au quotidien
Une fois la configuration en place, il y a très peu à faire. Un rapide coup d'œil hebdomadaire à la page du module WHMCS suffit :
| Ce qu'il faut regarder | État sain |
|---|---|
| Setup checklist | Tout au vert, avec du gris sur la ligne de licence si vous utilisez l'offre Free |
| Queue pending | Faible, et en diminution entre deux exécutions du cron |
| Dead events | 0 |
| Recent activity | Majoritairement des lignes ok |
| Outbound queue de Perfex | 0 pending, 0 dead, sur les installations Pro bidirectionnelles |
Si l'un de ces points est anormal, Dépannage en donne la cause et la solution.