API e integraciones

La interfaz web y la API son lo mismo: la interfaz llama exactamente a la API que se expone a las integraciones, sin atajos privilegiados. Todo lo que se puede hacer en pantalla está disponible por HTTP.

Tokens de API

Los tokens son para integraciones desatendidas (sistemas de facturación, scripts). Sólo los administradores pueden crearlos.

En la interfaz de administración, abra Panel → Tokens de API.
Asigne al token un nombre y una fecha de vencimiento (obligatoria, como máximo un año).
Copie el token. Se muestra una sola vez; el panel guarda sólo un hash. Si lo pierde, revóquelo y cree otro.

Úselo como token portador contra el puerto de administración (la API no se expone en un puerto separado):

curl -sS -H "Authorization: Bearer <token>" https://panel.ejemplo.com:2087/api/conexion

Las solicitudes sin ese encabezado reciben 404. La cookie del navegador nunca se acepta en /api/.

Puede revocar un token en cualquier momento desde la misma pantalla; deja de funcionar de inmediato. Restablecer la clave o el segundo factor del administrador que lo creó también revoca sus tokens. Los tokens que no se usan vencen como cualquier otro; un token vencido que fue real no se cuenta como ataque.

Qué puede y qué no puede hacer un token

Un token nunca recibe, ve ni fija la clave o el segundo factor de nadie. Las operaciones que crean o mueven credenciales, o que abren una sesión sobre algo (terminal, casilla, base, suplantación), responden 403 con "esta operación no se puede hacer con un token de API: ingrese al panel". Todo lo demás que puede hacer un administrador está permitido, incluidos crear y suspender clientes.

Crear un ingreso para un cliente se hace así:

Un token puede crear el ingreso sólo para una cuenta que a su vez fue creada por un token, sólo con el rol cliente, y sólo si la cuenta todavía no tiene ingreso.
El ingreso se crea sin clave. El cliente recibe un correo con un enlace de un solo uso (válido una hora) para elegir su clave y dar de alta su segundo factor. El enlace no lo consume un escáner de enlaces que sólo lo abre; se gasta al enviar la nueva clave.
Un restablecimiento de clave desde una integración envía un enlace nuevo a la dirección de recuperación guardada en la cuenta. Cambiar esa dirección requiere a una persona con su propia clave.

Ejemplos

Los nombres de los campos son los de la API (identificadores en español):

H="Authorization: Bearer <token>"
B=https://panel.ejemplo.com:2087/api

# crear un cliente y luego un sitio
curl -sS -H "$H" -H 'Content-Type: application/json' -d '{"cliente":"acme"}' $B/clientes
curl -sS -H "$H" -H 'Content-Type: application/json' \
  -d '{"cliente":"acme","domain":"ejemplo.com","aliases":["www.ejemplo.com"]}' $B/sitios

# asignar un plan
curl -sS -H "$H" -H 'Content-Type: application/json' -d '{"plan":"basic"}' $B/clientes/acme/plan

# suspender / reactivar (estas acciones FIJAN un estado; repetirlas es seguro)
curl -sS -H "$H" -X POST $B/clientes/acme/suspender
curl -sS -H "$H" -X POST $B/clientes/acme/activar

# consumo frente al plan
curl -sS -H "$H" $B/clientes/acme/uso

Los listados se paginan por cursor (GET /clientes?desde=<ultimo>&limite=200; el límite tiene un tope duro de 200).

Los códigos de error tienen el mismo significado que en la interfaz: 402 función paga, 403 no permitido u operación restringida para tokens, 409 conflicto o falta un requisito previo (por ejemplo "esta cuenta vive en el nodo X"), 429 esperar antes de repetir, 507 cuota de disco o de inodos agotada. Ver las Preguntas frecuentes.

WHMCS

Se incluye un módulo de servidor para WHMCS en el directorio integraciones/whmcs de la versión. Es PHP puro, sin Composer; requiere la extensión curl.

Copie modules/servers/controlpanel/ dentro de modules/servers/ de WHMCS.
Cree un token de API como se indicó arriba (póngale el nombre "WHMCS").
En WHMCS: Configuración → Productos/Servicios → Servidores → Agregar nuevo servidor, tipo controlpanel. Hostname panel.ejemplo.com:2087 (sin https://; el módulo siempre usa HTTPS), Contraseña = el token (WHMCS lo guarda cifrado). Deje vacíos Usuario y Hash de acceso. Probar conexión debe funcionar.
En el producto, Configuración del módulo → Plan: el nombre exacto de un plan que exista en el panel (vacío = sin plan).

El correo del cliente debe estar cargado en WHMCS antes de crear la cuenta: ahí se envía el enlace de activación.

Acción en WHMCS	Qué hace el panel
Crear	Crea el cliente y el sitio, asigna el plan, envía al cliente un enlace para activar su ingreso
Suspender / Reactivar	Fija suspendido / activo (idempotente)
Terminar	Elimina el cliente; "ya no existe" cuenta como éxito, un error de red no
Cambiar paquete	Asigna el nuevo plan
Cambiar contraseña	Envía al cliente un enlace de restablecimiento (la contraseña escrita en WHMCS se ignora)
Área de cliente	Muestra el plan y el uso actual, sólo lectura

El TLS siempre se verifica. Mientras el certificado del panel sea autofirmado, instálelo en el almacén de confianza del servidor que ejecuta WHMCS; no hay ninguna opción para omitir la verificación. El módulo todavía no se probó contra un WHMCS de producción; pruébelo primero en un WHMCS de staging.

Cloudflare

Puede replicar sus zonas DNS en Cloudflare como secundario. El DNS propio del panel es siempre la fuente de verdad; Cloudflare es sólo una copia, y los cambios hechos en Cloudflare se sobrescriben con la siguiente sincronización.

Sólo administrador, una cuenta de Cloudflare por nodo (DNS → Cloudflare). La cuenta pertenece al operador de hosting que administra el nodo, no a cada cliente final. Un cliente que quiera su propia cuenta de Cloudflare sólo cambia los servidores de nombres en su registrador y quita la zona del nodo.
Cree un token de API de Cloudflare limitado a las zonas y permisos necesarios, péguelo una vez; se guarda cifrado y nunca se muestra ni se registra. El panel no puede verificar el alcance de un token, así que dele el alcance más acotado posible.
Usted elige zona por zona cuál replicar. No hay un interruptor de "replicar todo".
Sólo se pueden replicar las zonas que ya resuelven a este servidor; se verifica contra un resolutor recursivo (no el DNS propio del panel) y se vuelve a comprobar a diario. Una zona que deja de apuntar aquí se quita de la réplica y sus registros se eliminan de Cloudflare.
Una zona que ya existe en su cuenta de Cloudflare se rechaza, no se adopta: la sincronización borraría cualquier registro que no esté en el panel.
El panel avisa sobre la cuota de zonas de la cuenta antes de que se llene, leyendo el límite desde la propia cuenta.
Sincronizar ahora encola la zona; la cola procesa aproximadamente una zona por minuto.
Una falla de Cloudflare nunca afecta a su propio DNS.