Middleware de Sincronización SINCO → Zoho CRM

Resumen de todo lo que hace la plataforma.

Cómo la plataforma obtiene permiso para leer SINCO.

Para consultar SINCO se necesita un token de seguridad (JWT) por cada sociedad. Esos tokens viven en el módulo Sincronizaciones de Zoho (campo «Token Final») y Zoho los regenera todos los días a las 08:00. La plataforma los copia a su base de datos a las 08:03 — tres minutos después, para dar margen a que Zoho termine de regenerarlos y nunca leer un token a medio actualizar.

Cada token es válido desde las 08:00 hasta la medianoche de ese mismo día (unas 16 horas). Por eso la sincronización diaria de negocios corre en la tarde — mientras el token del día sigue vigente — y nunca de madrugada, cuando ya habría expirado.

El proceso principal: del negocio cerrado en SINCO al módulo Plan de Pagos.

Condición de entrada

En los procesos por proyecto (manual y automático) solo se sincronizan los negocios (Deals) cuya fase sea Cierre de negocio y cuya Fecha de cierre esté dentro del año 2026. Si un Deal no cumple ambas condiciones, no se sincroniza en esos procesos. La sincronización manual por negocio (el botón) no aplica el filtro de año: si presionan el botón, ese negocio se sincroniza igual.

Cómo se decide con qué token consultar

Cada negocio pertenece a una sociedad distinta, y cada sociedad tiene su propio token. La plataforma resuelve el token correcto siguiendo esta cadena automáticamente:

1. 1Toma el Número de documento del comprador en el Deal.
2. 2Sigue el campo «Proyecto de interés Sincroniza macro proyectos» del Deal.
3. 3De ahí obtiene la Sociedad (módulo Sincroniza MacroProyectos).
4. 4Con la Sociedad encuentra su Token Final en el módulo Sincronizaciones.
5. 5Usa ese token para consultar SINCO por el número de documento.

Qué se consulta en SINCO

El servicio NegociosComprador (GET /Ventas/NumeroIdentificacion/{documento}) devuelve toda la información de ventas del comprador: proyectos, unidades y el plan de pagos con todas sus cuotas.

Qué cuotas se sincronizan (filtro)

No se traen todas las cuotas. Una cuota se sincroniza solo si cumple al menos una de estas condiciones:

Las cuotas futuras sin mora ni pagos no se sincronizan, porque todavía no aportan información de cartera.

Qué módulo y qué campos se actualizan

Cada cuota se crea en el módulo Plan de Pagos de Zoho, enlazada al Deal correspondiente:

Trámites del negocio

La misma consulta a SINCO también trae los trámites del negocio (orden de separación, escrituración, etc.). Se sincronizan solo los trámites cumplidos: los que tienen fechaCumplimiento (no se traen los pendientes). Cada uno se crea en el módulo Trámites, enlazado al negocio por el campo «Oportunidad».

La sincronización de negocios corre sola todas las tardes, sin intervención.

Cada tarde la plataforma sincroniza automáticamente todos los proyectos. El orden responde a la vigencia del token:

¿Por qué en la tarde? El token de SINCO solo vive hasta la medianoche. Corriendo a las 17:00 se usa el token del día (aún vigente) y todo queda listo antes de que el equipo comercial ingrese a las 07:00 del día siguiente. La cola es persistente: si el servidor se reinicia, retoma donde quedó sin duplicar nada.

Un botón en el Deal para sincronizar un solo negocio al instante.

Además de la corrida automática, el equipo puede sincronizar un negocio puntual sin esperar a la tarde. Se coloca un botón en el Deal de Zoho; al presionarlo, Zoho envía el número de documento del comprador a la plataforma, que consulta SINCO y crea sus cuotas y trámites — con las mismas reglas (mismo filtro de cuotas, mismos módulos) y sin duplicar lo que ya exista.

El endpoint (webhook)

Recomendación: enviar también el dealId. Un mismo documento puede tener varios negocios; con el dealId se sincroniza exactamente ese. Sin él, se sincronizan todos los negocios en «Cierre de negocio» que compartan ese documento.

Modelo de la función Deluge (botón en Zoho)

Se crea una función personalizada enlazada al botón del Deal. Reemplazar TU-DOMINIO y TU_CRON_SECRET por los valores reales del entorno:

// Función personalizada de Deluge, enlazada al botón del Deal.
// 'deal' es el registro del negocio sobre el que se presiona el botón.

payload = Map();
payload.put("documento", deal.get("N_mero_de_documento"));
payload.put("dealId", deal.get("id"));

response = invokeurl
[
    url: "https://TU-DOMINIO/api/webhooks/sync-deal?secret=TU_CRON_SECRET"
    type: POST
    content-type: "application/json"
    parameters: payload.toString()
];

info response; // { "ok": true, "paymentsCreated": 3, "tramitesCreated": 1, ... }

Alternativa de autenticación por cabecera (en vez de ?secret= en la URL):

response = invokeurl
[
    url: "https://TU-DOMINIO/api/webhooks/sync-deal"
    type: POST
    content-type: "application/json"
    headers: {"Authorization": "Bearer TU_CRON_SECRET"}
    parameters: payload.toString()
];

Cada ejecución del botón queda registrada en Logs como una corrida con origen webhook, igual que las automáticas.

Cómo sabe la plataforma que un dato ya fue sincronizado.

Cada cuota se identifica de forma única por la combinación Negocio + Concepto (por ejemplo, «Deal 12345 + Cuota 3»); cada trámite, por Negocio + Código. La plataforma lleva un registro propio de todo lo que ya creó en Zoho.

Importante (estado actual): el comportamiento es crear o conservar. Si una cuota ya existe y sus datos cambiaron en SINCO (por ejemplo, un nuevo pago o más días de mora), hoy no se actualiza. La actualización de cuotas existentes está prevista como un paso siguiente.

Toda operación queda registrada con fecha y hora.

Cada proceso — sincronización de tokens, actualización de conteos y sincronización de planes de pago — escribe en un registro central. La sección Logs permite ver, por ejemplo, que «el proyecto X sincronizó 30 cuotas, 3 fallaron porque el documento no estaba en SINCO», con su fecha y hora exactas.

Módulos de Zoho involucrados y origen de los datos.

Despliegue. La plataforma se ejecuta en Docker (Dokploy): un contenedor web (interfaz + webhook) y un contenedor worker que ejecuta las tareas automáticas (tokens 08:03 y sincronización 17:00). El detalle técnico está en DEPLOY.md del repositorio.