Automatización de la facturación para Pelican Panel

Pelican tiene un indicador suspended en cada servidor. Nada dentro de Pelican lo activa jamás. Esa sola frase es toda la razón de ser de esta página: el panel sabe detener el servidor de un cliente, pero no tiene ni idea de si el cliente pagó.

Esta página cubre qué aspecto tiene una automatización que funciona: el camino del pedido, el camino de la reclamación de pago, y las partes que son de verdad más difíciles de lo que parecen.

Dos capas de facturación, y no son lo mismo

Antes que nada, sepárelas. La gente las confunde constantemente y luego discute sobre el problema equivocado.

Lo que cobra a sus propios clientes, y cómo, se queda enteramente dentro de su sistema de facturación. Provibr nunca ve una factura de cliente, nunca le fija un precio, y nunca habla con sus clientes; le factura la capacidad reservada por tipo de recurso, a un precio unitario que baja por tramos a medida que sube el recuento.

Esa separación es lo que hace la automatización manejable. Su sistema de facturación posee la decisión; la capa de aprovisionamiento posee la ejecución.

El ciclo de vida, en correspondencia

Esta es la correspondencia que necesita toda automatización de alojamiento de juegos, sean cuales sean sus herramientas:

Pelican está cómodo aquí, y vale la pena decirlo con claridad, porque no todos los paneles de juego lo están. Pelican dispone de una primitiva de suspensión de verdad. Un servidor suspendido lo está en el panel: alguien con acceso directo a Pelican no puede simplemente volver a arrancarlo. Cuando la aplicación de la regla importa (y para la reclamación de pago importa), esa es la diferencia entre una política y un deseo.

(Como contraste: PufferPanel no tiene una suspensión propia, así que una suspensión ahí es una noción de plataforma que el panel no impone.)

La regla que da forma a todo: nada es instantáneo

Esta es la parte que la gente hace mal cuando cablea una API por su cuenta.

Su panel vive en su propia red, y una plataforma sensata lo alcanza a través de un agente que se conecta hacia fuera: ningún puerto entrante, ningún agujero en el cortafuegos. La consecuencia es inevitable: un endpoint que cambia una máquina no puede responder con el resultado. Responde que el pedido fue aceptado, y le entrega algo que seguir:

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

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

Obtiene 202 Accepted, no 200. Luego lee ese comando hasta que su estado sea definitivo: done, failed, timed_out o cancelled. Un comando que falló lleva el código de error del propio agente, con sus argumentos.

La lectura nunca funciona así: un inventario, una dirección o una factura responde de inmediato, porque esa respuesta viene de una base de datos y no de su host.

Diseñe sus ganchos de facturación en torno a esto. Un gancho que trata «la API respondió» como «el trabajo está hecho» informará de éxito para una suspensión que nunca ocurrió, justo el día que importaba.

Repetir una petición sin riesgo

Todo lo que crea algo acepta una cabecera Idempotency-Key de su propia creación. Repita la misma petición con el mismo valor y recupera el primer resultado, en lugar de un segundo servidor, un segundo comando o un segundo cargo.

Para la reclamación de pago esto no es un lujo. Un cron de quince minutos, un webhook reenviado, un administrador que hace clic dos veces: los tres son normales y los tres deberían ser inofensivos. Indexe la petición sobre algo estable de su lado: el ID de la factura, el ID del servicio, la etapa de reclamación. Reutilizar ese valor para una petición distinta se rechaza a propósito: una clave que significa dos cosas no significa nada.

Los verbos, y cuándo están permitidos

Un servidor de juego acepta seis acciones por la API:

start · stop · restart · kill · suspend · resume

Están guardados por el estado actual del servidor, que es más estricto de lo que puede parecer:

La fila suspend es la interesante, y es deliberada: puede suspender un servidor que ya está detenido. Si la suspensión solo funcionara sobre servidores en marcha, un cliente podría detener su propio servidor, dejar de pagar y quedar inmune: el panel rechazaría la suspensión porque no había nada en marcha. Una aplicación de la regla que se puede esquivar pulsando «detener» no es aplicación de nada.

suspend desde installing también importa: una cancelación que llega a mitad de instalación no debería esperar a que la instalación termine.

Hacerlo desde un panel de facturación en lugar de en código

Si ya hace correr WHMCS, no necesita escribir nada de lo anterior. Provibr entrega un módulo de aprovisionamiento para WHMCS como un simple zip que instala por su cuenta: un producto de WHMCS apunta a un plan de Provibr, y el flujo de pedidos normal de WHMCS se encarga de crear, suspender, reactivar y cancelar.

Dos decisiones de diseño de ese módulo vale la pena robar aunque escriba su propio puente:

Una entrega que todavía está en curso cuenta como éxito. Si el presupuesto de espera se agota mientras el instalador sigue trabajando, el módulo informa de éxito. El pedido sí fue aceptado (la fila del servidor existe, la dirección está asignada, el comando está con el agente), y WHMCS no tiene un estado «en instalación» (Pending ahí significa no ha pasado nada todavía, lo cual es demostrablemente falso). Un comando que falla de verdad es distinto: el servicio se queda en Pending, el administrador ve por qué, y un clic repetido es inofensivo gracias a la clave de idempotencia.

Un servidor que ya no existe es una cancelación con éxito. Un 404 al eliminar significa cuatro cosas a la vez (ID desconocido, otra cuenta, no asignado a este miembro, o ya eliminado), y para un gancho de cancelación la acción correcta es idéntica en los cuatro casos: no queda nada que limpiar. Tratarlo como un error deja un servicio atascado en «terminating» para siempre.

Lo que deliberadamente no se automatiza

Fronteras honestas, porque estas son las preguntas que llegan después de que ya ha vendido algo:

• Sin facturación por uso. Las métricas por servidor se recogen y se muestran en el panel, pero todavía no se exponen por la API. Sin un endpoint no hay facturación medida. Si su producto es «paga por la RAM que usaste», hoy esto no lo hace.
• Sin cambio de plan en una sola llamada. Cambiar de plan tampoco es una única llamada de API a nivel de Pelican: es una reinstalación o un cambio de recursos, con consecuencias distintas para los datos del cliente.
• Sin restablecimiento de contraseña por la API. Las credenciales viajan de forma transitoria y no se almacenan nunca, así que no hay nada que reenviar.
• Sin inicio de sesión único desde su panel de facturación hacia el panel de Provibr.
• Sin bucle de reconciliación de inventario: un rechazo, no un hueco. La sincronización _ListAccounts de WHMCS cancela cualquier servicio que falte en la respuesta, y «que falta» tiene causas inocentes: un alcance de API más estrecho, un miembro restringido a parte del inventario, un límite de tasa, una página corta cuyo cursor no se siguió. Cada una eliminaría máquinas de clientes. En su lugar, el área de cliente lee el estado en vivo en cada carga de página, lo que no es sincronización y no pretende serlo.

El recuento de capacidad, y cómo se encuentra con la reclamación de pago

La facturación de la plataforma cuenta capacidad, no uso, con una regla que sorprende a todo el mundo el primer mes: cada servidor cuenta, esté en marcha o no. Solo un servidor suspendido no cuenta, y tampoco lo hace uno eliminado. Detener una máquina no libera una plaza.

Eso encaja perfectamente con la reclamación de pago. Un cliente al que suspende por impago deja de contar en su capacidad mientras esté suspendido, y vuelve a contar en cuanto paga y lo reactiva, de modo que no está pagando capacidad de plataforma por un cliente que no le paga.

Superar el límite no se bloquea en el momento en que lo hace. Se detecta, se le avisa, y dispone de un día laborable completo. Si esa gracia vence, los servidores más recientes por encima del límite se suspenden, los más recientes primero, para que sobreviva lo que construyó antes.

Hacer correr Pelican junto a todo lo demás

Un anfitrión de juegos que crece rara vez se queda en un solo panel. Provibr cubre sus paneles de control, sus hipervisores y sus paneles de juego en un solo panel de control, con una sola API y una sola cifra de capacidad para todos ellos.

POST /v1/servers/{id}/actions/suspend hace lo mismo tanto si debajo hay un servidor Pelican, un servidor Pterodactyl o una cuenta de alojamiento DirectAdmin. Las diferencias viven en el proveedor, no en su código de integración.