Integrations entre Modulos

Los modulos de Zentto se integran entre si de forma automatica y transparente. Cada integracion usa el patron best-effort: la operacion principal nunca falla por un error en la integracion.

Mapa de integraciones

POS ----------------+
Restaurante --------+
Manufactura --------+---> Inventario (stock)
Logistica ----------+
Compras ------------+

Ventas -------------+
Compras ------------+
Bancos -------------+
POS ----------------+
Restaurante --------+---> Contabilidad (asientos)
Nomina -------------+
RRHH ---------------+
Manufactura --------+
Flota --------------+

CRM (Call Center) --+---> Leads (auto-create)

Todos --------------+---> Auditoria (audit trail)
Todos --------------+---> Notificaciones (Zentto Notify)

POS a Inventario

Trigger: Venta en punto de venta.

Flujo:

1. Se registra la venta POS con sus lineas de detalle
2. Para cada linea, se descuenta stock del almacen asignado al POS
3. Se registra un StockMovement de tipo SALE

SP involucrados:

• usp_Ops_Sale_Create — crea la venta
• sp_MovUnidades — descuenta stock

Datos cruzados:

Origen (POS)	Destino (Inventario)
ProductId	ProductId del movimiento
Quantity	Quantity (negativo = salida)
SessionId —> WarehouseId	Almacen del POS

Restaurante a Inventario

Trigger: Cierre de orden de restaurante.

Flujo:

1. Se cierra la orden del restaurante
2. Para cada producto vendido, se busca su receta (rest.Recipe)
3. Para cada componente de la receta, se descuenta el ingrediente del inventario
4. Se registra movimiento de tipo RECIPE_CONSUMPTION

Ejemplo: Venta de 2 hamburguesas con receta que requiere 200g carne + 2 panes + 2 lechugas. Se descuentan 400g carne, 4 panes, 4 lechugas del stock.

SP involucrados:

• sp_Restaurante_Order_Close — cierra la orden
• usp_Rest_Recipe_GetComponents — obtiene ingredientes
• sp_MovUnidades — descuenta cada ingrediente

Logistica a Inventario

Recepcion de mercancia

Trigger: Aprobacion de recepcion de mercancia.

Flujo:

1. Se crea una recepcion vinculada a un documento de compra
2. Al aprobar, se registra ingreso de stock al almacen destino
3. Se registra StockMovement de tipo GOODS_RECEIPT

SP involucrados:

• usp_Logistics_GoodsReceipt_Approve — aprueba recepcion
• usp_Inv_Integracion_GoodsReceipt — ingresa stock

Nota de entrega (despacho)

Trigger: Despacho de nota de entrega.

Flujo:

1. Se crea una nota de entrega vinculada a un documento de venta
2. Al despachar, se descuenta stock del almacen origen
3. Se registra StockMovement de tipo DELIVERY

SP involucrados:

• usp_Logistics_DeliveryNote_Dispatch — despacha la nota
• usp_Inv_Integracion_Delivery — descuenta stock

Devolucion

Trigger: Aprobacion de devolucion.

Flujo:

1. Se crea devolucion vinculada a recepcion o despacho
2. Al aprobar, se registra movimiento inverso de stock
3. Tipo: RETURN_IN (devolucion de cliente) o RETURN_OUT (devolucion a proveedor)

Manufactura a Inventario

Trigger: Operaciones en orden de produccion.

Consumo de materiales

1. Se reporta consumo de materiales en la orden de trabajo
2. Se descuenta stock de materias primas del almacen
3. Se registra StockMovement de tipo MFG_CONSUMPTION

Produccion de producto terminado

1. Se reporta salida de producto terminado
2. Se ingresa stock del producto terminado al almacen
3. Se registra StockMovement de tipo MFG_OUTPUT

SP involucrados:

• usp_Mfg_WorkOrder_Consume — reporta consumo
• usp_Mfg_WorkOrder_ReportOutput — reporta produccion
• usp_Mfg_Integracion_StockMovement — mueve stock

Archivo: web/api/src/modules/manufactura/mfg-integracion.service.ts

Manufactura a Contabilidad

Trigger: Completar orden de trabajo.

Flujo:

1. La orden cambia a estado COMPLETED
2. Se calcula el costo total (materiales + mano de obra + CIF)
3. Se genera asiento contable:
   • Debito: Inventario de Producto Terminado
   • Credito: Produccion en Proceso

Campo SourceModule: manufactura

web/api/src/modules/manufactura/routes.ts

// Best-effort: contabilidad (nunca bloquea la operacion principal)
try {
  await mfgIntegracionService.generateAccountingEntry(workOrder);
} catch { /* best-effort */ }

Flota a Contabilidad

Combustible

Trigger: Registro de carga de combustible.

Debito	Credito
Gasto de Combustible	Caja/Banco

Mantenimiento

Trigger: Completar mantenimiento.

Tipo	Debito	Credito
Preventivo	Gasto de Mantenimiento	Caja/Banco
Correctivo	Gasto de Reparaciones	Caja/Banco

Campo SourceModule: flota

CRM a Leads

Auto-creacion desde Call Center

Trigger: Llamada entrante que identifica un nuevo prospecto.

Flujo:

1. Agente recibe llamada y registra datos del contacto
2. Si el contacto no existe como lead, se crea automaticamente
3. El lead se asigna al pipeline por defecto en la primera etapa

SP involucrados:

• usp_CRM_CallCenter_Call_Create — registra la llamada
• usp_Sys_Lead_Upsert — crea o actualiza el lead

Cierre de lead a creacion de cliente

Trigger: Lead cerrado como GANADO.

Flujo:

1. Lead se cierra como ganado
2. Si CustomerId es NULL, se crea un cliente en master.Customer
3. El lead se vincula al nuevo cliente

Alertas automaticas

Zentto incluye un sistema de alertas automaticas que ejecuta 7 verificaciones periodicas:

#	Alerta	Condicion	Modulo
1	Facturas vencidas	CxC con DueDate < TODAY y saldo > 0	Ventas/CxC
2	Stock bajo	Producto con stock < punto de reorden	Inventario
3	Vencimiento de lotes	Lotes con fecha de vencimiento proxima	Inventario
4	Mantenimiento pendiente	Vehiculos que superan km de intervalo	Flota
5	Documentos por vencer	Seguros, revisiones proximas a vencer	Flota
6	Pagos a proveedores	CxP con vencimiento proximo	Compras/CxP
7	Cierre contable pendiente	Meses no cerrados contablemente	Contabilidad

SP: sys_alertas.sql

Las alertas se registran en sys.Alert y se muestran en el dashboard del usuario.

Notificaciones (Zentto Notify)

Todas las operaciones importantes envian notificaciones via el microservicio Zentto Notify.

Patron: best-effort, nunca bloquea la operacion principal.

web/api/src/modules/_shared/notify.ts

// Todas las funciones son best-effort: nunca lanzan excepciones
await notifyService.send({
  channel: "email",
  template: "invoice-created",
  to: customer.email,
  data: { invoiceNumber, total }
});

Eventos notificados:

Evento	Canal	Template
Factura emitida	Email	invoice-created
Cobro recibido	Email	payment-received
Compra registrada	Email	purchase-created
Movimiento bancario	Interno	bank-movement
Solicitud de aprobacion	Interno	approval-request
Alerta de stock bajo	Interno	low-stock-alert

Archivo: web/api/src/modules/_shared/notify.ts

Auditoria automatica

Todos los modulos generan registros de auditoria automaticamente via el middleware audit-trail.ts. No requiere codigo adicional en cada modulo.

Datos capturados: usuario, modulo, entidad, accion, valores nuevos, IP, timestamp.

Ver Seguridad para detalles completos del middleware de auditoria.

Diagrama de integracion completo

+-------------+     +-------------+     +-------------+
|    Ventas    |---->|  Inventario |<----|   Compras   |
|  (ar/doc)   |     |   (inv)     |     |  (ap/doc)   |
+------+------+     +------+------+     +------+------+
       |                   |                   |
       |            +------+------+            |
       |            |  Logistica  |            |
       |            |(recepciones,|            |
       |            | despachos)  |            |
       |            +------+------+            |
       |                   |                   |
       v                   v                   v
+-----------------------------------------------------+
|                   Contabilidad                       |
|              (acct.JournalEntry)                     |
|    SourceModule: ventas|compras|bancos|pos|...       |
+-----------------------------------------------------+
       ^           ^           ^           ^
       |           |           |           |
+------+--+  +----+----+  +---+----+  +---+----+
|  Bancos |  | Nomina  |  |Manufac.|  | Flota  |
|  (fin)  |  |(nomina) |  | (mfg)  |  |(fleet) |
+---------+  +---------+  +--------+  +--------+