rckrdmrd a9703b2727 Initial commit - erp-construccion

2026-01-04 06:12:06 -06:00

6.9 KiB

Raw Permalink Blame History

RF-HR-004: Integración con IMSS

Epic: MAI-007 - RRHH, Asistencias y Nómina Tipo: Requerimiento Funcional Prioridad: Crítica (Cumplimiento Legal) Estado: 🚧 En Definición Última actualización: 2025-11-17

📋 Descripción

El sistema debe integrarse con el Instituto Mexicano del Seguro Social (IMSS) para dar cumplimiento a obligaciones patronales: alta/baja de trabajadores, modificaciones salariales, cálculo de cuotas obrero-patronales, y generación de archivos SUA para pago de cuotas.

🎯 Objetivo Legal

Obligación Legal: Ley del Seguro Social (LSS)

Art. 15: Obligación de inscribir a trabajadores
Art. 34: Plazo de 5 días hábiles para alta
Art. 37: Plazo de 5 días hábiles para baja
Art. 39: Modificación salarial en 5 días hábiles

Sanciones por incumplimiento:

Multas de 20 a 350 veces la UMA (~$2,100 a $36,000 MXN)
Actualización de adeudos con recargos
Posibles auditorías

✅ Casos de Uso Principales

UC-IMSS-001: Alta de Trabajador ante IMSS

Trigger: Nuevo empleado registrado en sistema

Sistema valida datos requeridos (NSS, CURP, RFC, salario)

Genera payload para API IMSS:

{
  "registro_patronal": "A1234567890",
  "nss": "12345678901",
  "curp": "ABCD123456HDFRNN09",
  "nombre": "Juan Pérez López",
  "fecha_nacimiento": "1990-01-15",
  "sexo": "H",
  "salario_base_cotizacion": 350.00,
  "fecha_alta": "2025-01-20",
  "tipo_trabajador": "1", // Permanente
  "tipo_salario": "0" // Fijo
}

Envía request a API IMSS
Recibe folio de confirmación
Guarda log en imss_integration_log
Actualiza estado en empleado: imss_status = 'registered'

Excepciones:

NSS ya registrado con otro patrón
NSS inválido (dígito verificador)
Certificado digital expirado

UC-IMSS-002: Baja de Trabajador ante IMSS

Trigger: Empleado dado de baja en sistema

Obtiene datos de baja (fecha, motivo)

Genera payload:

{
  "registro_patronal": "A1234567890",
  "nss": "12345678901",
  "fecha_baja": "2025-06-15",
  "tipo_baja": "1", // Término de relación laboral
  "causa_baja": "Renuncia voluntaria"
}

Envía a API IMSS
Guarda confirmación
Actualiza imss_status = 'unregistered'

Motivos de baja IMSS:

1: Término de relación laboral
2: Despido
3: Defunción
4: Ausentismo

UC-IMSS-003: Modificación Salarial

Trigger: Cambio de salario en sistema

Detecta cambio en salary_history
Si incremento > 5%, genera modificación ante IMSS

Payload:

{
  "registro_patronal": "A1234567890",
  "nss": "12345678901",
  "nuevo_sbc": 400.00,
  "fecha_efectiva": "2025-02-01",
  "tipo_modificacion": "Aumento salarial"
}

Envía a IMSS
Guarda confirmación

Regla: Solo modificaciones significativas (>5% o >1 UMA)

UC-IMSS-004: Generación de Archivo SUA

Periodo: Mensual (generado entre día 1 y 17 del mes siguiente)

Proceso:

HR accede a "IMSS" → "Generar SUA"
Selecciona período (ej: Enero 2025)
Sistema calcula para cada empleado:
- Días cotizados en el mes
- Salario Base de Cotización (SBC)
- Ausentismos e incapacidades
- Cuotas obrero-patronales por ramo:
  - Enfermedad y Maternidad: 20.4%
  - Invalidez y Vida: 1.75%
  - Retiro, Cesantía y Vejez: 6.15%
  - Guarderías y Prestaciones Sociales: 1%
  - Riesgos de Trabajo: Variable (1% - 15%)
Genera archivo .SUA (layout de 80 caracteres)
Permite descarga
Guarda hash del archivo generado

Formato SUA (simplificado):

*************0101202500120256  // Header
A1234567890CONSTRUCCIONES SA  // Registro patronal
12345678901PEREZ LOPEZ JUAN 0103500000000// Trabajador
99999999999TOTALES          99// Totales

UC-IMSS-005: Consulta de Vigencia de Derechos

Actor: HR, Empleado

Ingresa NSS del empleado
Sistema consulta API IMSS
Obtiene:
- Vigencia de derechos (activo/inactivo)
- Semanas cotizadas
- Última fecha de pago
- Patrón actual
Muestra en pantalla

📊 Modelo de Datos

CREATE TABLE hr.imss_integration_log (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  employee_id UUID NOT NULL REFERENCES hr.employees(id),
  operation_type VARCHAR(50) NOT NULL, -- alta, baja, modificacion, consulta

  request_payload JSONB NOT NULL,
  response_payload JSONB,

  status VARCHAR(20), -- pending, success, failed
  imss_folio VARCHAR(50), -- Folio de confirmación del IMSS
  error_message TEXT,

  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_imss_log_employee ON hr.imss_integration_log(employee_id);
CREATE INDEX idx_imss_log_status ON hr.imss_integration_log(status);
CREATE INDEX idx_imss_log_created ON hr.imss_integration_log(created_at DESC);

-- Tabla para archivos SUA generados
CREATE TABLE hr.sua_files (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  constructora_id UUID NOT NULL REFERENCES auth_management.constructoras(id),

  period_month INTEGER NOT NULL CHECK (period_month BETWEEN 1 AND 12),
  period_year INTEGER NOT NULL CHECK (period_year >= 2025),

  file_content TEXT NOT NULL, -- Contenido del archivo SUA
  file_hash VARCHAR(64) NOT NULL, -- SHA256 del archivo

  total_employees INTEGER NOT NULL,
  total_contributions DECIMAL(12, 2) NOT NULL,

  generated_by UUID REFERENCES auth_management.profiles(id),
  generated_at TIMESTAMPTZ DEFAULT NOW(),

  UNIQUE(constructora_id, period_month, period_year)
);

🔐 Reglas de Negocio

RN-IMSS-001: Plazos Legales

Alta: Máximo 5 días hábiles desde fecha de ingreso
Baja: Máximo 5 días hábiles desde fecha de baja
Modificación: Máximo 5 días hábiles desde cambio

RN-IMSS-002: Salario Base de Cotización (SBC)

SBC = Salario Diario + Prestaciones
Tope máximo: 25 veces la UMA (~$2,500 MXN/día en 2025)
SBC mínimo: 1 UMA (~$103.74 MXN/día en 2025)

RN-IMSS-003: Cuotas Obrero-Patronales

Total aproximado: 27-34% del SBC
Distribución: 70% patrón, 30% trabajador
Calculado sobre días cotizados (no trabajados)

RN-IMSS-004: Certificado Digital

Requiere certificado .cer + llave privada .key del SAT
Vigencia: 4 años
Renovación: 30 días antes de vencimiento

🧪 Criterios de Aceptación

✅ Alta de empleado se envía automáticamente a IMSS en < 5 días
✅ Baja se procesa correctamente con motivo
✅ Modificación salarial se notifica si cambio > 5%
✅ Archivo SUA se genera correctamente con layout válido
✅ SUA incluye todos los empleados activos del período
✅ Cálculo de cuotas es correcto (validado vs calculadora IMSS)
✅ Logs de integración registran request, response, errores
✅ Alertas si certificado digital vence en < 30 días
✅ Retry automático si API IMSS falla (max 3 intentos)

📐 Dependencias

✅ RF-HR-001: Empleados (requiere NSS, CURP, salarios)
✅ RF-HR-003: Costeo (usa cálculo de cuotas)

Fecha de creación: 2025-11-17 Versión: 1.0

6.9 KiB Raw Permalink Blame History