Automatizar la facturación con Virtualmin

Dos preguntas deciden si un panel de alojamiento puede sostener clientes de pago: ¿se convierte un pedido en una cuenta activa sin que la toque, y una factura impagada cambia realmente algo en el servidor?

Esta página responde a las dos para Virtualmin, en concreto: qué comando de Virtualmin hay detrás de cada paso, qué se almacena dónde, y dónde se detiene la automatización deliberadamente. Todo se midió contra una instalación real de Virtualmin GPL 8.1.2.

Del pedido a la cuenta

Un pedido necesita cuatro cosas: un dominio, una dirección de correo, un plan y una contraseña.

El plan es el punto interesante. Un plan web de Provibr fija exactamente un plan de Virtualmin sobre exactamente una integración y le da un nombre propio. Esa indirección existe porque un plan de Virtualmin es la descripción que el panel tiene de una cuenta (cuota de disco, tráfico mensual, número de buzones y de dominios, qué funciones están activadas), y su contenido puede cambiar en su máquina sin que nos lo digan. Así que nos referimos a él por su nombre y volvemos a leer lo que realmente pasó, en lugar de guardar en caché lo que creemos que significa.

Entre bastidores, el pedido ejecuta create-domain en el panel con el dominio, el plan y la contraseña. Luego:

Vale la pena conocer dos detalles del paso de creación.

El usuario unix viene del dominio. mi-cliente.es se convierte en mi-cliente. Los guiones son aquí la forma normal, y el techo es el de Linux mismo: 32 caracteres, a diferencia de DirectAdmin y cPanel, que imponen sus propias reglas de nombrado más estrictas. No elige el nombre de usuario; el panel lo deriva.

La contraseña no se registra nunca. Provibr conserva el hecho de que se suministró una, no el valor. La contraseña viaja separada del rastro de auditoría que registra el pedido, así que una contraseña de cuenta de alojamiento no existe en ningún lugar del historial de la plataforma. Si la pierde, la restablece; no la consulta.

Qué se almacena dónde

Una cuenta de alojamiento se convierte en una fila de servidor corriente, de tipo webserver. Su identificador es el número interno que Virtualmin atribuye al dominio, no el nombre.

Esa elección es deliberada e importa para la facturación. Virtualmin puede renombrar un dominio, y un cliente o un administrador acabará haciéndolo. Una clave basada en el nombre se suelta de su fila la primera vez que eso ocurre: su factura sigue cobrando por algo que la plataforma ya no encuentra. Un identificador numérico sobrevive al renombrado.

La frontera de la cuenta es el usuario unix, no el dominio. Los subservidores y los alias bajo una misma cuenta caerían si no cada uno en el recuento de capacidad como una cuenta de alojamiento distinta, y estaría pagando capacidad de licencia por alias.

⚠️ Hay aquí un paso de traducción fácil de errar si construye esto por su cuenta. Los programas de mutación de Virtualmin (disable-domain, enable-domain, modify-domain) aceptan solo --domain como selector. Lo medimos en 8.1.2: no existe un selector --user. Pero la plataforma direcciona las cuentas por nombre de usuario, porque eso es la identidad de la cuenta. La traducción corresponde al agente, que hace una búsqueda acotada en el panel para resolver el dominio actual, y no a la plataforma, que tendría que mantener una copia de sus nombres de dominio y apuntaría en silencio al dominio equivocado la primera vez que alguien renombra uno fuera de Provibr.

(Trampa vecina: modify-domain --user significa renombrar, no seleccionar. Ese parámetro nunca se envía.)

El modelo de capacidad, en un párrafo

Se compra capacidad por tipo de recurso (máquinas virtuales, máquinas dedicadas, cuentas de alojamiento, servidores de juego), y es un límite y un precio al mismo tiempo. Cada cuenta cuenta, esté en marcha o no. Solo una cuenta suspendida no cuenta, y tampoco lo hace una eliminada. Detener algo, por tanto, no libera una plaza: elimínelo, o suba su capacidad. Subir surte efecto de inmediato y el extra por el resto del periodo se prorratea en su siguiente factura; bajar también surte efecto de inmediato, y la parte no utilizada vuelve como crédito.

Las cuentas importadas cuentan exactamente igual que las pedidas. Adoptar un panel lleno de clientes existentes es una decisión de capacidad, no una acción gratuita.

Qué hace una factura impagada

Su organización lleva un solo estado de licencia: activo, gracia o suspendido. Dos cosas separadas pueden moverlo (un pago pendiente y un exceso), y cuando ambas se aplican, la más estricta gana, para que el banner no alterne entre dos relatos.

El camino de la prueba es el ejemplo más claro de la forma. Una organización nueva corre sobre una prueba de dos semanas sin que se pidan datos de pago y con todo funcionando. Cuando termina sin un método de pago se le avisa, y todavía no cambia nada. Una semana después, el panel empieza a advertir. Dos semanas después de terminar el periodo, los servidores se suspenden. Cada paso se anuncia antes de producirse: esa es la regla en torno a la cual está construido todo el calendario, no una cortesía añadida encima de él.

Para una suscripción en marcha el mecanismo es el mismo: el estado pasa a gracia antes de pasar a suspendido, el banner nombra la causa, y la solución está enlazada desde él. Una suspensión por pago y una suspensión por capacidad se ven y se leen distinto, porque necesitan cosas diferentes de su parte.

Qué hace la suspensión en el panel

Cuando la plataforma suspende una cuenta de alojamiento, envía disable-domain. Virtualmin bloquea la contraseña del usuario de administración y reemplaza el sitio web por una página de error. Los datos se quedan.

Tres propiedades de ese flujo vale la pena detallar, porque son las que separan una automatización de verdad de un script que lo parece.

La fila se marca como suspendida solo después de que el agente lo confirme. Enviar un comando no es lo mismo que haya ocurrido. Si la plataforma marcara la fila en el envío, una suspensión fallida dejaría una cuenta activa contada como «no cuenta para tu límite», el mismo error contable que la aplicación existe para evitar.

Un agente sin conexión significa aplazado, no hecho. Si no se puede alcanzar al agente, la aplicación se omite, se escribe un evento diciéndolo, y la ronda siguiente vuelve a intentarlo. Nada se marca en silencio como completado.

Leer el resultado es una lectura fresca, no la propia respuesta del comando. disable-domain devuelve un muro de texto de progreso (Locking administration user's password .., Replacing website with error page ..), y ese texto es una cita, no un contrato. El estado viene de un list-domains fresco hecho después. Esta es una regla de la casa en todos los paneles que integramos: no se cree ninguna mutación sobre su propia respuesta.

Esa última regla es lo que hace correcta la detección de suspensión siquiera, y esta es la razón medida. Sobre una cuenta suspendida, list-domains gana un campo llamado disabled. Sobre una cuenta activa ese campo simplemente está ausente: no existe un disabled: "No". Un analizador que busca un valor no encuentra nada y lee todas las cuentas como activas, incluidas las suspendidas. En un contexto de facturación eso no es cosmético: una cuenta que suspendió por impago se declararía activa, y su recuento de capacidad estaría equivocado en el sentido que le cuesta dinero.

Superar el límite

Hacer correr más cuentas de las que compró no se bloquea en el momento en que lo hace. Se detecta, se le avisa, y se le da tiempo.

1. 01El exceso se detecta. Recibe una notificación y un banner que nombra el tipo de recurso y por cuánto.
2. 02Dispone de un día laborable completo para corregirlo: eliminar cuentas, o subir su capacidad.
3. 03Si el periodo de gracia vence, la plataforma suspende las cuentas más recientes por encima de su límite. Las más recientes primero, para que sobreviva lo que construyó antes. Una cuenta suspendida conserva su disco y sus datos.
4. 04En cuanto vuelve a estar dentro de su límite, el exceso se cierra.

Un segundo exceso dentro de una semana obtiene una hora en lugar de un día. Sin eso, el periodo de gracia podría renovarse indefinidamente bajando por debajo del límite y volviendo a superarlo.

⚠️ Nada se arranca en su lugar cuando el exceso se resuelve. Encender una cuenta de nuevo es una decisión, y la plataforma no la toma mientras nadie mira. La reactiva por su cuenta, y eso envía enable-domain.

Detrás del paso 4 hay una pequeña aritmética fácil de tomar al revés. El exceso se considera resuelto cuando las cuentas que cuentan más las cuentas suspendidas por este exceso vuelven a estar dentro del límite, no solo el primer número. Sin esa suma, la aplicación se declararía resuelta en el instante mismo en que actúa, porque el recuento baja por debajo del límite precisamente al suspender.

Lo que nunca es automático

Eliminar. Ninguna factura impagada, ningún exceso y ninguna prueba expirada elimina una cuenta de alojamiento. La suspensión conserva el disco y los datos; la eliminación es una acción distinta y explícita que realiza por su cuenta. El único paso destructivo del ciclo de vida es justamente el que la plataforma no dará en su lugar.

Liquidación parcial con crédito. Puede recargar por adelantado, y el saldo es un libro mayor: una línea por cada movimiento, nunca editada, las correcciones son líneas opuestas con un motivo en lugar de reescrituras. Si el saldo cubre el mes entero, el mes se paga con crédito y no se cobra nada. Si no lo cubre, se cobra el importe completo y el saldo se deja intacto. No hay medias tintas.

Reescribir el historial. Una línea de factura registra el nombre del plan tal como estaba en el momento de facturar. Renombrar algo más adelante no cambia lo que dice una factura antigua.

Dónde le deja esto

Virtualmin le da un panel de alojamiento sólido y ninguna capa comercial en absoluto. La brecha no es el aprovisionamiento (create-domain es un solo comando); es todo lo que lo rodea: contar lo que un cliente tiene, saber que una factura quedó impagada, hacer algo al respecto que sea reversible, y poder explicar después qué pasó y cuándo.

Provibr se conecta a paneles de control, hipervisores y paneles de juego unos junto a otros. El modelo de facturación de arriba es el mismo en todos, que es el argumento práctico para un anfitrión pequeño: la máquina Virtualmin que ya hace correr sigue funcionando exactamente como hoy, y el VPS o el panel de juego que añada el año que viene aterriza en el mismo recuento de capacidad, la misma factura y el mismo flujo de suspensión.