Dépannage

Parcourez cette page dans l'ordre. Les trois premières sections couvrent l'écrasante majorité des demandes d'assistance.

Avant toute chose, ouvrez Addons > Perfex CRM Bridge dans WHMCS et lisez la Setup checklist. Elle est conçue pour pointer directement le problème, et chaque ligne est expliquée dans Configuration.

Référence rapide

Symptôme	Cause la plus probable	Solution
Module absent du menu Addons de WHMCS	Aucun rôle d'administration coché sous Access Control	Cochez Access Control
Tous les envois échouent immédiatement	L'URL Perfex commence par http://	Utilisez HTTPS
Des lignes auth.rejected dans le journal entrant Perfex	Le secret partagé ne correspond pas	Réappairez
« Two-way sync requires Pro » dans la file sortante Perfex	Le côté WHMCS est sur l'offre Free	Activez Pro
Les événements s'accumulent mais rien n'est livré	La synchronisation est en pause, ou le cron WHMCS ne s'exécute pas	Vérifiez le cron
Une facture n'arrive jamais et se réessaie indéfiniment	La devise de la facture n'existe pas dans Perfex	Ajoutez la devise
La licence refuse de s'activer	Clé manquante, ou absence de connectivité vers le service de licences	Lisez la couleur de la bannière
Aucun Connection code sur la page Perfex	Perfex n'est pas en HTTPS, ou le secret enregistré est trop court	Generate puis Save
La correspondance des départements affiche une zone de texte au lieu de listes déroulantes	Offre Free, ou WHMCS injoignable depuis Perfex	Solutions de repli de la correspondance
Des lignes bloquées en état dead	15 tentatives échouées pour la même raison	Rejouez les lignes en rebut

Le module n'apparaît pas dans le menu Addons

Symptôme. Vous avez activé Perfex CRM Bridge sous System Settings > Addon Modules, WHMCS a confirmé l'activation, et le module est introuvable dans le menu Addons de gauche.

Cause. Aucun rôle d'administration ne s'est vu accorder l'accès. WHMCS masque entièrement un module complémentaire à tout rôle non coché : le module est donc installé et pleinement fonctionnel, mais aucun lien n'y mène dans l'administration. C'est de très loin le signalement « il ne s'est pas installé » le plus fréquent.

Solution.

1. Allez dans System Settings > Addon Modules.
2. Cliquez sur Configure à côté de Perfex CRM Bridge.
3. Sous Access Control, cochez Full Administrator, ainsi que tout autre rôle censé utiliser le module.
4. Cliquez sur Save Changes.
5. Actualisez l'administration. Le module apparaît désormais sous Addons.

Rien d'autre ne se trouve sur cet écran Configure

Tous les véritables paramètres sont sur la page du module, dans Addons > Perfex CRM Bridge. L'écran Configure ne conserve qu'Access Control, car le cœur de WHMCS le rend et il ne peut pas être déplacé.

Tous les envois échouent immédiatement, ou l'URL est rejetée

Symptôme. Les événements sont mis en file d'attente et échouent instantanément. Le journal Recent activity se remplit d'erreurs de connexion. Ou bien le champ Perfex CRM URL refuse purement et simplement d'être enregistré.

Cause. HTTPS est requis par conception. Le transport HTTP est verrouillé sur le protocole https et vérifie le certificat TLS. Une URL en http:// fait échouer chaque envoi, et le champ WHMCS URL côté Perfex refuse de même l'enregistrement s'il ne commence pas par https://.

Solution.

1. Renseignez Perfex CRM URL avec une adresse en https:// du côté WHMCS.
2. Renseignez WHMCS URL avec une adresse en https:// du côté Perfex.
3. Assurez-vous que les deux certificats sont réellement validés depuis l'autre serveur, et pas seulement dans votre navigateur. Un certificat auto-signé ne fonctionne que si le serveur appelant lui fait confiance.
4. Cliquez sur Test Connection sur la page du module WHMCS.

Il n'existe aucun réglage pour désactiver la vérification HTTPS

C'est délibéré. Votre secret partagé et les données de vos clients transitent par ce canal. Si un certificat n'est pas validé, corrigez le certificat.

Des lignes auth.rejected dans le journal Perfex

Symptôme. WHMCS signale des erreurs HTTP 401. Dans Perfex, Setup > WHMCS Bridge > Recent inbound events affiche des lignes auth.rejected en rouge.

Cause. Le secret partagé ne correspond pas entre les deux côtés, ou l'horodatage de la requête est hors de la fenêtre de 300 secondes. En pratique, il s'agit presque toujours du secret : quelqu'un l'a régénéré d'un côté sans jamais réappairer l'autre.

Solution rapide.

1. Dans Perfex, Setup > WHMCS Bridge, copiez le Connection code actuel.
2. Dans WHMCS, Addons > Perfex CRM Bridge, collez-le dans l'encadré Re-pair et cliquez sur Connect.
3. Cliquez sur Test Connection. Vous devez obtenir la bannière verte « Connection OK ».
4. Cliquez sur Run Sync Now. Les événements en file d'attente qui échouaient sont désormais livrés.

Solution manuelle. Recollez exactement le même secret dans les deux champs Shared Secret et enregistrez des deux côtés. Les espaces en début et en fin de chaîne sont supprimés automatiquement, mais tout ce qui se trouve entre les deux doit correspondre caractère pour caractère.

S'il ne s'agit pas du secret. Vérifiez les horloges des deux serveurs. Un écart de plus de 300 secondes entre elles fait rejeter chaque requête comme un rejeu. Synchronisez les deux hôtes par NTP.

Les lignes rejetées sont limitées en débit

Perfex enregistre au maximum 10 lignes auth.rejected par minute, afin qu'un émetteur mal configuré ne puisse pas saturer votre disque. Si vous en voyez exactement 10 sur une minute, considérez qu'il y en a eu davantage.

« Two-way sync requires Pro » dans la file sortante Perfex

Symptôme. Vous modifiez un client dans Perfex. Le panneau Outbound queue de Setup > WHMCS Bridge affiche la ligne avec le message « Two-way sync requires Pro on the WHMCS side. » et un lien Upgrade to Pro. Les tentatives s'accumulent, et la ligne finit par passer en rebut.

Cause. La synchronisation bidirectionnelle est une fonctionnalité Pro, et la licence réside du côté WHMCS. Votre installation WHMCS est sur l'offre Free : son point de terminaison entrant répond donc 403 à toute modification issue de Perfex. Le compagnon Perfex se comporte correctement en mettant en file d'attente et en réessayant.

Solution. Activez une licence Pro du côté WHMCS. Consultez Licences et activation Pro. Une fois Pro actif, WHMCS transmet immédiatement le nouvel état de l'offre à Perfex, l'invitation à la mise à niveau disparaît, et les lignes en attente sont livrées à la prochaine exécution du cron Perfex.

Les lignes déjà passées en état dead pendant que vous étiez sur Free ne seront pas réessayées d'elles-mêmes. Consultez Des lignes bloquées en état dead.

Consultez d'abord le panneau d'offre

Le panneau WHMCS plan se trouve juste au-dessus de la file sortante sur la page de paramètres Perfex, précisément pour cette raison. S'il indique Free, vous avez votre réponse sans lire une seule ligne de la file.

Rien ne se synchronise du tout

Symptôme. Les événements apparaissent dans la file, Queue pending augmente, et rien n'arrive jamais dans Perfex. Aucune erreur, simplement le silence.

Il y a deux causes, et la checklist permet de les distinguer.

Cause A : la synchronisation est en pause

La ligne Sync enabled de la checklist est rouge.

Solution. Sur la page du module WHMCS, sous Settings > Sync behaviour, cochez Enable Sync et cliquez sur Save Settings. Rien n'a été perdu pendant la pause ; les événements ont continué à être mis en file d'attente et vont maintenant être livrés.

Cause B : le cron système WHMCS ne s'exécute pas

La ligne Cron delivering de la checklist est rouge ou orange.

Solution.

1. Prouvez que la passerelle elle-même fonctionne en cliquant sur Run Sync Now. Si votre file se vide, la livraison est opérationnelle et le problème vient bien du cron.
2. Vérifiez l'état du cron propre à WHMCS sous Utilities > System > System Health Status. WHMCS indique la date de la dernière exécution du cron système.
3. Si le cron ne s'est pas exécuté récemment, corrigez-le au niveau du serveur. C'est dans le gestionnaire de tâches planifiées de votre panneau d'hébergement, ou dans le crontab de votre serveur, que se trouve la commande cron de WHMCS. La documentation officielle de WHMCS fournit la commande exacte correspondant à votre version.
4. Une fois le cron réactivé, la ligne Cron delivering passe au vert au chargement de page suivant un véritable travail de la passerelle.

Run Sync Now ne peut pas faire passer la ligne du cron au vert

Cette ligne suit délibérément la seule activité réelle du cron système WHMCS, car elle répond à la question « est-ce que cela continuera de fonctionner quand personne ne regarde ? ». Un clic sur un bouton ne peut pas répondre à cette question. Si Run Sync Now fonctionne mais que la ligne reste rouge pendant des heures, votre cron ne s'exécute pas.

Une ligne de cron orange n'est pas toujours un problème

Cette ligne suit le travail réel de la passerelle : vidage de la file, purge des journaux et réconciliation. Une installation saine mais inactive, sans modification à synchroniser, peut rester en orange sans qu'il y ait quoi que ce soit à corriger.

Une facture est bloquée et n'arrive jamais dans Perfex

Symptôme. Une facture échoue à répétition. Le message du journal cite une devise, et la ligne continue de se réessayer avec un délai croissant.

Cause. La devise de la facture n'est pas configurée dans Perfex. Perfex rejette la facture, à juste titre, car il ne peut pas enregistrer un total dans une devise qu'il ne connaît pas.

Solution.

1. Dans Perfex, allez dans Setup > Finance > Currencies.
2. Ajoutez la devise, en utilisant le code ISO exact utilisé par WHMCS, par exemple EUR ou USD.
3. Ne faites rien d'autre. L'événement en file d'attente est réessayé selon son propre calendrier et aboutit à la tentative suivante.

Vous disposez d'environ 40 heures

Le calendrier de nouvelles tentatives autorise 15 tentatives réparties sur environ 40 heures. Ajoutez la devise dans cette fenêtre, sans quoi la ligne passe au rebut et devra être rejouée manuellement. Si vous êtes sur le point de reprendre des factures historiques, ajoutez d'abord toutes les devises utilisées par vos clients.

Le cas voisin : « Not mapped (will retry) »

Un enregistrement enfant est arrivé avant son parent : un contact dont le client n'est pas encore dans Perfex, une facture dont le client n'est pas encore associé, ou une réponse de ticket dont le ticket n'a pas été synchronisé.

Cela se résout normalement tout seul. La file livre dans l'ordre, le parent arrive, et l'enfant aboutit à sa tentative suivante. Cela ne devient un vrai problème que lorsque le parent ne sera jamais synchronisé, par exemple si vous avez repris des services sans reprendre les clients. Dans ce cas, mettez le parent en file d'attente (modifiez le client dans WHMCS, ou lancez une reprise Clients) et les enfants suivront.

La licence refuse de s'activer

Symptôme. Vous avez collé une clé et l'installation affiche toujours Free.

Deux conditions sont nécessaires pour Pro : une clé valide et une connectivité entre votre serveur WHMCS et le service de licences. Lisez la couleur de la bannière, car elle vous indique laquelle des deux fait défaut.

Bannière	Signification	Solution
🔴 Rouge	Le serveur de licences a activement rejeté la clé, et le message en donne la raison.	Recopiez la clé depuis l'e-mail d'achat en une seule fois. Les clés comptent 32 caractères et peuvent contenir de la ponctuation : ne supprimez rien et ne reformatez pas. Si le message mentionne des installations ou un quota, libérez un emplacement d'activation en retirant la clé d'une installation qui n'en a plus besoin.
🟠 Orange	Votre serveur n'a pas pu joindre le service de licences. Il ne s'agit pas d'un rejet.	La clé est enregistrée et les nouvelles tentatives se poursuivent. Autorisez le trafic HTTPS sortant vers api.freemius.com à travers tout pare-feu ou proxy de sortie sur le serveur WHMCS. Cliquez ensuite sur Check licence now.
⚪ Aucune bannière	Vous avez enregistré la même clé que celle déjà stockée : rien n'a donc été revérifié.	Cliquez sur Check licence now.
L'en-tête indique « awaiting first verification »	Une clé est enregistrée mais n'a jamais été confirmée.	Cliquez sur Check licence now.

Autres vérifications :

• Assurez-vous que la clé se trouve bien dans Pro License Key, sous Settings > Pro licence sur la page du module, et non quelque part sur l'écran Configure de WHMCS.
• Cliquez sur Check licence now en laissant quelques secondes entre deux pressions. Une seconde pression rapide répond « checked a moment ago » sans envoyer de requête.
• Si Pro est actif dans WHMCS mais que Perfex affiche toujours Free, cliquez sur Check licence now ou sur Test Connection dans WHMCS. Les deux transmettent immédiatement l'état de l'offre à Perfex. Rechargez ensuite la page de paramètres Perfex.

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

Aucun Connection code n'apparaît dans Perfex

Symptôme. Vous êtes sur Setup > WHMCS Bridge, vous avez enregistré un secret, et il n'y a aucun champ Connection code, seulement une note grise.

Causes et solutions. La note elle-même vous indique le cas qui s'applique.

Note	Cause	Solution
« not served over HTTPS »	L'appairage nécessite une installation Perfex en HTTPS.	Corrigez le certificat, ou utilisez la configuration manuelle.
« shorter than 32 characters »	Le secret enregistré est trop court. Avoir cliqué sur Generate sans cliquer sur Save en est la cause habituelle.	Cliquez sur Generate, puis sur Save. Le code apparaît au rechargement.

L'appairage échoue avec « the shared secret does not match »

Symptôme. Vous avez collé un Connection code dans WHMCS et obtenu une bannière rouge mentionnant une erreur HTTP 401.

Cause. Le code contient un secret que Perfex ne possède plus. Il s'agit presque toujours d'un code copié avant un Generate et un Save ultérieurs, ou d'un Generate qui n'a jamais été enregistré.

Solution. Dans Perfex, cliquez sur Save sur la page de paramètres pour que le secret actuel soit réellement stocké, copiez un nouveau Connection code, et collez celui-ci. La tentative échouée n'a rien enregistré du côté WHMCS : votre configuration précédente, qui fonctionnait, est donc intacte.

La correspondance des départements affiche une zone de texte au lieu de listes déroulantes

Symptôme. La page de paramètres Perfex affiche une simple zone de texte pour la correspondance des départements, au lieu d'une liste déroulante par département WHMCS.

Cause. La page n'a pas pu récupérer l'annuaire de vos départements d'assistance WHMCS. L'indication sous la zone de texte précise le cas qui s'applique :

Indication	Cause	Solution
« Couldn't fetch WHMCS departments (needs Pro + working connection) »	La passerelle n'est pas configurée, WHMCS est injoignable depuis le serveur Perfex, ou WHMCS est sur l'offre Free. L'annuaire est soumis à la même restriction de licence que la synchronisation des tickets.	Terminez l'appairage, vérifiez que Perfex peut joindre votre URL WHMCS en HTTPS, et activez Pro.
« Connection OK, but WHMCS has no support departments yet »	La récupération a fonctionné ; il n'y a simplement rien à faire correspondre.	Créez des départements dans WHMCS sous Support > Support Departments, puis rechargez la page Perfex.

La zone de texte manuelle whmcs_deptid=perfex_department_id fonctionne toujours entre-temps, à raison d'une correspondance par ligne. Cela ne bloque pas la synchronisation : un ticket sans correspondance retombe sur votre département par défaut, ou sur l'ID de département Perfex le plus bas.

Des lignes bloquées en état dead

Symptôme. Le compteur Dead events de la page du module WHMCS, ou le compteur dead du panneau Outbound queue de Perfex, est supérieur à zéro.

Cause. Ces lignes ont échoué 15 fois sur environ 40 heures pour la même raison. Les lignes en rebut ne sont jamais réessayées automatiquement ni purgées, délibérément, afin que vous puissiez les examiner.

Solution.

1. Déterminez pourquoi. Ouvrez Recent activity dans WHMCS, ou la colonne « Last error » de la file sortante dans Perfex, et lisez l'erreur des lignes concernées. La cause est presque toujours l'une des suivantes : une devise Perfex manquante, un secret qui ne correspond pas, une offre Free bloquant un événement Pro, ou Perfex qui était hors ligne.

2. Corrigez d'abord cette cause racine. Rejouer une ligne sans corriger la cause revient simplement à brûler 40 heures de plus.

3. Remettez le travail en file d'attente. La méthode la plus sûre ne nécessite aucun accès à la base de données :

   • Pour les clients, contacts, factures, services et domaines, redéclenchez l'événement. Modifiez et enregistrez l'enregistrement dans WHMCS, ou lancez l'assistant de reprise en mode Only new (not yet synced).
   • Pour les modifications côté Perfex, modifiez à nouveau l'enregistrement Perfex afin de générer un nouvel événement.

4. Si vous préférez rejouer la ligne d'origine et que vous disposez d'un accès à la base de données, repassez-la en pending. Effectuez d'abord une sauvegarde :

   UPDATE mod_perfexbridge_outbox
      SET status = 'pending', attempts = 0, next_attempt_ts = 0
    WHERE id = 123;

   Remplacez 123 par l'ID de la ligne que vous souhaitez rejouer. La table équivalente côté Perfex est tblwhmcs_bridge_outbox, avec votre préfixe de tables Perfex.

Une modification faite dans Perfex n'arrive jamais dans WHMCS

Déroulez cette liste :

1. Le côté WHMCS est-il en Pro ? Consultez le panneau WHMCS plan sur la page de paramètres Perfex. La synchronisation bidirectionnelle est réservée à Pro.
2. L'URL WHMCS est-elle renseignée du côté Perfex ? Setup > WHMCS Bridge > WHMCS URL, en HTTPS, sans chemin final. L'appairage renseigne normalement ce champ lors du premier appairage, mais il n'écrase jamais une valeur déjà présente.
3. Le serveur Perfex peut-il joindre WHMCS en HTTPS ? Le client d'envoi de Perfex impose HTTPS et vérifie le certificat, exactement comme du côté WHMCS.
4. Le cron Perfex s'exécute-t-il ? Les modifications issues de Perfex sont livrées par le cron Perfex, et non par celui de WHMCS. Vérifiez votre tâche cron Perfex.
5. L'enregistrement est-il associé ? Seuls les clients synchronisés depuis WHMCS sont associés. Un client créé directement dans Perfex n'a pas d'équivalent WHMCS et n'est jamais transmis. De même, les tickets créés directement dans Perfex restent dans Perfex.
6. Lisez le panneau Outbound queue. Il indique la dernière erreur pour chaque ligne.

Une modification est revenue en arrière et a écrasé ma saisie

Symptôme. Vous avez modifié un enregistrement dans un système, et il est revenu à la valeur de l'autre système.

Cause. Les deux côtés ont modifié le même enregistrement depuis la dernière synchronisation, et votre Two-Way Conflict Policy a désigné le gagnant.

Solution. Choisissez la politique qui correspond au fonctionnement de votre équipe, sous Settings > Sync behaviour sur la page du module WHMCS :

• newest_wins (par défaut) - la modification la plus récente l'emporte. Nécessite que les horloges des deux serveurs soient exactes.
• whmcs_wins - WHMCS fait toujours autorité.
• perfex_wins - Perfex fait toujours autorité.

Si les horloges des deux hôtes échappent à votre contrôle, évitez newest_wins : la dérive d'horloge décale ses décisions d'autant.

Les clients reçoivent deux e-mails pour une seule réponse de ticket

Symptôme. Un collaborateur Perfex répond à un ticket synchronisé, et le client reçoit deux notifications.

Cause. Perfex envoie son propre e-mail de réponse de ticket, et la réponse synchronisée vers WHMCS déclenche également la notification propre à WHMCS. Il s'agit d'un comportement documenté, et non d'une boucle de synchronisation. La suppression des e-mails ne couvre que le sens WHMCS vers Perfex.

Solution. Si vos clients utilisent l'espace client WHMCS, désactivez le modèle d'e-mail Perfex ticket-reply sous Setup > Email Templates > Tickets dans Perfex.

Toujours bloqué : ce qu'il faut réunir avant de contacter l'assistance

Ayez ces éléments sous la main et la réponse arrive généralement dès le premier échange :

• La version des deux modules, actuellement 1.3.4, et la confirmation que les deux côtés sont sur la même version.
• La version de WHMCS, la version de Perfex CRM, et la version de PHP sur les deux serveurs.
• Une capture d'écran de la Setup checklist depuis la page du module WHMCS.
• Les compteurs Queue pending et Dead events.
• Les lignes concernées de Recent activity dans WHMCS et de Recent inbound events dans Perfex, avec la colonne de message complète.
• Ce que vous étiez en train de faire au moment de l'incident, et si cela a déjà fonctionné auparavant.

N'envoyez jamais votre secret partagé ni votre Connection code

Le Connection code contient votre secret partagé. Ni l'un ni l'autre n'ont leur place dans un ticket d'assistance, une capture d'écran ou un message de discussion. L'assistance n'a jamais besoin de l'un ou l'autre pour diagnostiquer un problème.