Configuración

Todo lo que aparece en esta página da por hecho que ambos módulos están instalados y activados, y que puedes acceder a Addons > Perfex CRM Bridge en WHMCS y a Setup > WHMCS Bridge en Perfex CRM. Si te falta alguno de los dos, vuelve a Instalación. En WHMCS la causa habitual es la casilla de Access Control.

Cómo se autentican los dos lados

Ambos endpoints autentican cada petición con una firma HMAC-SHA256 derivada de un secreto compartido.

Dicho de forma sencilla: el emisor firma el cuerpo de la petición con el secreto y le añade una marca de tiempo. El receptor recalcula la firma con su propia copia del secreto y rechaza todo aquello cuya firma no coincida, o cuya marca de tiempo tenga más de 300 segundos. Esa ventana temporal es lo que impide que alguien reproduzca más tarde una petición capturada.

La consecuencia: el secreto debe ser idéntico byte a byte en ambos lados, o todas y cada una de las peticiones fallarán con un 401. Además, cada endpoint rechaza todo el tráfico mientras su propio secreto esté vacío, de modo que un puente configurado a medias queda cerrado y no abierto.

Ambos lados eliminan los espacios en blanco iniciales y finales antes de usarlo, así que un espacio o salto de línea que se cuele al copiar y pegar no te romperá nada. Todo lo que haya en medio debe coincidir exactamente.

Trata el secreto compartido como una credencial

El secreto compartido concede acceso de escritura a los clientes y contactos de Perfex y, con una licencia Pro, a las facturas, pagos, pedidos y tickets de ambos lados. Rótalo en ambos lados de inmediato si alguna de las bases de datos, o una copia de seguridad de ellas, queda expuesta. Los secretos se almacenan en texto plano en tbladdonmodules (WHMCS) y tbloptions (Perfex), que es la práctica habitual en ambos ecosistemas, así que cualquiera con acceso a la base de datos tiene el secreto.

Emparejamiento: la vía rápida (recomendada)

No necesitas copiar ajustes de un lado a otro a mano. Perfex genera un único Connection code que incluye tanto la URL de Perfex como el secreto compartido, y WHMCS lo consume con un solo pegado.

Paso 1: Generar el secreto en Perfex

1. En Perfex CRM, ve a Setup > WHMCS Bridge.
2. Junto a Shared Secret, haz clic en Generate. El campo se rellena con un secreto aleatorio robusto de 64 caracteres y se hace visible para que puedas ver lo que estás a punto de guardar. El botón del ojo vuelve a alternar la visibilidad.
3. Haz clic en Save.

Paso 2: Copiar el Connection code

La página se recarga y ahora muestra un campo Connection code de solo lectura. Su valor es una única cadena que empieza por PBC1..

Haz clic en Copy. El botón parpadea con "Copied!" cuando el código está en tu portapapeles.

El Connection code es una contraseña

El código es PBC1. seguido de un JSON codificado en base64url que contiene la URL de tu Perfex y tu secreto compartido. Eso es codificación, no cifrado. Cualquiera que consiga el código puede comunicarse con los endpoints de tu puente. No lo pegues en un ticket público, un canal de chat, una captura de pantalla ni una solicitud de soporte.

Si no aparece ningún Connection code

El código solo se muestra cuando se cumplen dos condiciones: que tu instalación de Perfex se sirva por HTTPS y que el secreto compartido guardado tenga al menos 32 caracteres. Hacer clic en Generate sin hacer clic en Save es la causa habitual. La página te indica cuál de las condiciones ha fallado:

• "not served over HTTPS" - el emparejamiento necesita HTTPS. Usa la configuración manual en su lugar, o corrige el certificado.
• "shorter than 32 characters" - haz clic en Generate, después en Save, y el código aparecerá.

Paso 3: Pegarlo en WHMCS

1. En WHMCS, abre Addons > Perfex CRM Bridge.
2. Busca el recuadro verde Quick setup en la parte superior de la página.
3. Pega el código en el campo.
4. Haz clic en Connect.

Qué hace realmente Connect

En un solo paso, y en este orden:

1. Decodifica el código y lo valida con rigor: el prefijo PBC1., base64url estricto, un objeto JSON bien formado, una URL que empiece por https:// y supere la validación de URL, y un secreto de al menos 32 caracteres.
2. Envía un ping firmado a tu instalación de Perfex usando la URL y el secreto decodificados, y espera el pong.
3. Solo si ese ping tiene éxito guarda la Perfex CRM URL y el Shared Secret en el lado de WHMCS.
4. Únicamente en el primer emparejamiento, el ping lleva también la URL base de tu WHMCS, de modo que el campo WHMCS URL del lado de Perfex se rellena por ti. Esto solo ocurre si tu WHMCS se sirve por HTTPS, y nunca sobrescribe un valor que ya esté definido.
5. Registra la comprobación satisfactoria, de forma que la fila Connection verified de la lista de verificación se pone verde en esa misma carga de página.

Si todo va bien, verás un banner verde indicando la URL de Perfex con la que se emparejó. Si falla, obtendrás un banner rojo que explica exactamente qué ha ido mal, y no se guarda nada. Un código que no supere la verificación nunca podrá sobrescribir una configuración que funciona.

Volver a emparejar más adelante

Una vez configurado WHMCS, el recuadro Quick setup se convierte en un discreto formulario de Re-pair. Pega un código nuevo cada vez que rotes el secreto o traslades Perfex a un dominio distinto. Se aplica la misma regla: un código que no supere la verificación no cambia nada.

Rota el secreto y después vuelve a emparejar, en ese orden

Si haces clic en Generate y Save del lado de Perfex, todas las peticiones existentes de WHMCS empezarán a fallar al instante con un HTTP 401 hasta que pegues el nuevo código en WHMCS. Haz los dos pasos seguidos. Un código antiguo copiado antes de la rotación será rechazado, y el banner te dirá que Perfex respondió con un 401.

Emparejamiento: la alternativa manual

El Connection code es una comodidad, no magia. Todo lo que hace puede hacerse a mano, y necesitarás esta vía si tu instalación de Perfex todavía no está en HTTPS, o si tu flujo de trabajo prohíbe pegar una credencial combinada.

1. Genera un secreto aleatorio robusto de al menos 32 caracteres. Usa el botón Generate de la página de ajustes de Perfex, o tu propia herramienta, por ejemplo openssl rand -hex 32.
2. En Perfex, en Setup > WHMCS Bridge, pégalo en Shared Secret y haz clic en Save.
3. En WHMCS, abre Addons > Perfex CRM Bridge, baja hasta Settings > Connection y:
   • define Perfex CRM URL con la URL base de tu Perfex, por ejemplo https://crm.example.com, por HTTPS y sin ninguna ruta al final;
   • pega el mismo secreto en Shared Secret.
4. Haz clic en Save Settings.
5. Haz clic en Test Connection en la parte superior de la página. Debes obtener el banner verde "Connection OK".
6. Para la sincronización bidireccional de Pro, define también WHMCS URL en la página de ajustes de Perfex. El emparejamiento lo habría hecho por ti.

Ajustes de WHMCS, sección por sección

Todos los ajustes están en la página propia del módulo

Abre Addons > Perfex CRM Bridge y baja hasta Settings. No busques en la pantalla Configure de WHMCS, en System Settings > Addon Modules; esa pantalla conserva únicamente Access Control, que lo renderiza el núcleo de WHMCS y no se puede mover.

Haz clic en Save Settings para aplicar los cambios. El formulario es todo o nada: una entrada no válida, por ejemplo una URL sin HTTPS, rechaza el envío completo y no cambia nada.

Los dos campos de secreto nunca muestran su valor almacenado

Shared Secret y Pro License Key siempre se muestran vacíos, para que una credencial almacenada no quede expuesta en el código fuente de la página ante cualquier administrador que pueda abrir el módulo. Deja un campo en blanco para conservar su valor actual. Escribe en él para reemplazar ese valor. Para eliminar una clave Pro por completo, marca Remove the stored key.

Connection

Ajuste	Qué hace	Valor recomendado
Perfex CRM URL	La URL base de tu instalación de Perfex, por ejemplo https://crm.example.com. Debe ser HTTPS: el puente se niega a enviar por HTTP sin cifrar.	Se define automáticamente al emparejar
Shared Secret	El secreto HMAC. Debe coincidir con el secreto configurado en Perfex en Setup > WHMCS Bridge. Déjalo en blanco para conservar el almacenado.	Se define automáticamente al emparejar

Sync behaviour

Ajuste	Qué hace	Valor recomendado
Enable Sync	El interruptor principal. Desmárcalo para pausar toda la entrega saliente. Los eventos siguen encolándose mientras está en pausa, así que no se pierde nada; se entregan en la siguiente ejecución después de reactivarlo.	Activado, una vez configurado
Order Sync Target (Pro)	En qué se convierte un pedido de WHMCS dentro de Perfex. lead crea una oportunidad de Perfex por pedido. note añade en su lugar una nota en el cliente de Perfex. off no sincroniza los pedidos en absoluto.	lead
Two-Way Conflict Policy (Pro)	Qué lado gana cuando ambos sistemas han modificado el mismo cliente o contacto desde la última sincronización. Ver más abajo.	newest_wins

Opciones de la política de conflictos, una línea cada una:

• newest_wins (por defecto) - compara la hora del evento entrante de Perfex con la hora de la última sincronización, y gana la edición más reciente.
• whmcs_wins - conserva los datos de WHMCS y descarta la edición conflictiva de Perfex.
• perfex_wins - aplica la edición de Perfex sobre los datos de WHMCS.

La política de conflictos solo actúa ante un conflicto real

Se aplica únicamente cuando ambos lados han modificado el mismo registro desde la última sincronización correcta. Una edición normal en un lado, con el otro lado intacto, siempre se aplica. No estás eligiendo qué sistema "gana" en general, solo cómo deshacer un empate.

Una advertencia sobre newest_wins y los relojes de los servidores

"Más reciente" compara la marca de tiempo del servidor emisor con la hora de última sincronización del servidor receptor, así que los relojes de ambos equipos importan. Mantén los dos servidores sincronizados por NTP. Si la desviación horaria entre tu servidor de WHMCS y el de Perfex está fuera de tu control, opta por whmcs_wins o perfex_wins, que son deterministas.

Tickets

Ajuste	Qué hace	Valor recomendado
Ticket Reply Admin (Pro)	El nombre de usuario del administrador de WHMCS que se utiliza cuando la respuesta de un empleado de Perfex se sincroniza en un ticket de WHMCS. Déjalo vacío para atribuir la respuesta al nombre del empleado de Perfex, publicada como respuesta de no administrador.	Vacío

Licencia Pro

Ajuste	Qué hace	Valor recomendado
Pro License Key	Déjalo vacío para el plan Free. Pega aquí tu clave Pro para desbloquear las funciones Pro. Las claves empiezan por sk_. Guardar una clave que haya cambiado la verifica en vivo, de inmediato.	Vacío (Free)
Remove the stored key	Una casilla que aparece solo cuando hay una clave almacenada. Marcarla y guardar revierte la instalación a Free y libera la plaza de activación de este sitio, para que la licencia pueda usarse en otro lugar.	Sin marcar
Check licence now (botón, parte superior de la página)	Fuerza una comprobación inmediata de la clave ya almacenada, ignorando la limitación de una vez al día.	-
Upgrade to Pro / Buy a Pro licence (enlaces)	Abren el proceso de compra. En una instalación sin Pro aparecen junto al campo de la clave, en la fila de licencia de la lista de verificación y en los recuadros promocionales de Pro.	-

Todos los detalles están en Licenciamiento y activación de Pro.

Los ajustes Pro se pueden configurar sin riesgo en Free

Order Sync Target, Two-Way Conflict Policy y Ticket Reply Admin se guardan sin problema en una instalación Free. Simplemente no tienen efecto hasta que haya una licencia válida activa, y la página lo indica bajo cada campo. Configúralos por adelantado si lo prefieres.

Ajustes de Perfex CRM, campo por campo

Abre Setup > WHMCS Bridge en el área de administración de Perfex y después haz clic en Save.

Connection

Campo	Qué hace	Valor por defecto / alternativo
Shared Secret	Debe coincidir con el Shared Secret de WHMCS. Usa Generate para obtener uno robusto y después Save. El botón del ojo lo muestra u oculta. El endpoint rechaza todo el tráfico mientras esté vacío.	Vacío, endpoint cerrado
Connection code	Solo lectura. Aparece cuando el secreto guardado tiene 32 caracteres o más y Perfex está en HTTPS. Cópialo en el recuadro Quick setup de WHMCS.	Se muestra automáticamente
WHMCS URL	La URL base de la instalación de WHMCS que ejecuta el addon. Solo hace falta para el tráfico de Perfex hacia WHMCS, que es una función Pro. Debe empezar por https:// o no se guarda.	Se rellena automáticamente en el primer emparejamiento, nunca se sobrescribe una vez definida

Sincronización de tickets (Pro)

Campo	Qué hace	Valor por defecto / alternativo
Department mapping (WHMCS to Perfex)	Asigna cada departamento de tickets de WHMCS a un departamento de Perfex. Se muestra como un desplegable por cada departamento de WHMCS cuando se puede obtener el directorio, o como un área de texto manual en caso contrario.	Vacío, nada asignado
Default department for unmapped WHMCS tickets	El departamento de Perfex que se usa para cualquier ticket de WHMCS cuyo departamento no esté en el mapeo.	"Lowest department id (automatic)"
Staff author for synced WHMCS staff replies	El empleado de Perfex al que se atribuye la autoría de las respuestas del personal de WHMCS reflejadas en Perfex.	"First active admin (automatic)"
Create a Perfex task per synced ticket	Cuando está marcado, cada ticket sincronizado obtiene una tarea de Perfex vinculada para que tu personal pueda imputar tiempo con las hojas de horas nativas de Perfex.	Desactivado

Cómo se muestra el mapeo de departamentos

La experiencia normal son desplegables. Cuando se carga la página de ajustes, esta obtiene el directorio de departamentos de soporte de tu WHMCS a través del puente firmado y muestra una fila por departamento de WHMCS, con un desplegable de tus departamentos de Perfex. Elige un destino para cada fila, o déjala en - not mapped -, y haz clic en Save.

Esa consulta necesita una conexión operativa y un WHMCS con licencia Pro, porque el directorio de departamentos está tras la misma barrera de licencia que la sincronización de tickets. Cuando no puede ejecutarse, la página recurre automáticamente a un área de texto manual y te explica por qué:

Lo que ves	Qué significa
Desplegables, uno por departamento de WHMCS	Todo funciona correctamente
Área de texto, "Couldn't fetch WHMCS departments (needs Pro + working connection)"	El puente aún no está configurado, WHMCS no es accesible desde el servidor de Perfex, o la instalación de WHMCS está en el plan Free
Área de texto, "Connection OK, but WHMCS has no support departments yet"	La consulta funcionó. Crea departamentos en WHMCS en Support > Support Departments y después recarga esta página

La consulta tiene un límite de unos pocos segundos, así que un WHMCS inaccesible ralentiza ligeramente la página de ajustes pero nunca la deja colgada.

El formato manual es un mapeo por línea, con el ID del departamento de WHMCS a la izquierda y el ID del departamento de Perfex a la derecha:

1=2
2=5
3=5

Con los desplegables visibles, el enlace Advanced: edit the mapping manually abre esa misma área de texto. Mientras ese editor manual esté abierto, es su contenido lo que se guarda, prevaleciendo sobre lo seleccionado en los desplegables.

Orden de resolución del departamento de un ticket entrante:

1. Una coincidencia exacta en el mapeo.
2. En su defecto, el Default department configurado.
3. En su defecto, el ID de departamento de Perfex más bajo, elegido automáticamente.

Una errata en una línea de mapeo degrada con elegancia hacia la alternativa. No impide guardar ni rompe la sincronización.

El tiempo imputado en la tarea por ticket se queda en Perfex

La tarea opcional de Perfex existe para que tu personal pueda usar las hojas de horas nativas de Perfex sobre un ticket. Esas imputaciones de tiempo no se sincronizan de vuelta a WHMCS, y la tarea no se cierra automáticamente cuando se cierra el ticket.

Paneles de la misma página

La columna derecha de Setup > WHMCS Bridge contiene tres paneles de solo lectura:

• WHMCS plan - qué plan informó por última vez el lado de WHMCS (Pro, Free o Unknown), cuándo se comprobó la licencia por última vez, y un botón Upgrade to Pro cuando hay algo que comprar.
• Outbound queue - cambios del lado de Perfex a la espera de enviarse a WHMCS, con los recuentos de pendientes y muertos, el número de reintentos, la hora del siguiente intento y el último error de cada fila.
• Recent inbound events - lo que WHMCS ha enviado a esta instalación de Perfex, con su estado y su mensaje.

Estos son tus diagnósticos del lado de Perfex. Consulta Cómo funciona y uso diario.

La lista de verificación de configuración, fila por fila

La página del módulo de WHMCS se abre con una lista de verificación de seis filas. Cada fila lleva una marca verde, una advertencia ámbar, una cruz roja o un guion gris, además de una pista de una línea. Todo en verde, con gris en la fila de licencia si estás en Free, significa que el puente está sano.

Fila	Verde significa	Cualquier otra cosa significa
Module tables present	Las tablas de outbox, mapa y registro existen todas.	🔴 Rojo: falta una tabla. Desactiva y vuelve a activar el módulo en System Settings > Addon Modules para recrearla.
Connection configured	La URL de Perfex y el secreto compartido están ambos definidos.	🔴 Rojo: aún no están definidos. Pega un Connection code en Quick setup, o rellena ambos campos en Settings > Connection.
Connection verified	Un ping firmado obtuvo un pong de vuelta, y la fila indica hace cuánto.	🔴 Rojo: la última comprobación falló, y la fila muestra el error. Corrígelo y después haz clic en Test Connection. ⚪ Gris: nunca se ha comprobado, o la última comprobación tiene más de 24 horas. Haz clic en Test Connection para actualizarla.
Sync enabled	La entrega saliente está activada.	🔴 Rojo: la sincronización está en pausa. Los eventos siguen encolándose pero no se entregan. Marca Enable Sync en Settings > Sync behaviour y guarda.
Cron delivering	El cron del sistema de WHMCS hizo trabajo real del puente recientemente, y la fila indica hace cuánto.	🟠 Ámbar: no hay actividad del cron desde hace un tiempo. Comprueba que el cron del sistema de WHMCS esté en funcionamiento. 🔴 Rojo: nunca se ha registrado actividad del cron. En una instalación recién creada eso es normal hasta la primera entrega; si persiste, tu cron no se está ejecutando.
License / plan	Pro está activo.	⚪ Gris: no hay clave de licencia, es decir, el plan Free, que es una forma perfectamente admitida de usar este módulo. 🔴 Rojo: hay una clave definida pero no valida. Revisa la clave y después haz clic en Check licence now.

La fila "Cron delivering" es deliberadamente difícil de falsear

Solo una ejecución auténtica del cron del sistema de WHMCS pone esta fila en verde. Run Sync Now entrega tus eventos encolados, y demuestra que la entrega funciona, pero no toca esta fila. Esa es precisamente la idea: la fila responde a la pregunta "¿seguirá funcionando esto cuando nadie esté mirando?", y pulsar un botón no puede responder a eso.

La fila rastrea trabajo real del puente: vaciados de cola, poda de registros y pasadas de reconciliación. Por eso una instalación inactiva desde hace tiempo pero perfectamente sana puede quedarse en ámbar sin nada que arreglar, sencillamente porque no ha habido nada que hacer.

Tanto Connect (emparejamiento) como Test Connection actualizan la fila Connection verified.

Adónde ir ahora

• Verifica la cadena de extremo a extremo: Instalación, paso 5.
• Desbloquea la sincronización bidireccional, las facturas y los tickets: Licenciamiento y activación de Pro.
• Entiende qué se sincroniza y dónde están los registros: Cómo funciona y uso diario.