Nómina360

Integración Nómina360 con Phantom X

Cliente: Veris - Síntesis de flujos, contratos de interfaz, decisiones y riesgos de integración

Veris Diseño de integración v2 - 11-jun-2026
Vista general
Contratos de interfaz
1. Maestro empleado
2. Catálogos
3. Gestión de turnos
4. Marcaciones
5. Permiso mismo día
6. Permiso programado
7. Cierre mensual
8. Excepciones
Decisiónes y Riesgos
Vista general

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.

Nómina360 Soluciónes y Proyectos S.A. Dueño de datos del empleado Catálogos de permisos Cálculo de nómina (mes caído) Recargos legales (25/50/100, feriados) Permisos y vacaciónes programadas API REST - Job batch 2:00 AM Endpoint de consulta en línea (contrato por definir) Phantom X Sistema operativo de Veris Agenda medica Asignación de turnos (estándar) Login / Logoff = marcaciones Ausencias del mismo día Espejo del catálogo de permisos API REST - Push diario / cierre 31 23:59 Consume API en línea de N360 1. Maestro empleado (batch) - pendiente por definición cédula, nombres, depto, CC, localidad, agencia (propuesta N360) 2. Catálogo de tipos de permiso (batch + en línea) feriados NO se envían - vacaciones por definir 3. Turnos (dia caído) - asignación por definir por definir si el turno nace en Phantom o en N360 4. Marcaciones crudas (batch 2 AM) login / logoff sin calcular 5. Permiso o vacación mismo día entra como Por Registrar en N360 6. Permiso o vacación programado push + consulta en línea de Phantom a N360 RRHH (N360) Alta, modificación, baja Configura catálogos Empleado (ej. tipo médico) Solicita permisos en N360 Hace login/logoff en Phantom Coordinador / Agendador Asigna turnos a empleados Captura ausencias mismo día Decisiones pendientes en esta vista (detalle en la pestaña Decisiones y Riesgos) D4: novedades que llegan despues del corte mensual - D5: contrato tecnico del API en linea de N360 - D7: citas ya agendadas frente a ausencia o baja D9: interfaz de maestro de empleado (lo mostrado es propuesta de N360) - D10: donde se asigna el turno (Phantom o N360) D11: tipos y categorias de vacaciones en el catalogo (los feriados NO se envian) Cerradas el 11-jun-2026: anti-eco de permisos, sin retroalimentacion de rechazo, politica no-hoy, vigencia de catalogo, re-extraccion, codigo de empleado Cadencia operativa Batch nocturno 2:00 AM - Día caído / semana cerrada para turnos y marcaciones - Corte mensual 31 a las 23:59 - Catálogos en línea + respaldo batch
Plataformas (núcleo)
Actor humano
-> Datos hacia Phantom
-> Datos hacia N360
Decisión pendiente

Dueño de datos del empleado

N360. Esquema mínimo a Phantom: cédula, nombres, apellidos, departamento, centro de costo, localidad, agencia (nombre y código). La interfaz de sincronización del maestro está pendiente por definición con Veris.

Dueño de datos de turnos

Pendiente por definición: si la asignación del turno se hace en Phantom o en N360. Hipótesis actual: la agenda planificada en Phantom genera el turno del empleado en N360. Recargos legales se aplican transversalmente en N360.

Dueño del catálogo de permisos

N360. Cada tipo viaja con estado y vigencia (desde-hasta), no solo la lista. Los feriados NO se envían. Pendiente por definición: tipos y categorías de vacaciones. Phantom consume el catálogo al capturar ausencias del mismo día.

Marcaciones

Phantom emite eventos crudos (login = entrada, logoff = salida). N360 calcula atrasos, horas extras y recargos. Reproceso por nueva consulta completa: trae solo lo nuevo o modificado.

Identificación del empleado

Clave primaria: cédula. Segundo validador: código de empleado (Veris ya lo usa). Ambos viajan en todos los contratos.

Anti-eco de permisos

Todo permiso lleva idOrigen (N360 o PHANTOM) + idExterno cruzado. La consulta es incremental con acuse de consumido: ningún sistema re-procesa ni re-publica lo que originó el otro.

Cierre mensual

Corte el 31 a las 23:59. Qué hacer con novedades que llegan después del corte está aún por definir con Veris (punto D4 de la pestaña Decisiones y Riesgos).

Sentido de orquestación

El contrato técnico del API en línea está por definir con los equipos técnicos (punto D5 de la pestaña Decisiones y Riesgos). 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ónDirecciónDatos claveCadenciaNotas
1Maestro de empleado Pendiente por definiciónNómina360 → Phantom XCédula, nombres, apellidos, departamento (código + nombre), centro de costo, localidad, agenciaBatch 2:00 AMPendiente por definición con Veris: lo mostrado es la propuesta de N360. Alta, modificación y baja. La baja inactiva al empleado en Phantom.
2Catálogo de tipos de permisoNómina360 → Phantom XCódigo, nombre, reglas del tipo (paga, descuenta, requiere documento), estado, vigenciaEn línea + batch 2:00 AMPhantom consume el catálogo y lo usa al capturar ausencias del mismo día. Los feriados NO se envían. Pendiente por definición: tipos y categorías de vacaciones en el catálogo.
3Gestión de turnos Pendiente por definiciónPhantom X → Nómina360Cédula + código de empleado, fecha, horario (instancia diaria)Día caído + corte 31 23:59Misma configuración para todos los empleados (el tipo del empleado puede ser médico). Recargos legales se aplican en N360. Pendiente por definición: dónde se asigna el turno — hipótesis: la agenda planificada en Phantom genera el turno del empleado en N360.
4Marcaciones (login / logoff)Phantom X → Nómina360Cédula + código de empleado, fecha, hora, tipo de marcación (eventos crudos)Batch 2:00 AMN360 calcula atrasos, horas extras y recargos 25 / 50 / 100, fines de semana y feriados. Reproceso = nueva consulta completa por rango que devuelve solo lo nuevo o modificado (idempotente).
5Permiso o vacación generado en PhantomPhantom X → Nómina360Cédula + código, tipo (catálogo N360), fecha, motivo, idOrigen=PHANTOM + idExternoBatch 2:00 AMEntra en N360 como Por Registrar (sin aprobación). Sin retroalimentación de rechazo: para Phantom el empleado ya no trabajó ese día. Consulta incremental con acuse de consumido (anti-eco).
6Permiso o vacación programadoNómina360 → Phantom XCédula + código, tipo, fechas desde-hasta, idOrigen=N360Push en línea + consulta en líneaPhantom no puede rechazar. Política N360: no se registran permisos ni vacaciones con fecha de hoy (solo pasadas o futuras); el mismo día nace solo en Phantom. Phantom consulta disponibilidad antes de abrir agenda.

Contratos de interfaz: qué expone cada sistema, quién consume y para qué

Vista de los endpoints acordados. Cada dato tiene un solo dueño: N360 es dueño de los datos del empleado, del catálogo de permisos y del registro oficial de ausencias; Phantom X es dueño de la operación diaria (turnos, marcaciones, ausencias del mismo día).

Endpoints que expone Phantom X (N360 consume)

#ContratoPara qué consume N360Payload mínimoCadenciaReglas clave
P1GET marcacionesCalcular atrasos, horas extras y recargos legales en el rol de pagosCédula, código de empleado, fecha, hora, tipo de marcación (entrada / salida)Batch 2:00 AMEventos crudos: N360 toma lo recibido como verdad. Reproceso = nueva consulta completa por rango de fechas; Phantom devuelve solo lo nuevo o modificado. Consulta idempotente.
P2GET permisos y vacaciones generados en PhantomRegistrar en N360 (estado Por Registrar) la ausencia capturada durante la planificación de agendaCédula, código, tipo (del catálogo N360), categoría, fecha(s), motivo, idExterno PhantomBatch 2:00 AMConsulta incremental (desde última sincronización) con acuse de consumido. idOrigen=PHANTOM evita el eco. Sin retroalimentación de rechazo: para Phantom ese empleado ya no trabajó ese día.

Endpoints que expone Nómina360 (Phantom X consume)

#ContratoPara qué consume PhantomPayload mínimoCadenciaReglas clave
N1GET catálogo de tipos de permiso (mantenimiento)Poblar el select de tipos y categorías al registrar un permiso: el catálogo nace y vive en N360Código, nombre, categoría, reglas (paga / descuenta / requiere documento), estado, vigencia desde-hastaEn línea + batch respaldoCatálogo versionado con vigencias. Los feriados NO se envían. Si un tipo se inactiva, Phantom deja de ofrecerlo; N360 valida el tipo al recibir cada permiso. Pendiente por definición: tipos y categorías de vacaciones en el catálogo.
N2GET estado del empleado (disponibilidad)Verificar antes de planificar agenda si el empleado está con permiso o vacación en N360Cédula o código + fecha (o rango) → estado: disponible / ausencia activa con tipo y fechasConsulta en líneaObligatoria al abrir agenda, no opcional. Complementa el push N360 → Phantom al aprobar (doble control). Contrato técnico por definir con los equipos (punto D5 de la pestaña Decisiones y Riesgos): autenticación, timeout, fallback.

Flujos de soporte

#ContratoDirecciónPropósitoCadencia
S1Maestro de empleado Pendiente por definiciónN360 → PhantomAlta, modificación y baja con esquema mínimo (cédula, código, nombres, depto, CC, localidad, agencia). La interfaz está pendiente por definición con Veris; lo mostrado es la propuesta de N360.Batch 2:00 AM
S2Turnos asignados Pendiente por definiciónPhantom → N360Instancia diaria de turno como input del cálculo de recargos. Pendiente por definición dónde se asigna el turno: la hipótesis es que la agenda planificada en Phantom genera el turno en N360.Día caído + corte 31 23:59
S3Push de permiso programado aprobadoN360 → PhantomNotificación inmediata al aprobar, con cola de reintentos; Phantom no puede rechazarPush en línea

Reglas transversales acordadas (11-jun-2026)

Identificación dual
Cédula como clave primaria + código de empleado como segundo validador en todos los contratos (Veris ya usa el código). Si los dos no coinciden, el registro se rechaza a cola de conciliación.
Anti-eco de permisos
Todo permiso lleva idOrigen (N360 o PHANTOM) e idExterno cruzado. N360 no publica hacia Phantom permisos con origen Phantom; Phantom reconoce como propios los que él originó. Consultas incrementales con acuse de consumido.
Política "no hoy" en N360
N360 no permite registrar permisos ni vacaciones con fecha de inicio igual a hoy (fecha calendario Ecuador). El mismo día nace únicamente en Phantom, que es quien controla la agenda. Fechas futuras: flujo normal con push. Fechas pasadas (retroactivos): permitidas solo para regularización; si existen marcaciones en esa fecha, N360 alerta y exige resolución antes de registrar.
Doble control para fechas futuras
Push inmediato al aprobar (con cola de reintentos si Phantom no responde) + verificación en línea obligatoria de Phantom al abrir agenda. Ninguno de los dos mecanismos es opcional: el push cubre la inmediatez, la consulta cubre la falla del push.
Borde de medianoche (a vigilar)
Un permiso para mañana aprobado hoy 23:55 deja ventana mínima de reacción si el empleado tiene turno nocturno que cruza medianoche o citas ya agendadas. Mitigación sugerida: anticipación mínima configurable para vacaciones y conexión con D7 (citas abiertas).

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 cerradas el 11-jun-2026

C1 - Anti-eco e identidad de permisos
Todo permiso lleva idOrigen (N360 / PHANTOM) + idExterno cruzado. Consultas incrementales con acuse de consumido. Ningún sistema re-procesa ni re-publica lo que originó el otro.
C2 - Sin retroalimentación de rechazo hacia Phantom
Lo que N360 haga con un permiso recibido de Phantom (reclasificar, ajustar) es interno: para Phantom el empleado ya no trabajó ese día y su agenda ya se cerró. No se construye flujo de reversa.
C3 - Política "no hoy" en N360
N360 bloquea el registro de permisos y vacaciones con fecha de inicio igual a hoy. El mismo día nace solo en Phantom. Futuro: push + verificación en línea. Retroactivo: permitido con validación contra marcaciones existentes de la fecha. Esto cierra la parte central de D6.
C4 - Catálogo con estado y vigencia
El catálogo de tipos de permiso viaja con estado (activo / inactivo) y vigencia desde-hasta. N360 valida el tipo al recibir cada permiso.
C5 - Reproceso de marcaciones por re-extracción
Phantom solo expone marcaciones. Si N360 necesita reprocesar, ejecuta una nueva consulta completa por rango y Phantom devuelve solo lo nuevo o modificado. Consulta idempotente; no hay push de correcciones.
C6 - Código de empleado como segundo validador
Cédula es la clave primaria; el código de empleado (que Veris ya utiliza) viaja como segundo validador en todos los contratos. Discrepancia entre ambos → cola de conciliació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 empleado 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. Nota: las correcciones de marcaciones ya quedaron resueltas con C5 (re-extracción por rango).
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 - Mismo día: residual de borde de medianoche
La parte central quedó cerrada con C3 (política no-hoy: el mismo día nace solo en Phantom). Residual: definir "hoy" como fecha calendario Ecuador y manejar el turno nocturno que cruza medianoche — un permiso para mañana aprobado a las 23:55 deja ventana mínima de reacción. Sugerencia: anticipación mínima configurable para vacaciones.
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.
D9 - Interfaz de maestro de empleado pendiente por definición
La sincronización completa del maestro (dirección, cadencia, campos) aún no está acordada con Veris. Lo diagramado en el sub-flujo 1 es la propuesta de N360.
D10 - Dónde se asigna el turno
Por definir si la asignación de turnos se hace en Phantom o en Nómina360. Hipótesis de trabajo: la agenda planificada en Phantom X genera automáticamente el turno del empleado en N360. Si se decide al revés, el flujo del sub-flujo 3 se invierte.
D11 - Tipos y categorías de vacaciones en el catálogo
Cerrado: los feriados NO se envían a Phantom. Por definir: cómo se incorporan los tipos y categorías de vacaciones al catálogo sincronizado de permisos.

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 empleado 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.