Venda alojamiento de Zinn® desde WHMCS

El módulo de Zinn Digital® convierte los propios botones de WHMCS en acciones reales en nuestra plataforma. Un pedido aprovisiona el alojamiento de su cliente. La automatización de facturas vencidas de WHMCS lo suspende. Marcar la factura como pagada lo reactiva. Cancelar programa la eliminación. Y su cliente obtiene un botón Iniciar sesión en el panel de alojamiento en su área de cliente que le permite acceder directamente.

Es gratuito, cuenta con licencia GPL-2.0-or-later y no dispone de ninguna vía privilegiada hacia nuestra plataforma: cada llamada que realiza es a un endpoint documentado que usted mismo podría efectuar con su propia clave de API.

Antes de comenzar

Necesita dos cosas, y la segunda suele tomar a la gente desprevenida.

1. Una cuenta de distribuidor de Zinn® con un programa activo. Regístrese en zinndigital.com y active la distribución.
2. Un plan de distribuidor con asignación de sitios. Los sitios que sus clientes solicitan cuentan contra su plan, por lo que necesita uno que disponga de espacio libre.

⚠️ Test Connection no puede indicarle si un pedido se completará con éxito. Lee su programa y no aprovisiona nada, por lo que informa de una cuenta active correcta que aún no puede vender nada. Si su primer pedido falla con «This organization has no hosting plan, so it cannot host a site yet», eso es lo que ha ocurrido: adquiera o amplíe su plan de distribuidor y vuelva a realizar el pedido. El módulo no tiene ningún problema.

1. Crear la clave de API

En su panel de control de Zinn®, abra API keys y cree una con exactamente estos once permisos:

⛔ No conceda reseller.manage. Una clave introducida en un panel de facturación debe ser capaz de retener a un cliente por impago e iniciar su sesión. No debería poder leer ni sobrescribir sus propias credenciales de la pasarela de pago. reseller.provision existe para que no tenga que conceder el permiso más amplio. ⛔ org.create no es opcional. Sin él, el módulo puede leer sus cuentas pero no puede abrir una nueva, por lo que Test Connection responde correctamente y el primer pedido devuelve un error 403. ⛔⛔ Conceda toda la tabla y tenga en cuenta que Test Connection no puede indicarle si no lo ha hecho. Lee su programa de distribuidor y no aprovisiona nada, por lo que se mostrará en verde para una clave a la que le falte cualquiera de ellos. Lo que obtendrá en su lugar es un error 403 en la única operación que cubre el permiso ausente, meses después, procedente de un cliente.

2. Instalar el módulo

1. Descargue el módulo y descomprímalo.
2. Suba el directorio zinn en su instalación de WHMCS de modo que el archivo del módulo quede en modules/servers/zinn/zinn.php.

⛔ El directorio debe llamarse zinn. WHMCS deriva los nombres de función de un módulo de aprovisionamiento a partir del nombre de su directorio, por lo que renombrarlo a zinn-whmcs o zinndigital genera un módulo que WHMCS lista, le permite seleccionar y luego nunca ejecuta, sin mostrar ningún error en ningún sitio. El archivo zip ya se descomprime con el nombre correcto; simplemente no lo modifique.

3. Añadir el servidor

En WHMCS: Configuración → Ajustes del sistema → Servidores → Añadir nuevo servidor.

• Nombre: cualquiera, p. ej. Zinn Digital®
• Nombre de host: api.zinndigital.com
• Tipo: Zinn Digital®
• Contraseña: su clave de API del paso 1

⛔ La clave se introduce en el campo Contraseña, el cual WHMCS almacena cifrado. No la introduzca en una opción de configuración de producto: estas se guardan en texto plano en la base de datos y son visibles para cualquier administrador, y esta credencial puede crear y destruir el alojamiento de sus clientes.

Pulse Test Connection. Realiza una llamada real y notifica lo que nuestra plataforma respondió, en lugar de limitarse a comprobar si los campos están completos.

4. Crear el producto

Configuración → Ajustes del sistema → Productos/Servicios, después establezca Ajustes del módulo en el servidor que acaba de añadir. Los campos son:

⛔⛔ El código del plan es obligatorio, y un pedido sin él se rechaza a propósito. Hasta el 2026-09-01 el campo era decorativo y nada lo leía, por lo que el módulo solicitaba alojamiento que no incluía ningún plan en absoluto, y todas las consecuencias de ello pasaban desapercibidas. Su estado de cuenta mayorista se genera a partir de las suscripciones activas de sus clientes, por lo que no existía ninguna línea para el servicio y no se le facturaba nada mientras estuviera en funcionamiento; su cliente no heredaba ninguna asignación, por lo que no se aplicaba cuota de disco o archivos a su sitio; y Change Package no tenía nada que cambiar, de modo que una ampliación que usted hubiera vendido no podía realizarse. El sitio se aprovisionó y funcionó a la perfección durante todo el tiempo.

El módulo ahora rechaza el pedido en su lugar, ya que no existe un plan seguro que pueda asumir de forma automática: una suposición aprovisionaría alojamiento en un plan que usted no eligió y para el cual tal vez no fijó un precio y, a diferencia de un rechazo, del cual se percata de inmediato, solo saldría a la luz cuando llegara un extracto, si es que lo hiciera.

Configure Configuración automática según su preferencia: el módulo es idempotente respecto al identificador del servicio de WHMCS, por lo que reintentar un aprovisionamiento devuelve el mismo sitio en lugar de facturarle por un segundo.

Qué hace cada acción de WHMCS

Mejoras: quién cobra a quién

A su cliente nunca le factura Zinn®, ni en un pedido ni en una mejora. Usted le factura a través de WHMCS; nosotros le facturamos a usted en su estado de cuenta mayorista. Por lo tanto, Change Package actualiza los derechos de su cliente y la línea en su próximo estado de cuenta, sin realizar cargos a ninguna tarjeta: WHMCS ya ha cobrado el dinero a su cliente y ha calculado su propio prorrateo.

El segundo servicio de un cliente. En el mismo plan, constituye otro sitio dentro de la propia asignación de sitios de dicho plan, y no se concede nada más. En un plan diferente, es rechazado: reemplazar el plan activo dejaría uno de los dos servicios sin facturar. Venda ambos en el mismo plan o registre al cliente como un registro de cliente independiente en WHMCS.

Cambiar contraseña existe únicamente para WordPress. El alojamiento de Zinn® no tiene una única «contraseña de servicio» (su cliente accede a su panel mediante el botón de inicio de sesión) y un sitio php o static no cuenta con una cuenta de aplicación que modificar. WHMCS oculta el cuadro por completo en lugar de mostrar uno que no puede funcionar.

Tres respuestas que no debe reducir a dos

• Reactivar puede responder con un rechazo. Esto significa que el sitio fue suspendido por nuestro equipo de abusos, no por usted, y ningún panel de facturación puede levantarlo. El mensaje así lo indica; muéstreselo a su administrador en lugar de reintentar.
• Dar de baja programa una eliminación, no la ejecuta de forma inmediata. La fecha se devuelve como pending_deletion_at y el área de cliente la muestra. Decirle a un cliente que sus datos ya han desaparecido cuando no es así resulta peor que no decirle nada.
• El disco y el ancho de banda pueden ser desconocidos, y desconocido no equivale a cero. Cuando no pudimos obtener una lectura, el módulo deja la cifra intacta en lugar de escribir 0; de lo contrario, WHMCS mostraría a su cliente una reconfortante barra de uso vacía para un sitio del cual no tenemos lecturas.

Resolución de problemas

Test Connection pasa con éxito y el primer pedido falla con un error de permisos. A la clave de API le falta org.create. El módulo debe abrir la cuenta del cliente antes de poder crear su sitio.

Un pedido falla indicando que la organización no tiene plan de alojamiento. Su plan de distribuidor no dispone de más asignación de sitios o aún no cuenta con uno. Consulte Antes de comenzar más arriba.

Un pedido falla mencionando un stack. El campo Stack del producto está vacío o indica algo que no compilamos. Establézcalo en wordpress a menos que esté vendiendo otra cosa.

Las cancelaciones están fallando. Asegúrese de estar utilizando la versión 1.0.0 o posterior del módulo. Las versiones anteriores no enviaban confirmación de eliminación y cada rescisión se rechazaba, lo que dejaba el servicio activo y facturándose.

Un rechazo que menciona un campo. Nuestros errores de validación indican el campo y el motivo entre corchetes tras el mensaje, p. ej. (php_version: 7.2 is not offered on this product line). Esa es la parte procesable: la frase que la precede es deliberadamente genérica.

Verifique su descarga

Cada archivo se suministra mediante TLS desde nuestro propio nombre de host y nunca se redirige a un alojamiento de terceros. Su suma de comprobación SHA-256 se muestra junto al enlace de descarga en la página de descargas. Compárela tras la descarga:

• macOS o Linux: shasum -a 256 zinn-whmcs-1.0.0.zip
• Windows: certutil -hashfile zinn-whmcs-1.0.0.zip SHA256

¿No utiliza WHMCS?

Existe un módulo para HostBill y un cliente PHP de un solo archivo para cualquier otro entorno, ambos gratuitos y disponibles en la misma página de descargas. Cada endpoint que utilizan los módulos se detalla en la referencia de la API.