Automatizar la facturación con WISP

WISP suspende un servidor cuando se le pide, y hace que esa suspensión se sostenga: un cliente que todavía tiene credenciales del panel no puede pulsar arrancar. Lo que WISP no tiene, y nunca pretende tener, es la menor idea de si ese cliente pagó.

Esta página trata de la capa que va en medio. También cubre lo único que distingue a WISP de los demás paneles de juego que hay aquí, y que no tiene nada que ver con su API: el panel no es suyo.

El panel está alojado, el nodo es suyo

WISP se vende como un servicio alojado. wisp.gg hace correr el panel; el nodo que lleva sus servidores de juego corre sobre su propio hardware. Un agente dentro de su red habla hacia fuera con el panel a través de su API, y con el demonio de su nodo para la consola, así que no hay que abrir nada hacia internet.

Para una integración de facturación esa división tiene una consecuencia real: no hay nada que actualizar ni nada que fijar. WISP puede cambiar su API sin que medie una versión bajo su control. Provibr está probado contra la v3.7.5 y lee la versión en marcha del propio panel, así que la deriva aparece en la prueba de conexión y no en un pedido fallido a las dos de la madrugada.

Un detalle relacionado que conviene conocer antes de culpar al código propio. La puerta de entrada del panel está detrás de un desafío de Cloudflare; toda ruta /api/… pasa de largo. Se midió con tres agentes de usuario distintos y los tres respondieron 200. Es un ajuste de wisp.gg, no suyo ni nuestro, así que si algún día WISP pone el mismo desafío sobre la API, todas las integraciones de WISP se paran a la vez y no hay nada que arreglar localmente. El fallo tiene una forma reconocible (403, una cabecera Cf-Mitigated: challenge y HTML en lugar de JSON) y merece un mensaje propio, para que el panel diga no nos deja entrar y no clave equivocada.

El ciclo de vida, en correspondencia

Cinco acciones, y las cinco responden con un 204 vacío. En el cuerpo no hay literalmente nada, así que la regla de la casa se aplica sin excepción: ninguna mutación se fía de su propia respuesta. Después hay que volver a leer el servidor.

La suspensión es de verdad, y es idempotente

Esa combinación es más rara de lo que debería entre los paneles de juego, y es toda la razón por la que un ciclo de reclamación de pago sobre WISP resulta aburrido en el buen sentido.

Una segunda suspensión sobre un servidor ya suspendido vuelve a responder 204. Nada que tratar como caso especial, nada que interpretar como «ya estaba así», ningún error que tragarse. Compárese con los paneles de control donde suspender dos veces es un error de autenticación, y se ve cuánto de una integración de reclamación de pago se dedica normalmente a pedir perdón por el panel.

Eliminar funciona también sobre un servidor suspendido, lo que importa para la cancelación que llega un mes después de la suspensión. Una segunda eliminación responde 404, que es el resultado correcto para un gancho de baja: no queda nada que limpiar.

Las reglas de estado del lado de Provibr son más estrictas que las del panel, a propósito:

Conviene leer dos veces la fila de la suspensión. Se puede suspender un servidor que ya está detenido, y también uno que todavía se está instalando. Si la suspensión solo funcionara sobre servidores en marcha, un cliente podría detener su propio servidor, dejar de pagar y quedar intocable. Una aplicación de la regla que se esquiva pulsando «detener» no es aplicación de nada, y una cancelación que llega a mitad de instalación no debería tener que esperar a que la instalación termine.

Dos claves, sin prefijo, y el error que viene detrás

WISP conserva la división de Pterodactyl entre dos superficies de API, y ninguna clave por sí sola cubre las dos. La clave de aplicación construye, suspende, reinstala y elimina; la clave de cliente se encarga del encendido, de las estadísticas en vivo y de la consola. Las dos se crean sobre una cuenta de administrador.

Y aquí está la trampa. Las claves de WISP no llevan prefijo, a diferencia del ptla_ de Pterodactyl o del papp_ de Pelican: son 48 caracteres sin una cabeza reconocible, así que nada puede avisar de que se han pegado al revés. Nosotros no, y el panel tampoco, porque WISP responde a una clave equivocada con un 403 y un mensaje vacío. Un 403 normalmente significa esta clave no tiene permiso para eso, así que un cliente que ha intercambiado las dos claves entra en el panel y se pone a marcar permisos que nunca fueron el problema. Si la prueba de conexión falla, lo primero es intercambiar las dos claves, antes de tocar cualquier otra cosa.

La otra mitad de esa credencial merece una frase en el manual de operaciones propio: la clave de aplicación no es solo gestión de servidores. El mismo listado de nodos que lee una integración lleva también la clave de licencia de su nodo y el token de su demonio. Conviene tratarla como una credencial de todo el panel, y revocarla en WISP si algún día se desconecta la integración.

Nada es instantáneo, y la API lo dice

Su panel vive en su propia red y el agente marca hacia fuera, así que 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"
  }
}

Eso es un 202 Accepted, no un 200. Luego se lee ese comando hasta que su estado sea definitivo: done, failed, timed_out o cancelled. La lectura nunca funciona así, porque un inventario o una factura sale de una base de datos y no de su host.

Todo lo que crea algo acepta una Idempotency-Key de su propia cosecha. Basta con derivarla de algo estable del lado propio, como el identificador de la factura más la fase de reclamación de pago, y entonces una tarea programada cada quince minutos, un webhook reintentado y un administrador que hace clic dos veces se vuelven inofensivos.

Dos formas que rompieron esta integración antes de que llegara a sus manos

Las dos merecen una lectura aunque nunca se toque WISP, porque las dos son de esa clase de fallo que informa de éxito.

Toda identidad es una cadena con prefijo, no un número. Un servidor de WISP es server_01m0n8m94afcj2kk5mzt9z379q; los nodos, los eggs y las asignaciones tienen el mismo aspecto. La plataforma comprobaba que el identificador externo de un servidor de juego fueran letras y dígitos, lo cual es cierto en todos los demás paneles de juego y falso aquí. El resultado no fue un mensaje de error: los clientes de WISP por encima de su límite se comunicaban al proceso que aplica la regla y luego se saltaban, en cada ronda, para siempre. Quedaban señalados y no se suspendían nunca. Ahora una única comprobación de identidad compartida cubre las dos formas.

Un peso de disco de cero se rechaza. WISP exige limits.io y pide un valor entre 10 y 1000. El campo del plan en la plataforma vale cero por defecto, así que todo pedido de WISP habría terminado en un 422 sobre un campo del que la mayoría de la gente no ha oído hablar jamás. Ahora hay dos vallas: el formulario del plan rechaza el cero y dice por qué, y el agente sube un cero al peso por defecto antes de enviarlo. Dos vallas para un solo error es deliberado, porque una de ellas está del lado que se ve.

Lo que no se puede ver, y no conviene fingir

Esta es la parte honesta, y es corta.

• No hay campo de estado en un servidor de WISP. Pterodactyl sí lo tiene, con installing e install_failed dentro. WISP tiene suspended y container.installed, los dos booleanos. Una instalación fallida tiene por tanto exactamente el mismo aspecto que una en curso: installed sigue en falso en los dos casos. En construcción y roto son la misma imagen sobre esta superficie, y un producto que afirme otra cosa está adivinando.
• Un nodo no informa de su propia ocupación. El campo que otros paneles usan para eso no está, ni siquiera cuando se pide de forma explícita. La ocupación se suma a partir de los servidores, lo cual funciona y cuesta una llamada más.
• No hay tiempo de actividad en las estadísticas en vivo. Un contenedor que se reinició entre dos sondeos no se puede reconocer con certeza. En el otro platillo, WISP no guarda esas estadísticas en caché durante veinte segundos como hace Pterodactyl, así que las gráficas no inventan una caída que nunca ocurrió. En el balance sale mejor, con un borde afilado.

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

Provibr le factura la capacidad, no a sus clientes. Lo que cobre por un servidor de juego se queda enteramente dentro de su propio sistema de facturación; nosotros nunca vemos una factura de cliente y nunca hablamos con sus clientes.

La regla que pilla a todo el mundo el primer mes: todo servidor cuenta, esté en marcha o no. Uno suspendido no, y uno eliminado tampoco. Detener una máquina no libera nada.

Eso encaja con la reclamación de pago de una forma bastante limpia. Al suspender a un cliente por impago deja de contar contra su capacidad en ese mismo momento; al reactivarlo cuando paga, vuelve a contar. No se paga capacidad de plataforma por alguien que no paga.

Lo que deliberadamente no se automatiza

Provibr gestiona servidores, no el panel. No instala WISP, no toca el demonio de su nodo más allá de la consola, y no gestiona copias de seguridad, reglas de cortafuegos ni asignación de IP en este proveedor: esas capacidades están apagadas en el registro en lugar de implementadas a medias. No hay facturación por uso medido sobre WISP, porque las estadísticas por servidor se muestran en el panel y no se exponen por la API, y no se puede facturar contra un endpoint que no existe.

Si todavía está en fase de elegir, la comparación que conviene leer primero es Elegir un panel de juego por su API, que mide seis paneles sobre exactamente una pregunta: si una suspensión hace algo. La conexión en sí, las dos claves y el campo de la huella están cubiertos en la página de la integración con WISP.