Integración Nómina360 ↔ Phantom X — Módulo de Préstamos

Cliente: Veris · Verificador de Capacidad de Endeudamiento · 3 puntos pendientes de definición

Veris Diagrama de Secuencia 3 por definir
13 mensajes · 4 actores · 3 fases

📋 Pasos del proceso

Seguridad — JWT en cada request
JWT
Phantom X incluye el token en cada llamada
N360 valida la firma del JWT, extrae el company_id del payload y carga el contexto de la empresa antes de ejecutar la operación.
❌
JWT inválido o expiradoN360 responde 401/403. Phantom X debe renovar el token antes de reintentar.
✅
JWT válidocompany_id extraído. Contexto de empresa cargado. Continuar con la operación.
Fase 1 — Verificación de capacidad
1
El operador solicita la verificación
En Phantom X, ingresa la cédula del empleado, el monto y el número de cuotas.
2
N360 evalúa la capacidad
Consulta el rol de pago, descuentos activos y límites legales del empleado.
❌
Sin capacidadEl proceso termina aquí. Phantom X notifica al operador.
✅
Con capacidadN360 devuelve el monto disponible. Continuar a Fase 2.
Fase 2 — Registro del préstamo
3
El operador confirma las facturas
Revisa los datos finales del préstamo y emite las facturas en Phantom X.
4
Phantom X envía el préstamo a N360
Incluye facturas, monto total, cuotas y el PDF de autorización firmada por el empleado.
5
N360 almacena el PDF en Azure
El documento queda guardado en la carpeta de la empresa, con la ruta {company_id}/autorizaciones/{empleado_id}/{prestamo_id}.pdf.
⚠ N360 genera el prestamo_id. Phantom X debe guardarlo — es la clave para enviar las facturas en Fase 3.
6
Confirmación al operador
El préstamo queda registrado. Estado de facturas PDF: Pendiente de recepción.
Fase 3 — Recepción de facturas PDF
⏱ Proceso asíncrono
Puede ocurrir en un momento posterior a la Fase 2. El plazo exacto está por definirse con Veris.
7
Phantom X envía los PDFs de facturas
Incluye el prestamo_id de la Fase 2 para que N360 los vincule al préstamo correcto.
🔁 Por cada PDF de factura:
N360 lo almacena en Azure Blob y guarda la URL.
8
N360 confirma la recepción
Estado del préstamo actualizado: Facturas recibidas. Flujo completo.
✅ Proceso completado

⚠ Puntos pendientes — deben acordarse con Veris antes de implementar

1 · ¿Cuánto tiempo puede pasar entre Fase 2 (registro) y Fase 3 (recepción de PDFs)?
Necesitamos un SLA o plazo máximo (ej: 24h, 72h, 30 días). Si se supera, ¿N360 notifica a alguien? ¿El préstamo queda pendiente indefinido o se cancela?
Sugerencia: campo fecha_limite_facturas en el préstamo + job nocturno que alerte cuando venza el plazo.
2 · ¿Cómo vinculamos el PDF de factura que llega en Fase 3 con la transacción original?
Propuesta: N360 genera prestamo_id en Fase 2 y lo retorna a Phantom X. En Fase 3, Phantom X incluye ese mismo prestamo_id en el payload para que N360 localice y asocie los documentos. Phantom X debe almacenarlo desde la respuesta de Fase 2.
3 · Si hay más de una factura, ¿Phantom X las envía en un solo PDF o cada una en archivo separado?
Opción A — Un PDF por factura: más granular, permite consultar y mostrar cada factura individualmente en N360.
Opción B — Todas en un PDF: más simple de enviar, pero dificulta trazabilidad individual.
Recomendación: Opción A para facilitar la vista por factura en el módulo de préstamos.

Descripción técnica de mensajes

#FaseOrigen → DestinoDescripciónMétodoDatos clave
1F1Usuario → Phantom XOperador solicita verificar capacidad de endeudamiento de un empleado de VerisUICédula, valor, cuotas
2F1Phantom X → N360 APILlama al Verificador de Capacidad de Endeudamiento del módulo de préstamosPOST REST/JSONcedula, valor_requerido, num_cuotas
3F1N360 API → Phantom XResponde si el empleado tiene o no capacidad. Si no es apto, el proceso termina.200 JSONapto: bool, capacidad_disponible
4F2Usuario → Phantom XOperador emite facturas y confirma los datos del préstamo a registrarUIFacturas, valor total, cuotas
5F2Phantom X → N360 APIRegistra el préstamo con facturas y adjunta PDF de autorización firmada por el empleadoPOST multipartfacturas[], valor_total, num_cuotas, PDF
6F2N360 API → Azure BlobAlmacena el PDF de autorización firmadaAzure SDKRuta: {company_id}/autorizaciones/{empleado_id}/{prestamo_id}.pdf
7F2Azure Blob → N360 APIRetorna URL del documento almacenadoAzure SDKblob_url
8F2N360 API → Phantom XConfirma el registro. Estado de facturas PDF: Pendiente de recepción201 JSONprestamo_id, url_autorizacion
9F2Phantom X → UsuarioInforma al operador que el préstamo fue registrado correctamenteUIPréstamo registrado
10F3Phantom X → N360 APIEn proceso posterior, Phantom envía los PDFs de las facturas declaradas en Fase 2POST multipartprestamo_id, facturas_pdf[]
11F3N360 API → Azure BlobAlmacena cada PDF de factura (iterado por archivo)Azure SDKRuta: {company_id}/facturas/{prestamo_id}/factura_N.pdf
12F3Azure Blob → N360 APIRetorna URL de cada factura almacenadaAzure SDKblob_url por factura
13F3N360 API → Phantom XConfirma recepción. Estado actualizado: Facturas recibidas200 JSONestado: facturas_recibidas

📋 Mensajes de respuesta estándar — Integración Phantom X ↔ N360

✅ Respuestas de éxito

IDHTTPFaseMensaje / Campo claveDescripción
—200F1apto: true, capacidad_disponible: 1200.00Empleado verificado con capacidad suficiente. Phantom X puede continuar a Fase 2.
—200F1apto: false, capacidad_disponible: 0Empleado sin capacidad. El proceso termina aquí; Phantom X informa al operador.
—201F2prestamo_id, url_autorizacion, estado: ACTIVOPréstamo registrado correctamente. prestamo_id debe ser almacenado por Phantom X para la Fase 3.
—200F3estado: facturas_recibidas, urls_facturas[]PDFs de facturas recibidos y asociados al préstamo. Flujo completo.
—202F3mensaje: "Procesando", consultar_en: 30Los PDFs fueron recibidos pero el almacenamiento en Azure está en proceso. Phantom X debe reintentar en N segundos.

🔴 Errores de validación de entrada (400)

IDHTTPFaseMensajeCausa y acción
VAL-001400F1/F2/F3Campo requerido ausente: {campo}El payload no incluye un campo obligatorio. N360 devuelve la lista de campos faltantes.
VAL-003422F1Cedula invalida — verificacion de digito fallaEl número de cédula no pasa el algoritmo módulo-10 del Registro Civil. Phantom X debe validar antes de enviar.
VAL-004400F1Cedula con formato incorrecto — debe tener 10 digitos numericosGuiones, espacios o letras en la cédula. Error de digitación del operador en Phantom X.
VAL-007422F1/F2Monto negativo o cero no permitidovalor_requerido o valor_total es <= 0.

🔴 Errores de empleado (422 / 404)

IDHTTPFaseMensajeCausa y acción
EMP-001404F1Empleado no encontrado con cedula {cedula} en empresa VerisLa cédula no existe en N360. Verificar que el empleado fue cargado correctamente en el sistema.
EMP-002422F1Empleado inactivo — estado: {estado}El empleado existe pero está INACTIVO, LIQUIDADO o en BAJA. No se puede verificar capacidad.
EMP-003422F1Empleado en proceso de liquidacion — operacion no permitidaEl empleado está en estado LIQUIDANDO. Rechazar hasta que el proceso de liquidación concluya.
EMP-007404F1/F2Empresa Veris no encontrada o inactivaEl tenant de Veris no existe o está suspendido en N360. Escalar a soporte N360.

🔴 Errores de capacidad de endeudamiento (422)

IDHTTPFaseMensajeCausa y acción
CAP-001422F1Capacidad insuficiente — disponible: {monto}, solicitado: {monto}El empleado tiene capacidad, pero menor al monto requerido. Phantom X debe mostrar el monto máximo disponible.
CAP-002422F1Capacidad no calculada — empleado sin rol de pago asignadoFalta configuración en N360. Escalar a soporte N360 para revisar la parametrización del empleado.
CAP-003409F2Capacidad cambio entre verificacion y registro — diferencia: {monto}Condición de carrera: otro préstamo fue registrado entre la Fase 1 y la Fase 2. N360 debe recalcular y Phantom X confirmar si desea continuar.
CAP-004422F2Descuento excede el maximo legal permitidoEl monto de la cuota supera el porcentaje máximo descontable por ley ecuatoriana. La respuesta incluye el máximo permitido.
CAP-006200F1advertencias: ["anticipo_pendiente"]El empleado tiene un anticipo pendiente que podría reducir la capacidad real. Se incluye en el campo advertencias[] de la respuesta exitosa; no es un error.

🔴 Errores de documentos y PDFs (422 / 500)

IDHTTPFaseMensajeCausa y acción
DOC-001202F3PDF de autorizacion no disponible aun — reintente en {n} segundosEl PDF de autorización firmada está en generación asíncrona. Phantom X debe reintentar con backoff.
DOC-002500F2/F3Error al generar PDF — referencia: {prestamo_id}Fallo en el motor de PDF de N360. Se registra para reintento manual. Phantom X debe alertar al operador.
DOC-003410F3URL de documento expirada — solicite nueva URLEl token de acceso a Azure Blob venció. N360 debe re-generar la URL firmada y devolverla.
DOC-004409F3Facturas duplicadas — ya existen PDFs para {prestamo_id}Phantom X envió los PDFs dos veces. N360 devuelve la referencia original; no re-procesa. Idempotencia activa.

🔴 Errores de infraestructura (502 / 503 / 504 / 429)

IDHTTPFaseMensajeCausa y acción
INF-001504F2/F3Timeout al conectar con Azure BlobAzure no respondió en el tiempo configurado. N360 reintenta automáticamente (máx. 3 veces). Si persiste: alerta interna, no se expone el detalle al cliente.
INF-002502F2/F3Servicio de almacenamiento no disponibleAzure Blob retornó 5xx o la conexión fue rechazada. Se activa circuit breaker; el préstamo queda en estado PENDIENTE_DOCUMENTOS.
INF-004503TodasN360 temporalmente fuera de servicioBase de datos no disponible o despliegue en curso. Phantom X debe reintentar con backoff exponencial. No devolver detalle de infra al cliente.
INF-006429TodasLimite de peticiones excedido — reintentar en {n} segundosRate limiting activado. Phantom X debe respetar el header Retry-After de la respuesta.

🔴 Errores de autenticación (401 / 403)

IDHTTPFaseMensajeCausa y acción
AUTH-001401TodasToken no enviado — incluya Authorization: Bearer en el headerEl header Authorization está ausente en el request de Phantom X.
AUTH-002401TodasToken expirado — token_expired: trueEl JWT venció. Phantom X debe renovar el token antes de reintentar la operación.
AUTH-004403TodasSin permiso para operar en empresa VerisEl token es válido pero el scope no incluye el tenant de Veris. Revisar configuración del cliente en N360.

🟠 Errores de orden entre fases y concurrencia (422 / 404 / 409)

IDHTTPFaseMensajeCausa y acción
ORD-001422F2Operacion requiere verificacion previa — Fase 1 no completadaPhantom X intentó registrar el préstamo sin haber verificado capacidad primero. El flujo debe respetar el orden F1 → F2 → F3.
ORD-002404F3prestamo_id no encontrado o expiradoEl prestamo_id de la Fase 2 no existe en N360 o el plazo para enviar las facturas venció. Phantom X debe re-verificar.
ORD-003200F2/F3Solicitud duplicada detectada — respuesta original devueltaIdempotencia activa. Si Phantom X reenvía el mismo request (mismo prestamo_id o Idempotency-Key), N360 retorna la respuesta original sin re-procesar. No es un error.
ORD-005422F2/F3Estado incorrecto — estado actual: {estado}, permitidos: {estados[]}Se intentó una transición de estado no permitida (ej: registrar facturas en un préstamo ya CANCELADO).
ORD-006422F2Periodo de nomina cerrado — no se aceptan descuentos para {periodo}El rol de pago del período ya fue cerrado. El préstamo se procesará en el siguiente período.