Integración Nómina360 - Phantom X (Veris)

Vista general de la integración

Nómina360 y Phantom X intercambian datos a traves de 6 puntos de integración. Cadencia general por lotes (job a las 2 AM); los catálogos y la consulta de disponibilidad usan canal en línea.

Plataformas (núcleo)

Actor humano

-> Datos hacia Phantom

-> Datos hacia N360

Decisión pendiente

Dueño del empleado

N360. Esquema mínimo a Phantom: cédula, nombres, apellidos, departamento, centro de costo, localidad, agencia (nombre y código).

Dueño de turnos

Phantom X. Misma configuración para todos los médicos (no usa catálogos de N360). Recargos legales se aplican transversalmente en N360.

Dueño de catálogos de permisos

N360. Phantom consume el catálogo y lo usa al capturar ausencias del mismo día.

Marcaciones

Phantom emite eventos crudos (login = entrada, logoff = salida). N360 calcula atrasos, horas extras y recargos.

Cierre mensual

Corte el 31 a las 23:59. Las novedades posteriores quedan sujetas a la política de D4 (ver Parking lot).

Sentido de orquestación

A definir por equipos técnicos (D5). Para efectos del diseño se asume: N360 expone API REST que Phantom consume y viceversa.

Paso a paso de los puntos de integración

#	Punto de integración	Dirección	Datos clave	Cadencia	Notas
1	Maestro de empleado	Nómina360 → Phantom X	Cédula, nombres, apellidos, departamento (código + nombre), centro de costo, localidad, agencia	Batch 2:00 AM	Alta, modificación y baja. La baja inactiva al empleado en Phantom.
2	Catálogos (tipos de permiso y feriados)	Nómina360 → Phantom X	Código, nombre, reglas del tipo (paga, descuenta, requiere documento)	En línea + batch 2:00 AM	Phantom consume el catálogo y lo usa al capturar ausencias del mismo día.
3	Gestión de turnos	Phantom X → Nómina360	Id médico, fecha, horario (instancia diaria)	Día caído + corte 31 23:59	Misma configuración para todos los médicos. Recargos legales se aplican en N360.
4	Marcaciones (login / logoff)	Phantom X → Nómina360	Id médico, timestamp de inicio y fin de jornada (eventos crudos)	Batch 2:00 AM	N360 calcula atrasos, horas extras y aplica recargos 25 / 50 / 100, fines de semana y feriados.
5	Permiso o vacación del mismo día	Phantom X → Nómina360	Id médico, tipo (del catálogo de N360), fecha, motivo	Batch 2:00 AM	Entra en N360 como Por Registrar (sin flujo de aprobación). Phantom ya cerró la agenda localmente.
6	Permiso o vacación programado	Nómina360 → Phantom X	Id empleado, tipo, fechas desde-hasta	Push en línea + consulta en línea	Phantom no puede rechazar. Consulta disponibilidad en línea antes de abrir agenda.

Parking lot de decisiones y riesgos consolidados

Lista de puntos a cerrar con Veris antes de pasar a diseño técnico de la integración.

Decisiónes pendientes (a cerrar con Veris)

D1 - Modificación de turno ya envíado a N360

Si Phantom modifica o borra un turno después de envíarlo a N360, hay que definir: (a) prohibirlo con cierre por fecha, (b) reenvíar evento de corrección y reprocesar, o (c) registrar como ajuste manual. Recomendación: prohibir modificaciónes del período cerrado y permitir correcciónes del período abierto mediante reenvío idempotente.

D2 - Marcación sin turno y login huérfano

Pendiente consultar a Veris: que hacer cuando llega marcación de un médico que no tiene turno ese dia, y cuando hay login sin logoff al cierre del día. Sugerencia: alertar a RRHH para conciliación, no calcular automáticamente.

D3 - Modificación retroactiva en N360 ya envíada a Phantom

Si Phantom ya consumio el dato (catálogo, empleado, permiso) y N360 lo modifica con efecto retroactivo, definir si Phantom acepta el cambio y reabre operación, o si rechaza por fecha cerrada. Recomendación: incluir version y fecha de efectividad en cada evento.

D4 - Cierre mensual y novedades posteriores

Si llega una novedad después del corte 31 a las 23:59: (a) entra al período siguiente, (b) se reabre el cierre. Recomendación: política fija por tipo de novedad (turno y marcación al período siguiente; ausencia con justificativo legal reabre con autorización).

D5 - Mecanismo de consulta de disponibilidad

Confirmado api en línea expuesta por N360. Falta definir contrato (endpoint, autenticación, timeouts, fallback offline). Si la API esta caida, Phantom debe poder seguir operando con copia local o regla por defecto.

D6 - Definición operativa de mismo día

Pendiente. La etiqueta mismo día podria incluir el día siguiente cuando el médico avisa en la noche. Decidir umbral (hoy vs hasta 24h vs hasta inicio del turno).

D7 - Citas ya abiertas frente a permiso o baja

Cuando llega un permiso programado o una baja de empleado y Phantom ya tiene citas abiertas para esa persona en esas fechas, definir si se cancelan automático, se notifica al agendador, o se escala a RRHH. Recomendación: notificación + decision manual del agendador.

D8 - Esquema dual de empleado (campos Phantom-only)

Phantom requiere campos que N360 no tiene. Definir si se extiende el maestro de N360, si los campos viven solo en Phantom sin replica, o si se crea un repositorio compartido. Sin acuerdo hay riesgo de divergencia silenciosa.

Riesgos criticos y mitigaciónes sugeridas

R1 - Phantom es proveedor critico de input para nómina

Sin turnos ni marcaciones del período, N360 no puede calcular. Si Phantom envía tarde o incompleto antes del cierre, la nómina sale con errores.

Mitigación: SLA de entrega 100% antes de las 23:59 del 31. N360 debe poder bloquear el cálculo si detecta data faltante (validación de completitud por empleado-dia).

R2 - Phantom abre agenda sin consultar disponibilidad

El control de no agendar en dias con permiso programado recae en Phantom. Si no consulta el endpoint o consulta una version desactualizada, se compromete a un paciente.

Mitigación: Phantom valida disponibilidad obligatoriamente al abrir agenda (no opcional). Cache de novedades programadas con TTL corto. Auditoria de aperturas sin consulta.

R3 - Cancelación de permiso mismo día post-batch

Si Phantom registro ausencia mismo día y dos horas después el médico avisa que si va, el evento ya entro a N360 en estado Por Registrar.

Mitigación: Phantom emite evento de anulación que N360 procesa al siguiente batch. Si el período ya cerro, queda como ajuste manual con justificativo.

R4 - Novedad de borde llega después del corte mensual

Una marcación, turno o permiso registrado a las 23:59:59 del 31 puede no alcanzar a víajar antes del cierre.

Mitigación: política D4 documentada por tipo de evento. Job especial el 31 a las 23:55 que fuerza envío inmediato.

R5 - Esquema dual de empleado sin gobierno

Campos Phantom-only pueden divergir silenciosamente del maestro N360. Termina habiendo dos versiones de la verdad.

Mitigación: cerrar D8. Documentar campo por campo cual sistema es dueño. Auditoria mensual de consistencia.

R6 - Catálogo desactualizado en Phantom

Si N360 inactiva un tipo de permiso y el batch aún no corrio o el push en línea fallo, Phantom puede ofrecer un tipo que ya no es valido.

Mitigación: N360 valida el tipo al recibir el evento de mismo día. Si el tipo esta inactivo, devuelve error y queda en cola para corrección manual.

R7 - Falla prolongada de la integración

Si la integración se cae varias horas o un día, Phantom sigue operando (es el OS de Veris) pero N360 se queda sin data del período.

Mitigación: cola de eventos persistente del lado emisor con reintentos. Alerta a Soporte si el job batch falla. Procedimiento de catch-up manual antes del cierre mensual.

Integración Nómina360 con Phantom X