Instalar y configurar WHMCS para trabajar con el sistema de facturación HOSTKEY¶

En este artículo

• Software requerido
• Instalación del módulo
• Activar el módulo en WHMCS
• Carga y eliminación de información de HOSTKEY mediante comandos de consola
• Configuración de divisas para la exportación de precios
• Personalizar productos específicos para reventa
• Editar un producto específico
• Activación de pago para productos pedidos
• Ejemplos y consejos
• Errores típicos y soluciones

Software requerido¶

• reseller module para WHMCS: download;
• WHMCS versión 8.8 o superior.

Instalación del módulo¶

Extraiga el contenido del archivo en la raíz del sistema de contabilidad.

1. Descargue y descomprima el archivo del módulo en la raíz de WHMCS

   Extraiga el contenido del archivo en la raíz del sistema de contabilidad.

   WHMCS root es donde se encuentran los archivos configuration.php y las carpetas vendor/, modules/, includes/.

   Vía SSH:

   cd /path/to/your/whmcs
   

   unzip /path/to/HostkeyResellerMod.zip
   

   Vía FTP: Suba el contenido del archivo a la raíz de WHMCS, aceptando la fusión (merge) de las carpetas.

2. Compruebe la estructura tras el desempaquetado

   Deberían aparecer los siguientes elementos:

   • modules/addons/hostkeyresellermod/
   • modules/servers/hostkeyresellermod/
   • modules/gateways/callback/hostkeyresellermod.php
   • includes/hooks/hostkeyresellermod.php

   Archivos clave:

   • modules/addons/hostkeyresellermod/hostkeyresellermod.php
   • modules/addons/hostkeyresellermod/cron.php
   • modules/addons/hostkeyresellermod/clean.php
   • modules/addons/hostkeyresellermod/import.ini (opcional)

3. Refresque su sesión del panel de administración

   Cierre la sesión y vuelva a entrar en el panel de administración de WHMCS. Limpie la caché de su navegador si es necesario.

Problemas comunes al copiar¶

• Archivos en la carpeta incorrecta: El módulo no aparecerá en la lista si se encuentra en una subcarpeta en lugar de en la raíz de WHMCS.
• Permisos/Propietario: Los permisos incorrectos impiden la activación o visualización.
• Caché del navegador/sesión: Volver a iniciar sesión resuelve el problema de "el módulo no es visible".

Activar el módulo en WHMCS¶

1. Abra la lista de módulos addon

   Después de copiar el módulo al directorio de WHMCS y configurar los permisos del sistema de archivos, debe activar el módulo. Para ello:

   • Ruta: System Settings > Apps & Integrations > Addon Modules.
   • Busque HOSTKEY VPS/Dedicated.

   

2. Active el módulo y vaya a la configuración

   • Haga clic en Activate.
   • Luego en Configure (o Settings) para abrir el formulario de configuración.

   

3. Complete la configuración del módulo y guarde

   Campos:

   • API Url — Dirección de la API de facturación de HOSTKEY:
   • Internacional: https://invapi.hostkey.com/ (por defecto).
   • API key — Clave de acceso a la API de HOSTKEY. Obténgala siguiendo estas instrucciones; manténgala en secreto.
   • Preset name prefix — Prefijo de nombre (por defecto HKP-) para distinguir visualmente los productos de HOSTKEY en las listas de WHMCS.
   • Default product group — Grupo de productos de WHMCS para los productos creados (por defecto Hostkey servers).
   • Logging of requests to Hostkey API — Actívelo para depuración si es necesario.

   Haga clic en Save Changes.

   

4. Configure el acceso (Access Control)

   Marque los grupos de administradores que necesiten acceso al módulo (recomendamos habilitar "Administrators").

   Atención

   Si no marca ningún grupo en Access Control, el módulo no estará disponible para ese grupo y no se mostrará en el menú Addons, incluso para el administrador.

   Si todo se ha realizado correctamente (incluida la configuración de permisos), la sección HOSTKEY VPS/Dedicated aparecerá en el menú Addons.

5. Abra el módulo y configure la importación de productos

   Vaya a Addons > HOSTKEY VPS/Dedicated y seleccione los productos que desea revender:

   • Import VPS products — para VPS/VDS;
   • Import Bare metal products — para servidores dedicados;
   • Import GPU products — para servidores con GPU.

   Para cada categoría marcada, establezca el margen (markup) y el formato:

   • En porcentaje: introduzca el valor y deje "%" (ejemplo: "10 %").
   • En moneda fija: introduzca el valor y seleccione la moneda de WHMCS (ejemplo: "5 USD").

   Seleccione el modo de redondeo en Round price to:

   • Not round — sin redondeo.
   • 0.1, 0.2, etc — hasta los décimos.
   • 0.25, 0.5, 0.75 — hasta los cuartos.
   • 0.5, 1.0 — hasta la mitad.
   • 1.0 — a números enteros.

   

   Luego haga clic en el botón ImportProduct/AdjustPrice.

   Nota

   Para la primera ejecución, recomendamos utilizar otro método, ya que al cargar una gran cantidad de información, la página puede terminar con un código 504. La primera vez que realice una importación masiva, puede haber un tiempo de carga prolongado; si aparece el error 504, utilice la importación por consola.

6. Descarga exitosa y qué hacer a continuación

   Si el módulo está correctamente conectado y activado, aparecerá un mensaje sobre la descarga exitosa de los productos de HOSTKEY y una sugerencia para ir a la configuración específica del producto en el menú System Settings > Product/Services.

   

   Vaya a Product/Services:

   • Compruebe los grupos y productos creados.
   • Si es necesario, abra el producto, establezca precios/periodos en la pestaña Pricing; en la pestaña Details, desmarque Hidden para que el producto se muestre en la vitrina (showcase).

   

   Nota

   En caso de una gran cantidad de información, la página puede finalizar con el código 504 Gateway Timeout. Para la primera carga de la lista de productos, recomendamos ejecutar el comando en la raíz de la facturación.

Carga y eliminación de información de HOSTKEY mediante comandos de consola¶

Ejecución de cron.php¶

Se utiliza para cargar la información desde Hostkey. Ejecute el comando desde la raíz de su sitio web:

php modules/addons/hostkeyresellermod/cron.php

Ejecución de clean.php¶

Elimina la información recibida previamente de HOSTKEY. Ejecute el comando desde la raíz de su sitio web:

php modules/addons/hostkeyresellermod/clean.php

Importante: import.ini tiene prioridad sobre la configuración del administrador¶

Si existe un archivo import.ini en modules/addons/hostkeyresellermod/, la importación se basará en la configuración de este archivo y sobrescribirá/ignorará la configuración especificada a través del panel de administración en la página Addons > HOSTKEY VPS/Dedicated.

Recomendamos el uso de import.ini si la importación a través de la interfaz web es inestable (se congela, error 504) o cuando se ejecuta la importación mediante cron/consola.

Si desea configurar la importación a través del panel de administración, elimine o renombre import.ini:

rm modules/addons/hostkeyresellermod/import.ini

Tras eliminar/renombrar el archivo, la importación volverá a utilizar los valores especificados en el panel de administración.

Parámetros en import.ini¶

Durante su funcionamiento, el comando utiliza el archivo modules/addons/hostkeyresellermod/import.ini (si existe).

Parámetros en import.ini:

• template = 5 — reemplace 5 con el ID de la plantilla de correo deseada de WHMCS (puede verla en la sección Email Templates)
• round = 0 — redondeo de precios (0 = no redondear, 10 = hasta 0.1, 4 = hasta 0.25, 2 = hasta 0.5, 1 = hasta 1.0)
• vps = 10 % — margen para VPS
• bm = 50 USD — margen para Bare metal
• gpu = 100 RUB — margen para GPU

Ejemplo de import.ini:

[general]
round = 0
template = 5
[markup]
vps = 10 %
bm = 50 USD
gpu = 100 RUB

El archivo tiene dos secciones:

1. La sección general contiene el parámetro round, que controla el redondeo. Valores posibles para el parámetro:

   • 0 — sin redondeo;
   • 10 — redondeo al décimo más cercano;
   • 4 — redondeo al cuarto más cercano;
   • 2 — redondeo a la mitad más cercana;
   • 1 — redondeo al número entero más cercano.

2. La sección markup contiene el margen porcentual para cada grupo.

   Si el archivo import.ini no existe o se utiliza la opción default, no se aplicará ningún margen ni redondeo.

Actualización automática de presets (cron)¶

Recomendamos programar una tarea una vez al día, durante las horas de menor actividad.

Ejemplo de crontab (cada día a las 03:30; reemplace las rutas de whmcs por las suyas):

30 3 * * * /usr/bin/php /path/to/whmcs/modules/addons/hostkeyresellermod/cron.php >/dev/null 2>&1

Consejos de programación: consulte brevemente sobre cron, asistente — crontab.guru.

Configuración de divisas para la exportación de precios¶

Para exportar con precisión los precios de los productos, debe configurar los tipos de cambio relativos al EUR o USD y entre ellos. Esto puede hacerse en la sección Payments >> Currencies.

Personalizar productos específicos para reventa¶

Al ir a System Settings >> Product/Services verá una tabla con todos los productos disponibles para su reventa.

Al hacer clic en los iconos de las columnas de la derecha, puede cambiar la configuración del producto o eliminarlo de la lista. La mayoría de los ajustes están determinados por la configuración de WHMCS y nosotros solo nos enfocaremos en aquellos que son críticos para la reventa.

Editar un producto específico¶

Hacer clic en el icono Edit le llevará a la sección de modificación de parámetros de Edit Product.

Pestaña Detail¶

Esta pestaña le permite cambiar el nombre del producto que se mostrará en su tienda.

También, al marcar la opción Hidden, puede ocultar el producto del formulario de pedido sin eliminarlo.

Pestaña Price¶

Utilice esta pestaña para establecer el precio de su producto en las divisas disponibles para usted.

Puede configurar tres tipos de pago (Payment Type):

• Free - el producto se distribuye sin coste;
• One Time - pago único por un mes de uso;
• Recurring - pago recurrente por un periodo de tiempo.

Establece el precio para cada periodo y moneda por separado, lo que le da la flexibilidad de ajustar su política de precios:

• One Time/Monthly - Pago único o pago mensual recurrente.
• Quarterly - pago trimestral (cada 3 meses)
• Semi-annual - pago semestral (cada 6 meses)
• Annual - Pago por un año (12 meses)

Tiene dos precios distintos disponibles:

• Setup Fee - el precio por la instalación del producto;
• Price - el precio de venta del producto.

Después de cambiar los parámetros y el precio, haga clic en Save Changes y guarde la configuración para este producto.

Tras confirmar el guardado exitoso de la configuración, haga clic en el botón en la esquina superior derecha Back to product list para volver a la tabla de productos.

Una vez configurados, los productos aparecen en el panel del cliente.

Activación de pago para productos pedidos¶

Para pagar cualquier producto pedido, se utilizará el saldo de su cuenta HOSTKEY. Asegúrese de que el modo automatic payment from balance esté habilitado.

Ejemplos y consejos¶

• Ejemplo de margen y redondeo: precio 123.56 con un margen del 10% y redondeo a 0.5 > 136.0.
• Divisas (Currencies): compruebe Payments > Currencies - deben estar configuradas las tasas hacia EUR/USD y entre las divisas utilizadas.

Errores típicos y soluciones¶

• Invalid API key / 403: compruebe la validez de la API key, la URL (.com), que no haya espacios extra.
• El módulo no es visible en Addons: compruebe los grupos en Access Control, refresque la sesión, compruebe los permisos de archivos/propietario.
• 504 Gateway Timeout al importar: Utilice la importación por consola, aumente el max_execution_time.
• Los precios parecen "en pérdidas": establezca su precio en Pricing por encima del precio de compra; compruebe el margen y el redondeo.
• Error 503: Para averiguarlo, intente revisar el registro de errores del servidor error.log o php_error.log.