Installer et configurer WHMCS pour fonctionner avec le système de facturation HOSTKEY¶

Dans cet article

• Logiciels requis
• Installation du module
• Activer le module dans WHMCS
• Chargement et suppression d'informations de HOSTKEY via les commandes console
• Configuration des devises pour l'exportation des prix
• Personnaliser des produits spécifiques pour la revente
• Modifier un produit spécifique
• Activation du paiement pour les produits commandés
• Exemples et conseils
• Erreurs typiques et solutions

Logiciels requis¶

• module reseller pour WHMCS : download;
• version de WHMCS 8.8 ou supérieure.

Installation du module¶

Extrayez le contenu de l'archive à la racine du système de comptabilité.

1. Téléchargez et décompressez l'archive du module dans la racine de WHMCS

   Extrayez le contenu de l'archive à la racine du système de comptabilité.

   La WHMCS root est l'emplacement où se trouvent les fichiers configuration.php et les dossiers vendor/, modules/, includes/.

   Via SSH :

   cd /path/to/your/whmcs
   

   unzip /path/to/HostkeyResellerMod.zip
   

   Via FTP : Téléchargez le contenu de l'archive dans la racine de WHMCS, en acceptant la fusion des dossiers.

2. Vérifiez la structure après le décompression

   Les éléments suivants doivent apparaître :

   • modules/addons/hostkeyresellermod/
   • modules/servers/hostkeyresellermod/
   • modules/gateways/callback/hostkeyresellermod.php
   • includes/hooks/hostkeyresellermod.php

   Fichiers clés :

   • modules/addons/hostkeyresellermod/hostkeyresellermod.php
   • modules/addons/hostkeyresellermod/cron.php
   • modules/addons/hostkeyresellermod/clean.php
   • modules/addons/hostkeyresellermod/import.ini (optionnel)

3. Actualisez votre session du panneau d'administration

   Déconnectez-vous et reconnectez-vous au panneau d'administration de WHMCS. Videz le cache de votre navigateur si nécessaire.

Problèmes courants lors de la copie¶

• Fichiers dans le mauvais dossier : Le module n'apparaîtra pas dans la liste s'il se trouve dans un sous-dossier plutôt que dans la racine de WHMCS.
• Droits/Propriétaire : Des droits incorrects empêchent l'activation ou l'affichage.
• Cache du navigateur/session : Se reconnecter résout le problème "le module n'est pas visible".

Activer le module dans WHMCS¶

1. Ouvrez la liste des modules addon

   Après avoir copié le module dans le répertoire WHMCS et configuré les permissions du système de fichiers, vous devez activer le module. Pour ce faire :

   • Chemin : System Settings > Apps & Integrations > Addon Modules.
   • Recherchez HOSTKEY VPS/Dedicated.

   

2. Activez le module et accédez aux paramètres

   • Cliquez sur Activate.
   • Puis sur Configure (ou Settings) pour ouvrir le formulaire de configuration.

   

3. Remplissez les paramètres du module et enregistrez

   Champs :

   • API Url — adresse de l'API de facturation HOSTKEY :
   • International : https://invapi.hostkey.com/ (par défaut).
   • API key — clé d'accès à l'API HOSTKEY. Obtenez-la en suivant ces instructions ; gardez-la secrète.
   • Preset name prefix — préfixe de nom (par défaut HKP-) pour distinguer visuellement les produits HOSTKEY dans les listes WHMCS.
   • Default product group — groupe de produits WHMCS pour les produits créés (par défaut Hostkey servers).
   • Logging of requests to Hostkey API — à activer pour le débogage si nécessaire.

   Cliquez sur Save Changes.

   

4. Configurez l'accès (Access Control)

   Cochez les groupes d'administrateurs qui doivent avoir accès au module (nous recommandons d'activer "Administrators").

   Attention

   Si vous ne cochez aucun groupe sous Access Control, le module ne sera pas disponible pour ce groupe et ne s'affichera pas dans le menu Addons, même pour l'administrateur.

   Si tout est fait correctement (y compris la configuration des permissions), la section HOSTKEY VPS/Dedicated apparaîtra dans le menu Addons.

5. Ouvrez le module et configurez l'importation des produits

   Allez dans Addons > HOSTKEY VPS/Dedicated et sélectionnez les produits que vous souhaitez revendre :

   • Import VPS products — pour les VPS/VDS ;
   • Import Bare metal products — pour les serveurs dédiés ;
   • Import GPU products — pour les serveurs GPU.

   Pour chaque catégorie cochée, définissez la marge et le format :

   • En pourcentage : saisissez la valeur et laissez "%" (exemple : "10 %").
   • En devise fixe : saisissez la valeur et sélectionnez la devise WHMCS (exemple : "5 USD").

   Sélectionnez le mode d'arrondi dans Round price to :

   • Not round — sans arrondi.
   • 0.1, 0.2, etc — au dixième près.
   • 0.25, 0.5, 0.75 — au quart près.
   • 0.5, 1.0 — à la demi-unité.
   • 1.0 — à l'unité entière.

   

   Cliquez ensuite sur le bouton ImportProduct/AdjustPrice.

   Remarque

   Pour la première exécution, nous recommandons d'utiliser une autre méthode, car lors du chargement d'une grande quantité d'informations, la page peut se terminer par un code 504. Lors de votre premier import groupé, le temps de chargement peut être long ; si une erreur 504 survient, utilisez l'importation via la console.

6. Téléchargement réussi et étapes suivantes

   Si le module est correctement connecté et activé, un message confirmant le téléchargement réussi des produits HOSTKEY apparaîtra, ainsi qu'une suggestion de se rendre dans les paramètres spécifiques du produit via le menu System Settings > Product/Services.

   

   Allez dans Product/Services :

   • Vérifiez les groupes et produits créés.
   • Si nécessaire, ouvrez le produit, définissez les prix/périodes sur l'onglet Pricing ; sur l'onglet Details, décochez la case Hidden pour que le produit s'affiche dans la vitrine (showcase).

   

   Remarque

   En cas de grande quantité d'informations, la page peut se terminer par le code 504 Gateway Timeout. Pour le premier chargement de la liste des produits, nous recommandons d'exécuter la commande dans la racine de la facturation.

Chargement et suppression d'informations de HOSTKEY via les commandes console¶

Exécution de cron.php¶

Utilisé pour charger les informations depuis Hostkey. Exécutez la commande depuis la racine de votre site web :

php modules/addons/hostkeyresellermod/cron.php

Exécution de clean.php¶

Supprime les informations précédemment reçues de HOSTKEY. Exécutez la commande depuis la racine de votre site web :

php modules/addons/hostkeyresellermod/clean.php

Important : import.ini prime sur les paramètres admin¶

Si un fichier import.ini existe dans modules/addons/hostkeyresellermod/, l'importation se basera sur les paramètres de ce fichier et écrasera/ignorera les paramètres spécifiés via le panneau d'administration sur la page Addons > HOSTKEY VPS/Dedicated.

Nous recommandons d'utiliser import.ini si l'importation via l'interface web est instable (gel, 504) ou lorsque vous lancez l'importation via cron/console.

Si vous souhaitez configurer l'importation via le panneau d'administration, supprimez ou renommez import.ini :

rm modules/addons/hostkeyresellermod/import.ini

Après la suppression/le renommage du fichier, l'importation utilisera à nouveau les valeurs spécifiées dans le panneau d'administration.

Paramètres dans import.ini¶

Pendant le fonctionnement, la commande utilise le fichier modules/addons/hostkeyresellermod/import.ini (s'il existe).

Paramètres dans import.ini :

• template = 5 — remplacez 5 par l'ID du modèle d'e-mail souhaité de WHMCS (vous pouvez le voir dans la section Email Templates)
• round = 0 — arrondi des prix (0 = ne pas arrondir, 10 = au dixième, 4 = au quart, 2 = à la demi-unité, 1 = à l'unité entière)
• vps = 10 % — marge sur les VPS
• bm = 50 USD — marge sur le Bare metal
• gpu = 100 RUB — marge sur les GPU

Exemple de import.ini :

[general]
round = 0
template = 5
[markup]
vps = 10 %
bm = 50 USD
gpu = 100 RUB

Le fichier possède deux sections :

1. La section general contient le paramètre round, qui contrôle l'arrondi. Valeurs possibles pour le paramètre :

   • 0 — aucun arrondi ;
   • 10 — arrondissement au dixième le plus proche ;
   • 4 — arrondissement au quart le plus proche ;
   • 2 — arrondissement à la demi-unité la plus proche ;
   • 1 — arrondissement à l'unité entière la plus proche.

2. La section markup contient la marge en pourcentage pour chaque groupe.

   Si le fichier import.ini n'existe pas ou si l'option default est utilisée, aucune marge ni aucun arrondi ne sont appliqués.

Mise à jour automatique des préconfigurations (cron)¶

Nous recommandons de configurer une planification une fois par jour, pendant les heures creuses.

Exemple de crontab (chaque jour à 03:30 ; remplacez les chemins vers whmcs par les vôtres) :

30 5 * * * /usr/bin/php /path/to/whmcs/modules/addons/hostkeyresellermod/cron.php >/dev/null 2>&1

Conseils de planification : consultez brièvement cron, l'assistant — crontab.guru.

Configuration des devises pour l'exportation des prix¶

Pour exporter précisément les prix des produits, vous devez configurer les taux de change par rapport à l'EUR ou l'USD et entre eux. Cela peut être fait dans la section Payments >> Currencies.

Personnaliser des produits spécifiques pour la revente¶

En allant dans System Settings >> Product/Services, vous verrez un tableau de tous les produits disponibles pour la revente.

En cliquant sur les icônes dans les colonnes de droite, vous pouvez modifier les paramètres du produit ou le retirer de la liste. La plupart des paramètres sont déterminés par les réglages WHMCS et nous ne nous concentrerons que sur ceux qui sont critiques pour la revente.

Modifier un produit spécifique¶

Cliquer sur l'icône Edit vous mènera à la section de modification des paramètres du produit (Edit Product).

Onglet Detail¶

Cet onglet vous permet de modifier le nom du produit qui sera affiché sur votre boutique.

Vous pouvez également cocher Hidden pour masquer le produit du formulaire de commande sans le supprimer.

Onglet Price¶

Utilisez cet onglet pour définir le prix de votre produit dans les devises disponibles.

Vous pouvez définir trois types de paiement (Payment Type) :

• Free - le produit est distribué gratuitement ;
• One Time - paiement unique pour un mois d'utilisation ;
• Recurring - paiement récurrent pour une période donnée.

Vous définissez le prix pour chaque période et devise séparément, ce qui vous donne la flexibilité d'ajuster votre politique tarifaire :

• One Time/Monthly - Paiement unique ou paiement mensuel récurrent.
• Quarterly - paiement tous les trimestres (3 mois)
• Semi-annual - paiement tous les six mois (6 mois)
• Annual - Paiement pour un an (12 mois)

Deux types de prix distincts sont disponibles :

• Setup Fee - le prix pour l'installation du produit ;
• Price - le prix de vente du produit.

Après avoir modifié les paramètres et le prix, cliquez sur Save Changes pour enregistrer les réglages de ce produit.

Après confirmation de l'enregistrement des paramètres, cliquez sur le bouton en haut à droite Back to product list pour revenir au tableau des produits.

Une fois configurés, les produits apparaissent dans le tableau de bord du client.

Activation du paiement pour les produits commandés¶

Pour payer tout produit commandé, votre solde de compte HOSTKEY sera utilisé. Veuillez vous assurer que le mode automatic payment from balance est activé.

Exemples et conseils¶

• Exemple de marge et d'arrondi : prix 123,56 avec une marge de 10 % et un arrondi à 0,5 > 136,0.
• Devises : vérifiez Payments > Currencies - les taux vers l'EUR/USD et entre les devises utilisées doivent être configurés.

Erreurs typiques et solutions¶

• Invalid API key / 403 : vérifiez la validité de la clé API, l'URL (.com), et l'absence d'espaces superflus.
• Module non visible dans Addons : vérifiez les groupes dans Access Control, actualisez votre session, vérifiez les droits des fichiers/propriétaire.
• 504 Gateway Timeout lors de l'importation : Utilisez l'importation via la console, augmentez le max_execution_time.
• Les prix semblent "à perte" : définissez votre prix dans Pricing plus élevé que le prix d'achat ; vérifiez la marge et l'arrondi.
• Erreur 503 : Pour comprendre, essayez de consulter les journaux d'erreurs du serveur error.log ou php_error.log.