Resolución de problemas

Recorre esta página en orden. Las tres primeras secciones cubren la inmensa mayoría de las solicitudes de soporte.

Antes que nada, abre Addons > Perfex CRM Bridge en WHMCS y lee la lista de verificación de configuración. Está diseñada para señalar directamente el problema, y cada fila se explica en Configuración.

Referencia rápida

Síntoma	Causa más probable	Solución
El módulo no aparece en el menú Addons de WHMCS	Ningún rol de administrador marcado en Access Control	Marca Access Control
Todos los envíos fallan de inmediato	La URL de Perfex empieza por http://	Usa HTTPS
Filas auth.rejected en el registro de entrada de Perfex	El secreto compartido no coincide	Vuelve a emparejar
"Two-way sync requires Pro" en la cola de salida de Perfex	El lado de WHMCS está en el plan Free	Activa Pro
Los eventos se encolan pero no se entrega nada	La sincronización está en pausa, o el cron de WHMCS no se ejecuta	Comprueba el cron
Una factura nunca llega y se reintenta sin fin	La moneda de la factura no existe en Perfex	Añade la moneda
La licencia no se activa	Falta la clave, o no hay conectividad con el servicio de licencias	Fíjate en el color del banner
No aparece ningún Connection code en la página de Perfex	Perfex no está en HTTPS, o el secreto guardado es demasiado corto	Generate y Save
El mapeo de departamentos muestra un área de texto en lugar de desplegables	Plan Free, o WHMCS inaccesible desde Perfex	Alternativas de mapeo
Filas atascadas en estado dead	15 intentos fallidos por el mismo motivo	Reprocesa las filas muertas

El módulo no está en el menú Addons

Síntoma. Activaste Perfex CRM Bridge en System Settings > Addon Modules, WHMCS confirmó la activación, y el módulo no aparece por ninguna parte en el menú Addons de la izquierda.

Causa. No se ha concedido acceso a ningún rol de administrador. WHMCS oculta por completo un módulo addon a cualquier rol que no esté marcado, de modo que el módulo está instalado y plenamente operativo pero no tiene ningún enlace en el área de administración. Este es, con diferencia, el aviso de "no se ha instalado" más frecuente.

Solución.

1. Ve a System Settings > Addon Modules.
2. Haz clic en Configure junto a Perfex CRM Bridge.
3. En Access Control, marca Full Administrator, más cualquier otro rol que deba usar el módulo.
4. Haz clic en Save Changes.
5. Recarga el área de administración. El módulo ya aparece en Addons.

En esa pantalla Configure no hay nada más

Todos los ajustes reales están en la página propia del módulo, en Addons > Perfex CRM Bridge. La pantalla Configure conserva únicamente Access Control, porque lo renderiza el núcleo de WHMCS y no se puede mover.

Todos los envíos fallan de inmediato, o se rechaza la URL

Síntoma. Los eventos se encolan y fallan al instante. El registro Recent activity se llena de errores de conexión. O bien el campo Perfex CRM URL se niega directamente a guardarse.

Causa. HTTPS es obligatorio por diseño. El transporte HTTP está fijado al protocolo https y verifica el certificado TLS. Una URL http:// hace fallar absolutamente todos los envíos, y el campo WHMCS URL del lado de Perfex se niega igualmente a guardarse si no empieza por https://.

Solución.

1. Define Perfex CRM URL con una dirección https:// en el lado de WHMCS.
2. Define WHMCS URL con una dirección https:// en el lado de Perfex.
3. Asegúrate de que ambos certificados se validen realmente desde el otro servidor, no solo en tu navegador. Un certificado autofirmado solo funciona si el servidor que llama confía en él.
4. Haz clic en Test Connection en la página del módulo de WHMCS.

No existe ningún ajuste para desactivar la verificación HTTPS

Es deliberado. Tu secreto compartido y los datos de tus clientes viajan por este canal. Si un certificado no se valida, corrige el certificado.

Filas auth.rejected en el registro de Perfex

Síntoma. WHMCS informa de errores HTTP 401. En Perfex, Setup > WHMCS Bridge > Recent inbound events muestra filas rojas auth.rejected.

Causa. El secreto compartido no coincide en los dos lados, o la marca de tiempo de la petición está fuera de la ventana de 300 segundos. En la práctica casi siempre es el secreto: alguien lo regeneró en un lado y nunca volvió a emparejar el otro.

Solución rápida.

1. En Perfex, en Setup > WHMCS Bridge, copia el Connection code actual.
2. En WHMCS, en Addons > Perfex CRM Bridge, pégalo en el recuadro Re-pair y haz clic en Connect.
3. Haz clic en Test Connection. Debes obtener el banner verde "Connection OK".
4. Haz clic en Run Sync Now. Los eventos encolados que estaban fallando se entregan ahora.

Solución manual. Vuelve a pegar exactamente el mismo secreto en ambos campos Shared Secret y guarda en los dos lados. Los espacios en blanco iniciales y finales se eliminan automáticamente, pero todo lo que haya en medio debe coincidir carácter por carácter.

Si no es el secreto. Revisa los relojes de ambos servidores. Una desviación de más de 300 segundos entre ellos provoca que todas las peticiones se rechacen como si fueran repeticiones. Sincroniza ambos equipos por NTP.

Las filas rechazadas tienen un límite de frecuencia

Perfex registra como máximo 10 filas auth.rejected por minuto, de modo que un emisor mal configurado no pueda llenar tu disco. Si ves exactamente 10 en un minuto, da por hecho que hubo más.

"Two-way sync requires Pro" en la cola de salida de Perfex

Síntoma. Editas un cliente en Perfex. El panel Outbound queue de Setup > WHMCS Bridge muestra la fila con el mensaje "Two-way sync requires Pro on the WHMCS side." y un enlace Upgrade to Pro. Los intentos aumentan y al final la fila pasa a estado muerto.

Causa. La sincronización bidireccional es una función Pro, y la licencia reside en el lado de WHMCS. Tu instalación de WHMCS está en el plan Free, así que su endpoint de entrada responde con un 403 a cualquier cambio originado en Perfex. El complemento de Perfex se comporta correctamente al encolar y reintentar.

Solución. Activa una licencia Pro en el lado de WHMCS. Consulta Licenciamiento y activación de Pro. Una vez activo Pro, WHMCS envía el nuevo estado del plan a Perfex de inmediato, el aviso de mejora desaparece y las filas pendientes se entregan en la siguiente ejecución del cron de Perfex.

Las filas que ya pasaron a dead mientras estabas en Free no se reintentarán por sí solas. Consulta Filas atascadas en estado dead.

Consulta primero el panel de plan

El panel WHMCS plan está justo encima de la cola de salida en la página de ajustes de Perfex, precisamente por este motivo. Si indica Free, ya tienes la respuesta sin leer una sola fila de la cola.

No se sincroniza nada en absoluto

Síntoma. Los eventos aparecen en la cola, Queue pending sube y nada llega nunca a Perfex. Sin errores, solo silencio.

Hay dos causas, y la lista de verificación las distingue.

Causa A: la sincronización está en pausa

La fila Sync enabled de la lista está en rojo.

Solución. En la página del módulo de WHMCS, en Settings > Sync behaviour, marca Enable Sync y haz clic en Save Settings. No se perdió nada mientras estuvo en pausa; los eventos siguieron encolándose y ahora se vaciarán.

Causa B: el cron del sistema de WHMCS no se está ejecutando

La fila Cron delivering de la lista está en rojo o en ámbar.

Solución.

1. Demuestra que el puente en sí funciona haciendo clic en Run Sync Now. Si tu cola se vacía, la entrega está bien y el problema es realmente el cron.
2. Consulta el estado del propio cron de WHMCS en Utilities > System > System Health Status. WHMCS informa de cuándo se ejecutó por última vez el cron del sistema.
3. Si el cron no se ha ejecutado recientemente, corrígelo a nivel de servidor. El gestor de tareas cron de tu panel de hosting, o el crontab de tu servidor, es donde reside el comando del cron de WHMCS. La propia documentación de WHMCS indica el comando exacto para tu versión.
4. Una vez que el cron vuelva a ejecutarse, la fila Cron delivering se pondrá verde en la siguiente carga de página posterior a un trabajo real del puente.

Run Sync Now no puede poner en verde la fila del cron

Esa fila rastrea deliberadamente solo la actividad auténtica del cron del sistema de WHMCS, porque responde a la pregunta "¿seguirá funcionando esto cuando nadie esté mirando?". Pulsar un botón no puede responder a eso. Si Run Sync Now funciona pero la fila sigue en rojo durante horas, tu cron no se está ejecutando.

Una fila de cron en ámbar no siempre es un problema

La fila rastrea trabajo real del puente: vaciados de cola, poda de registros y reconciliación. Una instalación sana pero inactiva, sin cambios que sincronizar, puede quedarse en ámbar sin nada que arreglar.

Una factura se queda atascada y nunca llega a Perfex

Síntoma. Una factura falla repetidamente. El mensaje del registro menciona una moneda, y la fila se sigue reintentando con un retardo creciente.

Causa. La moneda de la factura no está configurada en Perfex. Perfex rechaza la factura, y hace bien, porque no puede registrar un total en una moneda que desconoce.

Solución.

1. En Perfex, ve a Setup > Finance > Currencies.
2. Añade la moneda, usando el código ISO exacto que emplea WHMCS, por ejemplo EUR o USD.
3. No hagas nada más. El evento encolado se reintenta según su propia programación y tendrá éxito en el siguiente intento.

Dispones de unas 40 horas

La programación de reintentos permite 15 intentos a lo largo de unas 40 horas. Añade la moneda dentro de esa ventana, o la fila pasará a dead-letter y habrá que reprocesarla manualmente. Si estás a punto de importar facturas históricas, añade primero todas las monedas que usen tus clientes.

El caso relacionado: "Not mapped (will retry)"

Ha llegado un registro hijo antes que su padre: un contacto cuyo cliente aún no está en Perfex, una factura cuyo cliente todavía no está asignado, o la respuesta de un ticket que aún no se ha sincronizado.

Esto normalmente se resuelve solo. La cola entrega en orden, el padre llega y el hijo tiene éxito en su siguiente intento. Solo se convierte en un problema real cuando el padre nunca se va a sincronizar, por ejemplo cuando importaste servicios sin importar clientes. En ese caso, encola el padre (edita el cliente en WHMCS, o ejecuta una importación de clientes) y los hijos irán detrás.

La licencia no se activa

Síntoma. Pegaste una clave y la instalación sigue mostrando Free.

Para tener Pro hacen falta dos cosas: una clave válida y conectividad desde tu servidor de WHMCS hasta el servicio de licencias. Fíjate en el color del banner, porque te indica cuál de las dos falta.

Banner	Significado	Solución
🔴 Rojo	El servidor de licencias rechazó activamente la clave, y el mensaje explica por qué.	Vuelve a copiar la clave del correo de compra de una sola vez. Las claves tienen 32 caracteres y pueden contener signos de puntuación, así que no recortes ni reformatees nada. Si el mensaje menciona instalaciones o un cupo, libera una plaza de activación eliminando la clave de una instalación que ya no la necesite.
🟠 Ámbar	Tu servidor no pudo contactar con el servicio de licencias. Esto no es un rechazo.	La clave está guardada y los reintentos continúan. Permite el tráfico HTTPS saliente hacia api.freemius.com en cualquier cortafuegos o proxy de salida del servidor de WHMCS. Después haz clic en Check licence now.
⚪ Ningún banner	Guardaste la misma clave que ya estaba almacenada, así que no se volvió a comprobar nada.	Haz clic en Check licence now.
La cabecera indica "awaiting first verification"	Hay una clave almacenada pero nunca se ha confirmado.	Haz clic en Check licence now.

Otras comprobaciones:

• Asegúrate de que la clave esté en Pro License Key, en Settings > Pro licence de la página propia del módulo, y no en algún punto de la pantalla Configure de WHMCS.
• Pulsa Check licence now y espera unos segundos entre pulsaciones. Una segunda pulsación rápida responde "checked a moment ago" sin enviar ninguna petición.
• Si Pro está activo en WHMCS pero Perfex sigue mostrando Free, pulsa Check licence now o Test Connection en WHMCS. Ambos entregan el estado del plan a Perfex de inmediato. Después recarga la página de ajustes de Perfex.

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

No aparece ningún Connection code en Perfex

Síntoma. Estás en Setup > WHMCS Bridge, guardaste un secreto, y no hay ningún campo Connection code, solo una nota gris.

Causas y soluciones. La propia nota te indica cuál se aplica.

Nota	Causa	Solución
"not served over HTTPS"	El emparejamiento requiere una instalación de Perfex con HTTPS.	Corrige el certificado, o usa la configuración manual.
"shorter than 32 characters"	El secreto guardado es demasiado corto. Hacer clic en Generate sin hacer clic en Save es la causa habitual.	Haz clic en Generate y después en Save. El código aparece al recargar.

El emparejamiento falla con "the shared secret does not match"

Síntoma. Pegaste un Connection code en WHMCS y obtuviste un banner rojo que menciona un HTTP 401.

Causa. El código contiene un secreto que Perfex ya no tiene. Casi siempre se trata de un código copiado antes de un Generate y Save posteriores, o de un Generate que nunca se guardó.

Solución. En Perfex, haz clic en Save en la página de ajustes para que el secreto actual quede realmente almacenado, copia un Connection code nuevo y pega ese. El intento fallido no almacenó nada en el lado de WHMCS, así que tu configuración anterior sigue intacta.

El mapeo de departamentos muestra un área de texto en lugar de desplegables

Síntoma. La página de ajustes de Perfex muestra un área de texto simple para el mapeo de departamentos en lugar de un desplegable por cada departamento de WHMCS.

Causa. La página no pudo obtener el directorio de departamentos de soporte de tu WHMCS. La pista bajo el área de texto indica cuál es el caso:

Pista	Causa	Solución
"Couldn't fetch WHMCS departments (needs Pro + working connection)"	El puente no está configurado, WHMCS no es accesible desde el servidor de Perfex, o WHMCS está en el plan Free. El directorio está tras la misma barrera de licencia que la sincronización de tickets.	Completa el emparejamiento, comprueba que Perfex pueda acceder a tu URL de WHMCS por HTTPS, y activa Pro.
"Connection OK, but WHMCS has no support departments yet"	La consulta funcionó; sencillamente no hay nada que asignar.	Crea departamentos en WHMCS en Support > Support Departments y después recarga la página de Perfex.

Mientras tanto, el área de texto manual whmcs_deptid=perfex_department_id siempre funciona, con un mapeo por línea. Esto no bloquea la sincronización: un ticket sin asignar recurre a tu departamento por defecto, o al ID de departamento de Perfex más bajo.

Filas atascadas en estado dead

Síntoma. El contador Dead events de la página del módulo de WHMCS, o el recuento de muertos del panel Outbound queue de Perfex, está por encima de cero.

Causa. Esas filas fallaron 15 veces a lo largo de unas 40 horas por el mismo motivo. Las filas muertas nunca se reintentan automáticamente ni se eliminan en la limpieza, deliberadamente, para que puedas inspeccionarlas.

Solución.

1. Averigua por qué. Abre Recent activity en WHMCS, o la columna "Last error" de la cola de salida en Perfex, y lee el error de las filas afectadas. La causa es casi siempre una de estas: una moneda que falta en Perfex, un secreto que no coincide, un plan Free bloqueando un evento Pro, o Perfex fuera de servicio.

2. Corrige primero esa causa raíz. Reprocesar una fila sin corregir la causa simplemente consume otras 40 horas.

3. Vuelve a encolar el trabajo. La vía más segura no requiere acceso a la base de datos:

   • Para clientes, contactos, facturas, servicios y dominios, vuelve a disparar el evento. Edita y guarda el registro en WHMCS, o ejecuta el asistente de importación masiva en el modo Only new (not yet synced).
   • Para los cambios del lado de Perfex, vuelve a editar el registro de Perfex para encolar un evento nuevo.

4. Si prefieres reprocesar la fila original y tienes acceso a la base de datos, devuélvela a estado pendiente. Haz antes una copia de seguridad:

   UPDATE mod_perfexbridge_outbox
      SET status = 'pending', attempts = 0, next_attempt_ts = 0
    WHERE id = 123;

   Sustituye 123 por el ID de la fila que quieras reprocesar. La tabla equivalente del lado de Perfex es tblwhmcs_bridge_outbox, con el prefijo de tablas de tu Perfex.

Un cambio hecho en Perfex nunca llega a WHMCS

Repasa esta lista en orden:

1. ¿El lado de WHMCS tiene Pro? Consulta el panel WHMCS plan en la página de ajustes de Perfex. La sincronización bidireccional es exclusiva de Pro.
2. ¿Está definida la WHMCS URL en el lado de Perfex? En Setup > WHMCS Bridge > WHMCS URL, con HTTPS y sin ninguna ruta al final. El emparejamiento normalmente la rellena en el primer intento, pero nunca sobrescribe un valor que ya estuviera ahí.
3. ¿Puede el servidor de Perfex acceder a WHMCS por HTTPS? El cliente de envío de Perfex fija HTTPS y verifica el certificado, exactamente igual que el lado de WHMCS.
4. ¿Está funcionando el cron de Perfex? Los cambios originados en Perfex se entregan con el cron de Perfex, no con el de WHMCS. Revisa tu tarea cron de Perfex.
5. ¿Está asignado el registro? Solo están asignados los clientes que se sincronizaron desde WHMCS. Un cliente creado directamente en Perfex no tiene equivalente en WHMCS y nunca se envía. Del mismo modo, los tickets creados directamente en Perfex se quedan en Perfex.
6. Lee el panel Outbound queue. Indica el último error de cada fila.

Un cambio rebotó y sobrescribió mi edición

Síntoma. Editaste un registro en un sistema y volvió al valor del otro sistema.

Causa. Ambos lados modificaron el mismo registro desde la última sincronización, y tu Two-Way Conflict Policy decidió el ganador.

Solución. Elige la política que se ajuste a la forma de trabajar de tu equipo, en Settings > Sync behaviour de la página del módulo de WHMCS:

• newest_wins (por defecto) - gana la edición más reciente. Requiere que los relojes de ambos servidores sean precisos.
• whmcs_wins - WHMCS es siempre la fuente autorizada.
• perfex_wins - Perfex es siempre la fuente autorizada.

Si los relojes de ambos equipos están fuera de tu control, evita newest_wins: la desviación horaria altera sus decisiones en la misma medida que dicha desviación.

Los clientes reciben dos correos por una sola respuesta de ticket

Síntoma. Un empleado de Perfex responde a un ticket sincronizado y el cliente recibe dos notificaciones.

Causa. Perfex envía su propio correo de respuesta de ticket, y la respuesta sincronizada en WHMCS hace que WHMCS envíe también su propia notificación. Es un comportamiento documentado, no un bucle de sincronización. La supresión de correos solo cubre la dirección de WHMCS hacia Perfex.

Solución. Si tus clientes operan en el portal de clientes de WHMCS, desactiva en Perfex la plantilla de correo ticket-reply en Setup > Email Templates > Tickets.

Sigues atascado: qué reunir antes de contactar con soporte

Ten esto preparado y la respuesta suele llegar en la primera contestación:

• La versión de ambos módulos, actualmente 1.3.4, y la confirmación de que los dos lados están en la misma versión.
• La versión de WHMCS, la versión de Perfex CRM y la versión de PHP de ambos servidores.
• Una captura de pantalla de la lista de verificación de configuración de la página del módulo de WHMCS.
• Los recuentos de Queue pending y Dead events.
• Las filas relevantes de Recent activity en WHMCS y de Recent inbound events en Perfex, con la columna de mensaje completa.
• Qué estabas haciendo cuando falló, y si alguna vez llegó a funcionar.

Nunca envíes tu secreto compartido ni tu Connection code

El Connection code contiene tu secreto compartido. Ninguno de los dos debe aparecer en un ticket de soporte, una captura de pantalla o un mensaje de chat. Soporte nunca necesita ninguno de ellos para diagnosticar un problema.