Instalación

Esta página instala las dos mitades de Perfex CRM Integration for WHMCS. Sigue los pasos en orden. Todo el proceso se realiza desde dos pestañas del navegador más el Administrador de archivos de tu panel de hosting. No hace falta SSH ni línea de comandos.

Deberías tener upload.zip (themesic.com/marketplace/whmcs-perfex.zip) descomprimido, lo que te deja dos archivos:

Archivo	Va a
🧩 perfex-module/module.zip	Perfex CRM
⚙️ whmcs-addon/addon.zip	WHMCS

Instalación rápida (la versión corta)

Para un administrador de hosting con experiencia, todo el trabajo son cinco movimientos. Hazlos en este orden.

1. 🧩 Perfex primero. En Perfex CRM, ve a Setup > Modules > Upload Module, sube module.zip y después Activate. Instalar primero el lado de Perfex significa que el endpoint receptor existe antes de que WHMCS envíe nada.
2. ⚙️ Addon de WHMCS. Sube y extrae addon.zip en modules/addons/ de modo que acabes con modules/addons/perfexbridge/perfexbridge.php, y después activa Perfex CRM Bridge en System Settings > Addon Modules.
3. 🔓 Marca Access Control. En la pantalla Configure del addon, marca Full Administrator (más cualquier otro rol que deba usarlo) y haz clic en Save Changes. Sin esto el módulo es invisible - no aparece en absoluto en el menú Addons.
4. 🔗 Empareja los dos lados. Abre Addons > Perfex CRM Bridge, pega el Connection code copiado de Perfex en la casilla Quick setup y haz clic en Connect. Los detalles están en Configuración.
5. ✅ Verifica. Crea un cliente de prueba en WHMCS, haz clic en Run Sync Now y confirma que aparece en Perfex en Customers.

Cada clic, cada fila de la lista de verificación y la verificación completa de extremo a extremo están en el Recorrido detallado de más abajo.

Recorrido detallado

El orden importa

Instala primero el complemento de Perfex. Es el que crea el endpoint receptor. Si instalas antes el addon de WHMCS y empiezas a sincronizar, todos los eventos fallarán hasta que exista el lado de Perfex, y perderás tiempo leyendo registros de error sobre un problema que aún no has provocado.

Paso 1: Instalar el complemento de Perfex CRM

El complemento de Perfex es gratuito, no lleva clave de licencia y se instala íntegramente desde el área de administración de Perfex.

1. Inicia sesión en Perfex CRM como Administrador.
2. Ve a Setup > Modules.
3. Haz clic en el botón Upload Module.
4. Elige module.zip en el selector de archivos y súbelo.
5. Perfex muestra el módulo como WHMCS Bridge. Haz clic en Install si te lo pide y después en Activate.

Si la subida se rechaza por el tamaño

El botón Upload Module envía el zip a través de PHP, así que los límites upload_max_filesize y post_max_size de tu servidor deben ser ambos mayores que el archivo. Si la subida falla, puedes aumentar esos límites en tu configuración de PHP o usar la alternativa manual que se describe a continuación.

Alternativa manual: extrae module.zip en tu ordenador y sube la carpeta whmcs_bridge resultante al directorio modules/ de tu instalación de Perfex por FTP o con el Administrador de archivos de tu panel de hosting. El resultado debe ser modules/whmcs_bridge/whmcs_bridge.php. Después vuelve a Setup > Modules y haz clic en Activate.

Comprobar que el lado de Perfex se instaló correctamente

• Aparece una nueva entrada WHMCS Bridge en el menú Setup de Perfex. Esa es la página donde generarás el secreto compartido en el siguiente capítulo.

Paso 2: Instalar el addon de WHMCS

WHMCS no tiene instalador de módulos dentro del administrador. Los archivos los colocas tú mismo en el disco y después activas desde el área de administración. El Administrador de archivos de tu panel de hosting lo hace todo.

1. Abre el Administrador de archivos de tu panel de hosting y navega hasta el directorio modules/addons/ de tu instalación de WHMCS.
2. Sube addon.zip a modules/addons/.
3. Usa la acción Extract del Administrador de archivos sobre el archivo subido, extrayendo en ese mismo directorio modules/addons/.
4. Comprueba que el resultado sea modules/addons/perfexbridge/perfexbridge.php. Si has acabado con modules/addons/perfexbridge/perfexbridge/perfexbridge.php, la extracción anidó un nivel de más. Sube la carpeta interior y elimina el envoltorio vacío.
5. Borra del servidor el archivo addon.zip subido una vez que la extracción haya funcionado.

Alternativa por FTP

Extrae addon.zip primero en tu propio ordenador y después sube la carpeta perfexbridge resultante a modules/addons/ por FTP. El estado final es idéntico.

Ahora actívalo:

6. En WHMCS, ve a System Settings > Addon Modules.
7. Busca Perfex CRM Bridge en la lista y haz clic en Activate.

Paso 3: Marca Access Control o el módulo seguirá invisible

Este es el aviso de "no se ha instalado" más frecuente

Tras la activación, WHMCS muestra el panel de configuración del módulo con una sección Access Control que enumera tus roles de administrador. Debes marcar como mínimo Full Administrator, más cualquier otro rol que deba usar el módulo, y hacer clic en Save Changes.

Hasta que no marques un rol, el módulo no aparece en absoluto en el menú Addons de la izquierda. El módulo está instalado, sus tablas existen y su página de ajustes funciona perfectamente, pero no hay ningún enlace a él en ninguna parte del área de administración. Nueve de cada diez veces, "el módulo no se ha instalado" significa que nunca se marcó esta casilla.

En concreto:

1. Sin salir de System Settings > Addon Modules, haz clic en Configure junto a Perfex CRM Bridge. WHMCS suele abrir este panel automáticamente justo después de la activación.
2. En Access Control, marca Full Administrator. Marca también cualquier otro rol de administrador que deba poder abrir y configurar el puente.
3. Haz clic en Save Changes.
4. Recarga el área de administración. Perfex CRM Bridge ya aparece en el menú Addons.

Access Control es lo único que hay en la pantalla Configure

Todos los ajustes reales de este módulo están en su propia página, en Addons > Perfex CRM Bridge, no en la pantalla Configure de WHMCS. La pantalla Configure conserva únicamente Access Control, porque lo renderiza el núcleo de WHMCS y no se puede mover. Si abres Configure buscando la URL de Perfex o la clave de licencia, estás en la pantalla equivocada. Consulta Configuración.

Paso 4: Abrir la página del módulo

Ve a Addons > Perfex CRM Bridge.

La página se abre con la lista de verificación de configuración. En una instalación nueva tiene este aspecto:

Fila de la lista	Estado esperado en este momento
Module tables present	🟢 Marca verde
Connection configured	🔴 Cruz roja, todavía no hay nada emparejado
Connection verified	⚪ Guion gris, nunca se ha comprobado
Sync enabled	🔴 Cruz roja hasta que marques Enable Sync
Cron delivering	🔴 Cruz roja, aún no se ha registrado actividad del cron
License / plan	⚪ Guion gris, plan Free

Ese es el estado correcto para un puente recién instalado y sin configurar. Cada fila se explica en Configuración.

El siguiente paso es emparejar los dos lados: Configuración.

Paso 5: Verificar la primera sincronización de extremo a extremo

Haz esto una vez, justo después del emparejamiento, antes de confiar datos reales al puente. Lleva dos minutos y demuestra que toda la cadena funciona.

1. Completa el emparejamiento descrito en Configuración. Las filas Connection configured y Connection verified deben estar ambas en verde.
2. En esa misma página, en Settings > Sync behaviour, asegúrate de que Enable Sync esté marcado y haz clic en Save Settings. La fila Sync enabled se pone verde.
3. En WHMCS, crea un cliente de prueba. Sirve cualquier nombre y correo electrónico, por ejemplo una empresa llamada Bridge Test Ltd.
4. Vuelve a Addons > Perfex CRM Bridge. El contador Queue pending de la parte superior debería marcar al menos 1.
5. Haz clic en Run Sync Now. Esto fuerza un intento de entrega inmediato sin esperar al cron. La página informa de cuántos eventos se enviaron, cuántos fallaron y cuántos pasaron a dead-letter.
6. En Perfex CRM, abre Customers. El cliente de prueba ya está ahí como cliente, con el nombre y el correo del cliente de WHMCS como contacto principal.
7. Comprueba que ambos registros lo hayan recogido:
   • Lado de WHMCS: la tabla Recent activity, más abajo en la página del módulo, muestra una fila client.upsert con estado ok.
   • Lado de Perfex: en Setup > WHMCS Bridge, el panel Recent inbound events muestra una fila client.upsert equivalente con una insignia verde ok.
8. Elimina el cliente de prueba de ambos sistemas si no quieres conservarlo.

"Run Sync Now" no demuestra que tu cron funcione

Run Sync Now demuestra que la entrega funciona. No pone en verde la fila Cron delivering, porque esa fila rastrea deliberadamente la actividad real del cron del sistema de WHMCS. Si esa fila sigue en rojo o ámbar una hora después, el cron del sistema de WHMCS no se está ejecutando y no se sincronizará nada de forma automática. Arregla el cron antes de pasar a producción. Consulta Resolución de problemas.

Actualizar a una versión más reciente

Ambos módulos comparten la misma versión y deben actualizarse siempre a la vez.

Lado de Perfex. Sube el nuevo module.zip mediante Setup > Modules > Upload Module, sobrescribiendo el módulo existente, y después carga cualquier página de administración. El complemento detecta la versión desactualizada de la base de datos y aplica sus propias migraciones sobre la marcha. Si lo prefieres, desactiva y vuelve a activar el módulo. Ambas vías son seguras: cada sentencia de migración está protegida, así que volver a ejecutarla no altera nada que ya sea correcto.

Lado de WHMCS. Sube y extrae el nuevo addon.zip sobre modules/addons/perfexbridge/. WHMCS ejecuta la rutina de actualización del módulo en cuanto detecta el nuevo número de versión. En caso de duda, desactiva y vuelve a activar el addon en System Settings > Addon Modules.

Tus ajustes sobreviven a una actualización

Los ajustes, el secreto compartido, la clave de licencia, el mapa de entidades y los registros residen todos en tablas de la base de datos que las actualizaciones nunca eliminan. Desactivar el addon de WHMCS tampoco borra sus datos.

Desinstalación

1. WHMCS: System Settings > Addon Modules > Perfex CRM Bridge > Deactivate, y después elimina modules/addons/perfexbridge/ del disco.
2. Perfex: Setup > Modules, desactiva WHMCS Bridge y después elimina el módulo.
3. Si también quieres eliminar los datos, borra las tablas de la base de datos del módulo en cada sistema (haz antes una copia de seguridad).
4. Si tenías una licencia Pro activa, elimina la clave antes de desinstalar para que se libere la plaza de activación y la licencia pueda reutilizarse en otro sitio. Consulta Licenciamiento y activación de Pro.