Automatisation de la facturation pour Pelican Panel

Pelican possède un indicateur suspended sur chaque serveur. Rien dans Pelican ne le positionne jamais. Cette seule phrase est toute la raison d’être de cette page : le panneau sait arrêter le serveur d’un client, mais il n’a aucune idée de savoir si ce client a payé.

Cette page décrit à quoi ressemble une automatisation qui fonctionne : le chemin de commande, le chemin de relance, et les parties réellement plus difficiles qu’elles n’en ont l’air.

Deux couches de facturation, et ce n’est pas la même chose

Séparez-les d’abord. On confond constamment ces deux-là, puis on discute du mauvais problème.

Ce que vous facturez à vos propres clients, et comment, reste entièrement dans votre système de facturation. Provibr ne voit jamais une facture client, ne fixe jamais un prix à votre place et ne parle jamais à vos clients ; il vous facture la capacité réservée par type de ressource, à un prix unitaire qui décroît par paliers à mesure que le nombre augmente.

Cette séparation est ce qui rend l’automatisation traitable. Votre système de facturation détient la décision ; la couche de provisionnement détient l’exécution.

Le cycle de vie, en correspondance

Voici la correspondance dont toute automatisation de serveurs de jeu a besoin, quels que soient vos outils :

Pelican est à l’aise ici, et cela mérite d’être dit clairement, car tous les panneaux de jeu ne le sont pas. Pelican dispose d’une véritable primitive de suspension. Un serveur suspendu l’est dans le panneau : quelqu’un ayant un accès direct à Pelican ne peut pas simplement le redémarrer. Quand l’application de la règle compte (et pour les relances, elle compte), c’est la différence entre une politique et un souhait.

(Par contraste : PufferPanel n’a pas de suspension propre, une suspension y est donc une notion de plateforme que le panneau n’impose pas.)

La règle qui façonne tout : rien n’est instantané

C’est la partie que l’on rate quand on câble une API soi-même.

Votre panneau vit dans votre propre réseau, et une plateforme sensée l’atteint via un agent qui se connecte vers l’extérieur : aucun port entrant, aucun trou dans le pare-feu. La conséquence est inévitable : un endpoint qui modifie une machine ne peut pas répondre par le résultat. Il répond que l’ordre a été accepté, et vous remet de quoi en suivre la suite :

POST /v1/servers/{serverId}/actions/suspend
Authorization: Bearer pvk_...
Idempotency-Key: dunning-inv-10482

{
  "command": {
    "id": "cmd_...",
    "kind": "game.suspend",
    "status": "pending"
  }
}

Vous obtenez 202 Accepted, pas 200. Ensuite vous relisez cette commande jusqu’à ce que son statut soit définitif : done, failed, timed_out ou cancelled. Une commande échouée porte le code d’erreur de l’agent lui-même, avec ses arguments.

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.

Concevez vos hooks de facturation en conséquence. Un hook qui lit « l’API a répondu » comme « le travail est fait » signalera le succès d’une suspension qui n’a jamais eu lieu, précisément le jour où cela comptait.

Répéter une requête sans risque

Tout ce qui crée quelque chose accepte un en-tête Idempotency-Key que vous composez vous-même. Répétez la même requête avec la même valeur et vous récupérez le premier résultat, au lieu d’un deuxième serveur, d’une deuxième commande ou d’un deuxième prélèvement.

Pour les relances, ce n’est pas un luxe. Un cron qui tourne tous les quarts d’heure, un webhook renvoyé, un administrateur qui clique deux fois : tous trois sont normaux, et tous trois doivent être inoffensifs. Indexez la requête sur quelque chose de stable de votre côté : le numéro de facture, l’identifiant du service, l’étape de relance. Réutiliser cette valeur pour une autre requête est refusé volontairement : une clé qui signifie deux choses ne signifie rien.

Les verbes, et quand ils sont autorisés

Un serveur de jeu accepte six actions via l’API :

start · stop · restart · kill · suspend · resume

Ils sont gardés par l’état courant du serveur, et c’est plus strict qu’il n’y paraît :

La ligne suspend est la plus intéressante, et c’est un choix délibéré : vous pouvez suspendre un serveur déjà arrêté. Si la suspension ne fonctionnait que sur des serveurs en marche, un client pourrait arrêter son propre serveur, cesser de payer et devenir intouchable. Le panneau refuserait la suspension parce que rien ne tournait. Une application de la règle que l’on contourne en appuyant sur « stop » n’en est pas une.

suspend depuis installing compte aussi : une résiliation qui arrive au milieu d’une installation ne devrait pas attendre la fin de celle-ci.

Depuis un panneau de facturation plutôt qu’en code

Si vous faites déjà tourner WHMCS, vous n’avez rien de tout cela à écrire. Provibr fournit un module de provisionnement pour WHMCS sous forme d’une simple archive zip que vous installez vous-même : un produit WHMCS pointe vers un plan Provibr, et le flux de commande habituel de WHMCS se charge de créer, suspendre, réactiver et résilier.

Deux décisions de conception dans ce module méritent d’être reprises, même si vous écrivez votre propre pont :

Une livraison encore en cours compte comme un succès. Si le budget d’attente expire pendant que l’installateur travaille encore, le module signale un succès. La commande a été acceptée : la ligne serveur existe, l’adresse est attribuée, l’ordre est chez l’agent. Et WHMCS ne connaît pas de statut « en cours d’installation » (Pending y signifie rien ne s’est encore produit, ce qui est démontrablement faux). Un ordre qui échoue réellement, c’est autre chose : le service reste alors Pending, l’administrateur voit pourquoi, et un clic répété est sans danger grâce à la clé d’idempotence.

Un serveur qui n’existe déjà plus est une résiliation réussie. Un 404 à la suppression signifie quatre choses à la fois (identifiant inconnu, autre organisation, non attribué à ce membre, ou déjà supprimé), et pour un hook de résiliation l’action correcte est la même dans les quatre cas : il n’y a plus rien à nettoyer. Le traiter comme une erreur laisse un service coincé dans « terminating » pour toujours.

Ce qui n’est volontairement pas automatisé

Des frontières honnêtes, car ce sont les questions qui arrivent après que vous avez déjà vendu quelque chose :

• Pas de facturation à l’usage. Les relevés par serveur sont collectés et affichés dans le panneau, mais pas encore exposés via l’API. Sans endpoint, pas de facturation mesurée. Si votre produit est « payez la RAM que vous avez consommée », ceci ne le fait pas aujourd’hui.
• Pas de changement de plan en un appel. Changer de plan n’est pas non plus un appel d’API unique au niveau de Pelican : c’est une réinstallation ou un changement de ressources, avec des conséquences différentes pour les données du client.
• Pas de réinitialisation de mot de passe via l’API. Les identifiants circulent de façon transitoire et ne sont conservés nulle part : il n’y a rien à renvoyer.
• Pas d’authentification unique depuis votre panneau de facturation vers le panneau Provibr.
• Pas de boucle de réconciliation d’inventaire : un refus, pas un manque. La synchronisation _ListAccounts de WHMCS résilie tout service absent de la réponse, et « absent » a des causes innocentes : une portée d’API plus étroite, un membre restreint à une partie de l’inventaire, une limitation de débit, une page courte dont le curseur n’a pas été suivi. Chacune supprimerait des machines clientes. À la place, l’espace client lit le statut réel à chaque affichage de page, ce qui n’est pas une synchronisation et ne prétend pas en être une.

Compter la capacité, et comment cela rejoint les relances

La facturation de la plateforme compte la capacité, pas l’usage, avec une règle qui surprend tout le monde le premier mois : chaque serveur compte, qu’il tourne ou non. Seul un serveur suspendu ne compte pas, et un serveur supprimé non plus. Arrêter une machine ne libère pas de place.

Cela s’articule proprement avec les relances. Un client que vous suspendez pour impayé cesse de compter dans votre capacité tant qu’il est suspendu, et recompte dès qu’il paie et que vous réactivez. Vous ne payez donc pas de capacité de plateforme pour un client qui ne vous paie pas.

Dépasser votre limite n’est pas bloqué au moment où vous le faites. C’est détecté, on vous le dit, et vous disposez d’un jour ouvré complet. Si ce délai de grâce expire, les serveurs les plus récents au-delà de votre limite sont suspendus, les plus récents d’abord, pour que ce que vous avez construit en premier survive.

Pelican à côté de tout le reste

Un hébergeur de jeu qui grandit reste rarement sur un seul panneau. Provibr couvre ses panneaux de contrôle, ses hyperviseurs et ses panneaux de jeu dans un seul tableau de bord, avec une seule API et un seul chiffre de capacité pour l’ensemble.

POST /v1/servers/{id}/actions/suspend fait la même chose qu’il y ait dessous un serveur Pelican, un serveur Pterodactyl ou un compte d’hébergement DirectAdmin. Les différences vivent dans le fournisseur, pas dans votre code d’intégration.