Cómo funciona y uso diario
Una vez emparejado el puente y activada la sincronización, funciona por sí solo. Esta página explica qué está haciendo realmente, para que cuando algo parezca raro sepas dónde mirar en lugar de suponer.
El motor de sincronización en lenguaje claro
1. Un cambio genera un evento
Cada cambio relevante en WHMCS dispara un hook de WHMCS: se añade o edita un cliente, se crea un contacto, se finaliza una factura, llega un pago, se realiza un pedido, se aprovisiona o suspende un servicio, se abre o se responde un ticket.
El hook no realiza ninguna llamada HTTP. Escribe un evento pequeño en una tabla outbox (mod_perfexbridge_outbox) y devuelve el control al instante.
Si un hook de WHMCS llamara directamente a Perfex, un servidor de Perfex lento o inaccesible bloquearía una página de administración de WHMCS o el proceso de pago de un cliente. Escribir en una tabla local lleva un milisegundo y nunca puede fallar por la red de otra persona. Todo lo demás ocurre en segundo plano.
2. El cron vac ía la cola
En cada ejecución del cron del sistema de WHMCS, el distribuidor toma un lote de eventos pendientes de la outbox y envía cada uno de ellos mediante POST a tu instalación de Perfex sobre HTTPS.
Cada petición lleva dos cabeceras junto al cuerpo JSON: una marca de tiempo y una firma HMAC-SHA256 calculada sobre esa marca de tiempo más el cuerpo exacto de la petición, usando tu secreto compartido. Perfex recalcula la firma con su propia copia del secreto y rechaza todo lo que no coincida, o cuya marca de tiempo tenga más de 300 segundos.
Puedes forzar un vaciado inmediato en cualquier momento con Run Sync Now en la página del módulo de WHMCS.
3. Los fallos se reintentan y después pasan a dead-letter
Un envío fallido no se pierde, y tampoco se reintenta en un bucle cerrado. Se reprograma con retardo exponencial: unos 60 segundos después del primer fallo, después 2 minutos, 4, 8, y así sucesivamente, con un tope de 6 horas entre intentos.
Tras 15 intentos, que abarcan aproximadamente 40 horas, la fila se marca como dead. Las filas muertas nunca se reintentan automáticamente ni se eliminan en la limpieza. Son tu cajón de dead-letter: el contador Dead events de la parte superior de la página del módulo de WHMCS te indica cuántas hay, y la fila del registro te dice por qué.
Que un evento pase a dead-letter significa que ha fallado durante casi dos días por el mismo motivo. Casi siempre la causa es una de estas cuatro: una moneda que falta en Perfex, un secreto que no coincide, un plan Free bloqueando un evento Pro, o Perfex fuera de servicio. Corrige la causa y vuelve a encolar el trabajo. Consulta Resolución de problemas.
4. Pausar no pierde nada
Desmarcar Enable Sync pausa únicamente la entrega. Los hooks siguen escribiendo eventos en la outbox, así que no se descarta nada mientras está en pausa. Reactívala y el trabajo acumulado se vacía en la siguiente ejecución, o al momento con Run Sync Now.
5. La supresión de eco evita los bucles infinitos
La sincronización bidireccional plantea un riesgo evidente: WHMCS aplica un cambio procedente de Perfex, esa escritura dispara los propios hooks de WHMCS, y el cambio rebota de vuelta. Si nadie lo impidiera, una sola edición iría y vendría eternamente.
El puente lo evita con varias capas de protección, aplicadas en ambos lados:
- Un marcador de origen dentro de la petición, activo mientras el puente aplica un cambio entrante, para que las escrituras que él mismo realiza no se traten como ediciones nuevas del usuario.
- Una consulta al mapa de entidades e IDs de respuesta, para que una respuesta de ticket que el puente acaba de crear se reconozca en lugar de reenviarse como nueva.
- Una comparación de sumas de verificación, que convierte un evento en una operación sin efecto cuando los datos ya coinciden con el último estado sincronizado.
Cada lado tiene su propio marcador de origen, y la suma de verificación actúa como red de seguridad si alguna vez se sortea un marcador. Estas protecciones fallan deliberadamente en modo abierto: si una de ellas no puede tomar una decisión, se prefiere un envío adicional inofensivo antes que una actualización descartada en silencio.
6. Mantenimiento
Ambos lados ejecutan una limpieza diaria autorregulada, como máximo una vez cada 24 horas:
- las filas de la outbox ya entregadas con más de 7 días se eliminan;
- las filas de registro con más de 90 días se eliminan;
- las filas pendientes y muertas nunca se eliminan, porque las pendientes son trabajo sin entregar y las muertas son tu cajón de dead-letter.
Qué se sincroniza y en qué dirección
De WHMCS a Perfex CRM
| Datos | Free | Pro | Qué llega a Perfex |
|---|---|---|---|
| 👥 Clientes | ✅ | ✅ | Un cliente de Perfex, más un contacto principal con el nombre y el correo del cliente |
| 👤 Contactos | ✅ | ✅ | Contactos adicionales bajo el mismo cliente de Perfex |
| 🗑️ Eliminación de clientes | ✅ | ✅ | El cliente de Perfex se desactiva, no se destruye |
| 📄 Facturas | ➖ | ✅ | Una factura de Perfex con líneas de detalle, una fila de impuestos, totales coincidentes, estado y el número de factura de WHMCS en la nota de administración |
| 💳 Pagos y transacciones | ➖ | ✅ | Un registro de pago contra la factura duplicada, con la pasarela y el ID de transacción. Los duplicados se rechazan |
| 💸 Reembolsos | ➖ | ✅ | El duplicado de Perfex se cancela y se anota |
| 🛒 Pedidos | ➖ | ✅ | Una oportunidad de Perfex por pedido, o una nota en el cliente, o nada, según Order Sync Target |
| 📦 Servicios | ➖ | ✅ | Filas en la pestaña WHMCS del cliente: nombre del producto, dominio, estado, ciclo de facturación, importe y próxima fecha de vencimiento |
| 🌐 Dominios | ➖ | ✅ | Filas en esa misma pestaña: registrador, estado, caducidad y próxima fecha de vencimiento |
| 🎫 Tickets y respuestas | ➖ | ✅ | Un ticket de Perfex bajo el cliente, en el departamento asignado, con sus respuestas y su estado |
En el plan Free, el estado y las notas de un cliente viajan en la carga útil pero no se escriben en Perfex. Solo la eliminación del cliente actúa sobre el registro de Perfex, desactivando al cliente.
De Perfex CRM a WHMCS (solo Pro)
| Cambio realizado en Perfex | Qué ocurre en WHMCS |
|---|---|
| Se edita la información de empresa del cliente | El registro de cliente de WHMCS se actualiza, sujeto a la política de conflictos |
| Se edita el contacto principal | Se actualizan los campos de identidad del cliente en WHMCS, porque el contacto principal es la identidad del cliente |
| Se edita un contacto no principal | Se actualiza el contacto correspondiente de WHMCS |
| Un empleado responde a un ticket duplicado | La respuesta aparece en el ticket de WHMCS, atribuida a tu Ticket Reply Admin si lo has definido, o si no al nombre del empleado de Perfex |
| Se cambia el estado de un ticket | El estado del ticket de WHMCS lo sigue |
Eliminar un cliente o un registro en Perfex no elimina nada en WHMCS. Los registros de facturación se conservan pase lo que pase en el CRM. Esto es deliberado y no es configurable.
Comportamientos conocidos que conviene saber antes de confiar en ellos
Son decisiones documentadas, no errores:
- Los tickets creados directamente en Perfex se quedan en Perfex. Nunca se crean en WHMCS, porque un ticket de WHMCS necesita una cuenta de cliente y un departamento de soporte que un ticket creado en el CRM puede no tener.
- El cambio de estado de un ticket realizado desde el formulario completo de ajustes del ticket en Perfex no se propaga. El desplegable de estado de un ticket individual, las respuestas, los cambios de estado masivos y el cierre automático sí se sincronizan correctamente.
- El tiempo imputado en una tarea de Perfex por ticket no se sincroniza de vuelta a WHMCS. La tarea existe para los informes de hojas de horas nativas de Perfex.
- La periodicidad de las facturas recurrentes no se modela. Las facturas de WHMCS se duplican como facturas puntuales normales de Perfex.
- La fusión de dos clientes de WHMCS no está contemplada. Después de una fusión, reasigna o elimina las filas del mapa correspondientes al cliente absorbido.
- La respuesta de un empleado de Perfex en un ticket sincronizado puede generar dos correos al cliente, uno de Perfex y otro de WHMCS. Si tus clientes operan en el portal de clientes de WHMCS, desactiva la plantilla de correo
ticket-replyde Perfex en Setup > Email Templates > Tickets.
Dónde están los registros
Esta es la sección que más tiempo ahorra. La gente suele buscar en el sitio equivocado.
Lado de WHMCS: la página propia del módulo
Ve a Addons > Perfex CRM Bridge y baja hasta Recent activity.
El puente no escribe en el Activity Log de WHMCS, en Utilities > Logs. Su propia tabla se muestra como el panel Recent activity de la página del módulo, y ese es el único sitio donde mirar en el lado de WHMCS.
La tabla muestra los últimos 50 eventos, con estas columnas:
| Columna | Significado |
|---|---|
| Time | Cuándo se escribió la fila |
| Dir | out para WHMCS hacia Perfex, in para Perfex hacia WHMCS |
| Event | Por ejemplo client.upsert, invoice.upsert, cron.drain |
| Entity | client, contact, invoice, ticket, etc. |
| WHMCS ID | El ID del registro en WHMCS |
| Status | ok en verde o error en rojo |
| Message | El resultado, o el texto exacto del error |
Justo encima, la línea de cabecera muestra los recuentos de Queue pending y Dead events. Esos dos números son tu resumen de salud: los pendientes deberían vaciarse en uno o dos ciclos de cron, y los muertos deberían mantenerse en cero.
Lado de Perfex: dos paneles en la página de ajustes
Ve a Setup > WHMCS Bridge.
Recent inbound events enumera lo que WHMCS ha enviado a esta instalación de Perfex, con el tipo de evento, el ID de WHMCS, el ID de Perfex al que se asignó, una insignia de estado y un mensaje. Aquí es donde una petición rechazada aparece como una fila auth.rejected, lo que indica un problema de firma o de marca de tiempo, casi siempre un secreto que no coincide. Las filas rechazadas están limitadas a 10 por minuto para que una avalancha no pueda llenar tu disco.
Outbound queue enumera los cambios del lado de Perfex a la espera de enviarse a WHMCS, con:
- los recuentos de pending y dead en el encabezado del panel;
- una fila por cambio encolado, mostrando el evento, la entidad, el estado, el número de intentos, la hora del siguiente intento y el último error;
- una explicación en lenguaje claro en lugar de un error en bruto cuando se conoce la causa. Un 403 de un WHMCS sin licencia se lee como "Two-way sync requires Pro on the WHMCS side", con un enlace de mejora, en lugar de un volcado JSON.
Solo se muestran las 20 filas más recientes. Las filas entregadas se eliminan solas al cabo de 7 días; las pendientes y las muertas se conservan.
Qué registro responde a qué pregunta
| Pregunta | Mira aquí |
|---|---|
| 📤 ¿Salió mi cambio de WHMCS? | WHMCS: Recent activity, dirección out |
| 📥 ¿Lo aceptó Perfex? | Perfex: Recent inbound events |
| 🔑 ¿Es incorrecto mi secreto compartido? | Perfex: filas auth.rejected en Recent inbound events |
| 🔁 ¿Llegó mi edición de Perfex a WHMCS? | Perfex: Outbound queue, y después WHMCS: Recent activity, dirección in |
| ⏰ ¿Está funcionando el cron? | WHMCS: la fila Cron delivering de la lista de verificación |
| 🔇 ¿Por qué no hay sincronización bidireccional? | Perfex: el panel WHMCS plan. Si indica Free, ahí tienes la respuesta |
El asistente de importación masiva (Pro)
La sincronización en vivo solo gestiona la actividad nueva. Si instalas el puente en una instalación de WHMCS ya consolidada, tus clientes y facturas existentes no estarán en Perfex hasta que los importes de forma masiva.
El asistente de importación masiva está en la página del módulo de WHMCS, debajo del formulario de ajustes. Encola tus registros existentes en la misma outbox que usa la sincronización en vivo, de modo que heredan la misma firma, los mismos reintentos, el mismo retardo y el mismo tratamiento dead-letter.
Ámbitos
Marca uno o varios:
| Ámbito | Qué encola |
|---|---|
| Clients + contacts | Todos los clientes del rango. Los contactos acompañan automáticamente a su cliente |
| Invoices | Todas las facturas del rango |
| Services + domains | Todos los servicios y dominios del rango, poblando la pestaña WHMCS de Perfex |
Los tickets históricos no se sincronizan. Solo la actividad nueva de tickets circula una vez que el puente está operativo. Esta es una limitación documentada, no un problema de configuración.
Modos
| Modo | Comportamiento |
|---|---|
| All history | Todos los registros de los ámbitos elegidos |
| Date range | Solo los registros creados dentro de una ventana YYYY-MM-DD de inicio y fin. Un rango no válido, por ejemplo una fecha de inicio posterior a la de fin, se rechaza con un mensaje claro y no se encola nada |
| Only new (not yet synced) | Omite los registros que ya están asignados. Este es el modo que debes usar en ejecuciones repetidas |
El límite de 500 entidades y cómo continuar
Cada ejecución encola como máximo 500 entidades, de modo que una importación masiva en una instalación grande no puede desbordar la cola ni atascar tu cron.
Cuando se alcanza el límite, el asistente te avisa. La rutina es la siguiente:
- Haz clic en Queue Backfill. Un banner informativo indica cuántos registros estaban previstos, cuántos se encolaron, cuántos dieron error y si la ejecución se truncó.
- Observa cómo se vacía el contador Queue pending de la parte superior de la página, ya sea con el cron o con Run Sync Now.
- Vuelve a ejecutar el asistente en el modo Only new (not yet synced).
- Repite hasta que una ejecución no prevea ningún registro nuevo.
No hay riesgo de duplicados. Los registros ya asignados se omiten, y un evento cuyos datos ya coinciden con el lado de Perfex se responde como una operación sin efecto.
Dos reglas de orden que te ahorrarán tiempo
Un registro hijo cuyo cliente padre todavía no está en Perfex recibe la respuesta "not mapped, will retry" y permanece en la cola hasta que llega el padre. Normalmente el propio orden de la cola resuelve esto. Pero si importas solo servicios o facturas en una instalación cuyos clientes nunca se sincronizaron, esos eventos se reintentan durante unas 40 horas y después pasan a dead-letter.
Marca Clients + contacts en la misma ejecución, o importa primero los clientes.
Una factura en una moneda que Perfex no conoce se rechaza y se reintenta, y pasa a dead-letter al cabo de unas 40 horas. Antes de importar facturas, añade en Perfex todas las monedas que usen tus clientes de WHMCS en Setup > Finance > Currencies, usando el código ISO exacto.
Facturas históricas ya pagadas
Las facturas importadas que ya estaban pagadas en WHMCS se liquidan en Perfex con un registro de pago sintético, de modo que aparecen como Paid y no como Overdue. Volver a ejecutar una importación masiva no crea pagos duplicados.
Operación cotidiana
Una vez configurado todo, hay muy poco que hacer. Basta con un vistazo semanal a la página del módulo de WHMCS:
| Qué revisar | Estado saludable |
|---|---|
| Lista de verificación | Todo en verde, con gris en la fila de licencia si usas Free |
| Queue pending | Bajo, y descendiendo entre ejecuciones del cron |
| Dead events | 0 |
| Recent activity | Mayoritariamente filas ok |
| Outbound queue de Perfex | 0 pendientes, 0 muertos, en instalaciones Pro con sincronización bidireccional |
Si algo de esa lista no cuadra, Resolución de problemas tiene la causa y la solución.