Automatiser la facturation HestiaCP

Un produit d’hébergement automatisé compte exactement trois moments où l’argent et les machines se touchent :

1. 01La commande est payée : un compte doit exister en quelques secondes, avec le bon paquet.
2. 02La facture est en retard : le compte doit s’éteindre, et revenir dès qu’il est payé.
3. 03L’abonnement se termine : le compte doit disparaître, vraiment, données comprises.

HestiaCP a une commande pour chacun de ces moments. Ce qu’il n’a pas, c’est quoi que ce soit qui décide quand les lancer. Cette page traite de la liaison entre les deux moitiés, et des endroits précis où l’API de HestiaCP répond d’une façon qui casse silencieusement une première tentative.

Les trois moments et les commandes dessous

Regardez la colonne des réponses. Une mutation réussie sur HestiaCP, c’est HTTP 204 avec rien dans le corps. Pas 200. Un client écrit en supposant que le succès vaut 200 rejette chaque appel qui a fonctionné, puis le réessaie généralement, et c’est ainsi qu’une intégration qui marche devient une intégration bannie (voir plus bas).

La vraie réponse vit dans un en-tête, Hestia-Exit-Code, qui porte un nombre issu d’une table fixe. Le statut HTTP en dérive et replie une vingtaine de codes sur quatre statuts. Lisez l’en-tête ; traitez le statut comme un indice.

La suspension n’est pas symétrique, et cela compte ici plus qu’ailleurs

C’est le piège qui touche spécifiquement une intégration de facturation, car une intégration de facturation est la seule chose qui suspend deux fois le même compte.

Mesuré, sur le même compte :

v-suspend-user   sur un compte actif      → 204, sortie 0
v-suspend-user   sur un compte suspendu   → 401, sortie 5   (« user X is suspended »)
v-unsuspend-user sur un compte suspendu   → 204, sortie 0
v-unsuspend-user sur un compte actif      → 204, sortie 0

Réactiver est idempotent. Suspendre ne l’est pas. Et l’échec produit est un 401 : le même statut que pour un mauvais secret, une clé hors de sa portée et une adresse bannie.

Une campagne de relance qui suspend tout ce qui est en retard, y compris ce qu’elle a déjà suspendu hier, signalera donc des erreurs d’authentification pour des comptes qui sont exactement dans l’état voulu. Le code de sortie 5 sur v-suspend-user signifie « c’était déjà le cas » et doit se lire comme un succès.

Ne jamais réessayer après une erreur d’authentification

HestiaCP bannit une adresse après cinq connexions refusées, avec fail2ban, maxretry = 5 et un DROP iptables. Une fois cela déclenché, les appels ne partent plus en délai dépassé au niveau applicatif mais au niveau réseau : votre supervision dit que le panneau est injoignable, et rien dans vos journaux ne désigne un problème d’identifiants.

Pour une intégration de facturation cela compte plus que pour tout le reste, car une intégration de facturation est ce qui tourne sans surveillance la nuit. Deux conséquences :

• Les codes de sortie 9, 10 et 21 ne doivent jamais déclencher de réessai automatique. Ce sont respectivement mauvais secret, permission refusée et API désactivée. Aucun n’est une panne passagère, et tous trois comptent pour le bannissement.
• Une commande hors des permissions de la clé compte aussi comme une connexion refusée. Ce n’est pas évident : la même ligne de journal est écrite pour un mauvais secret et pour une clé valide qui tend la main vers une commande qu’elle n’a pas le droit de lancer. Une clé restreinte au jeu billing fourni d’origine n’a ni v-list-user-packages ni v-list-web-domains, un cycle de relevé qui lit les paquets et les domaines épuise donc le compteur comme prévu. Utilisez une clé sans portée restreinte, celle de l’administrateur.

Lever un bannissement demande un terminal sur l’hôte du panneau : v-delete-firewall-ban <adresse> HESTIA. Si le logiciel que vous construisez ne sait pas dire cette phrase, la personne d’astreinte à trois heures du matin passera la nuit sur le mauvais problème.

Une commande payée coûte deux appels, donc un retour en arrière

HestiaCP n’a aucune commande qui crée un utilisateur et y rattache aussitôt un domaine. Cela laisse une fenêtre :

v-add-user       provibrtest1 …                        → 204, sortie 0
v-add-web-domain provibrtest1 "pas un domaine valide"   → 422, sortie 2
v-list-user      provibrtest1                           → le compte existe, avec zero domaine

Un vrai utilisateur unix, avec un répertoire personnel, sans site, et une ligne dans chaque comptage. Si le domaine de votre client était déjà pris sur votre panneau, et cela arrive puisque les clients déménagent, la commande échoue et il vous reste un demi-compte que personne ne remarquera jamais.

La règle est simple et doit être intégrée : si l’étape deux échoue, supprimez l’utilisateur et signalez l’erreur d’origine. Un domaine refusé ne doit jamais laisser un demi-compte derrière lui.

Provibr fait exactement cela, et l’erreur que voit le client est celle de HestiaCP sur le domaine, pas une seconde erreur portant sur un nettoyage.

Où se trouve réellement la facture

Cela vaut la peine d’être explicite, car c’est le malentendu le plus courant : Provibr ne facture pas vos clients. Il ne leur envoie rien, ne les relance pas, et ignore ce que vous leur facturez. Cette relation est la vôtre.

Ce que Provibr facture, c’est la capacité que vous réservez : combien de comptes d’hébergement vous pouvez faire tourner en même temps, par mois, à un prix unitaire dégressif. Ce que vous facturez à vos propres clients pour un compte HestiaCP, et comment, reste entièrement dans votre propre système de facturation.

Il y a deux façons de relier les deux moitiés.

Un module WHMCS. Si vous faites déjà tourner WHMCS, installez le module de provisionnement Provibr et faites pointer un produit WHMCS vers une formule d’hébergement web Provibr. Une commande payée crée le compte, une suspension le suspend, une résiliation le supprime. Votre client garde un compte, une facture et un identifiant. Le module est une simple archive zip que vous installez vous-même et qui tourne dans votre WHMCS : rien n’est à activer de notre côté.

L’API REST. Si vous faites tourner FOSSBilling, Blesta, quelque chose de maison, ou un tableur et une tâche planifiée, pilotez-le directement. Une clé, une URL de base, et exactement les droits que possède déjà le membre derrière cette clé.

La règle unique pour le piloter depuis votre code

Tout ce qui touche une machine est asynchrone, et cela doit l’être. Votre infrastructure n’est joignable que par l’agent qui se trouve dans votre propre réseau, et cet agent sort en connexion sortante. Un point d’accès qui modifie un compte ne peut donc pas répondre avec le résultat : il répond que l’ordre est accepté et vous tend une commande à suivre, que vous lisez jusqu’à ce que son état soit définitif, terminé, échoué, expiré ou annulé. Une commande échouée porte le code d’erreur de l’agent lui-même avec ses paramètres, celui-là même que le panneau affiche à l’écran.

La lecture ne fonctionne jamais ainsi. Un inventaire, une adresse ou une facture répond immédiatement, car cette réponse vient d’une base de données et non de votre hôte.

La conséquence pratique pour un déclencheur de facturation : ne marquez pas la commande comme terminée sur la réponse d’acceptation. Sur HestiaCP, v-add-user prend environ une seconde et v-delete-user environ trois, l’attente est donc courte, mais la réponse que vous obtenez d’abord dit « nous l’avons envoyé » et non « cela a marché ».

Suspendre, c’est aussi maîtriser vos propres coûts

Un lien facile à manquer. Dans Provibr, un serveur suspendu ne compte pas dans votre capacité, et pour un compte d’hébergement il n’existe pas d’état « arrêté » : il y a actif et suspendu.

L’action de relance que vous vouliez de toute façon lancer pour des raisons commerciales est donc aussi celle qui libère la place que vous payez. Suspendez un compte en retard et il cesse immédiatement de compter ; supprimez-le et il cesse aussi de compter ; laissez-le tourner impayé et vous le payez.

Ce que cela n’automatise pas

Provibr gère des comptes, pas le panneau. Il n’installe pas HestiaCP, ne le met pas à jour, ne modifie aucun réglage serveur et ne touche ni au DNS, ni aux boîtes aux lettres, ni aux bases de données : un client qui supprime sa propre boîte aux lettres depuis HestiaCP le fait sans que rien au-dessus le sache ni s’en soucie. Il n’y a pas de console pour un compte d’hébergement. Et il n’y a pas de suspension partielle : un compte est actif ou il ne l’est pas.

Si vous vendez aussi des VPS, des serveurs de jeu ou des comptes cPanel, les mêmes trois moments s’y appliquent, et ils peuvent vivre dans un seul inventaire. Provibr fait tourner aujourd’hui ses panneaux de contrôle, ses hyperviseurs et ses panneaux de jeu côte à côte, avec un seul modèle de droits et un seul journal d’activité sur l’ensemble.