Nómina¶

¿Qué es?¶

El módulo de Nómina gestiona los comprobantes de pago (payslips) de los empleados: creación, edición de conceptos, cambio de estado y exportación. También incluye la gestión de Períodos de pago, Tipos de comprobante y una herramienta de importación masiva de comprobantes desde hoja de cálculo.

Vista principal — Lista de comprobantes¶

Columnas de la tabla¶

Empleado — Nombre completo del empleado. Ancho variable, truncado.
Cargo — Título del cargo del empleado (job_title). Ancho variable, truncado.
Período — Nombre del período de pago (ej. "2025-01 Quincenal 1"). Ancho 150 px.
Tipo — Nombre del tipo de comprobante. Ancho 130 px.
Fecha de liquidación — Fecha de la liquidación en formato AAAA-MM-DD. Ancho 120 px (muestra solo la fecha, sin hora).
Neto a pagar — Valor del comprobante en pesos colombianos (COP), formateado con separadores de miles. Alineado a la derecha. Ancho 150 px.
Estado — Badge de color según el estado del comprobante. Ancho variable.

Filtros¶

Buscar — Campo de texto libre (nombre del empleado).
Estado — Selector con opciones: Todos, Borrador, Verificado, Pagado, Causado.
Período — Autocompletado que busca en /payroll/periods/search por nombre.
Tipo — Autocompletado que busca en /payroll/types/search por nombre.

Ordenación por defecto¶

Ordenada por fecha de liquidación descendente.

Estados de un comprobante¶

Estado	Badge	Descripción
Borrador	Gris	Recién creado, en proceso de configuración
Verificado	Azul	Revisado y validado, pendiente de pago
Pagado	Verde	El pago ha sido procesado
Causado	Morado	Causado contablemente (sin pago directo)
Cancelado	Rojo	Anulado (no recuperable)

Acciones en la lista¶

Botón "Nuevo" (crear comprobante)¶

Visible con permiso payroll: create. Abre el modal de creación con los campos:

Empleado — Autocompletado que busca en /contract/search/employees (empleados con contrato activo).
Período — Selector desplegable. Por defecto se ocultan los períodos futuros (más de 2 meses adelante). Hay un checkbox "Mostrar todos los períodos" para ver períodos futuros.
Si se selecciona un período futuro, aparece un diálogo de confirmación antes de crear el comprobante.
Tipo — Selector de tipos de comprobante disponibles.
Fecha de liquidación — Campo de fecha (selector de calendario).

Botón "Importar"¶

Visible con permiso payroll: import. Navega a la página de importación masiva (payroll-bulk).

Botón "Períodos"¶

Abre la subpágina de gestión de Períodos de pago.

Catálogos (panel deslizante)¶

Botón Catálogos abre el panel lateral con la pestaña Tipos de comprobante:

Lista de tipos con nombre y acciones al pasar el cursor.
Renombrar (ícono de lápiz) — Campo de texto en línea. Presionar Enter o check guarda; Escape cancela.
Eliminar (ícono de papelera) — Solicita confirmación. No se puede deshacer.
Agregar nuevo tipo — Campo de texto en el pie del panel + botón "+".

Exportar¶

Botón de exportación en la barra de la tabla. Descarga un archivo comprobantes con los datos filtrados. Requiere permiso payroll: export.

Acciones masivas¶

Al seleccionar uno o más comprobantes:

Cambiar estado — Selector + botón Aplicar para cambiar el estado de los seleccionados.
Eliminar — Requiere confirmación en dos pasos (primer clic muestra "¿Confirmar?", segundo clic ejecuta). Elimina permanentemente.

Detalle de comprobante¶

Al hacer clic en un comprobante de la lista, se abre la vista de detalle del comprobante (payroll-detail).

Información del encabezado¶

Nombre del empleado.
Período de pago y Tipo.
Estado actual con badge.
Fecha de liquidación.

Líneas del comprobante¶

La tabla de conceptos muestra:

Nombre — Nombre del concepto o rubro (ej. "Salario", "Aux. Transporte").
Categoría — Tipo contable del concepto:
Devengados — Salarios y devengos base.
Devengados no gravados — Ingresos no salariales sin retención.
Devengados compensatorios — Horas extras y recargos.
Otros devengados — Otros ingresos.
Otros salariales — Devengos salariales adicionales.
Otros derechos — Vacaciones, cesantías.
Deducciones — Descuentos al empleado (salud, pensión, etc.).
Provisiones — Provisiones del empleador.
Cantidad (qty) — Factor multiplicador (ej. 1, 0.5 para media jornada).
Tarifa (rate) — Porcentaje aplicado (por defecto 100%).
Valor base — Monto base del concepto en COP.
Total — Calculado automáticamente: qty × value × (rate / 100) redondeado.

La línea NETO A PAGAR es generada automáticamente por el servidor y no es editable.

Totales automáticos¶

Total devengados — Suma de todas las categorías de devengos.
Total deducciones — Suma de las deducciones.
Neto a pagar — Total devengados - Total deducciones.

Edición de líneas (solo en estado Borrador)¶

Agregar línea — Botón que añade una nueva fila editable al final de la tabla.
Eliminar línea — Ícono de papelera en cada fila para eliminar ese concepto.
Modificar valores — Los campos Nombre, Categoría, Cantidad, Tarifa y Valor son editables en línea. El Total se recalcula automáticamente al cambiar cualquiera de ellos.
Guardar líneas — Botón que guarda todas las líneas. Internamente elimina las líneas existentes y las re-crea con los valores editados. La línea NETO A PAGAR es regenerada por el servidor.

Cambio de estado del comprobante¶

Botón con el estado actual que abre un menú o modal para cambiar a otro estado.

Gestión de períodos¶

Subpágina accesible desde el botón Períodos en la vista principal.

Lista de períodos¶

Columnas: - Nombre — Nombre del período (ej. "2025-01 Quincenal 1"). - Inicio — Fecha de inicio en formato AAAA-MM-DD. - Fin — Fecha de fin. - Periodicidad — Badge: Quincenal (azul) o Mensual (morado). - Estado — Badge: Abierto (verde) o Cerrado (gris).

Filtros de la lista de períodos: - Buscar — Por nombre o año. - Periodicidad — Selector: Todas, Quincenal, Mensual.

Crear / Editar período¶

Campos del modal: - Nombre — Texto libre (obligatorio). - Fecha de inicio — Selector de fecha (obligatorio). - Fecha de fin — Selector de fecha (obligatorio). - Periodicidad — Selector: Quincenal (bi-monthly) o Mensual (monthly).

Generador de períodos anuales¶

Botón Generar que abre un modal para crear automáticamente todos los períodos de un año: - Año — Número de año (2000–2100). - Frecuencia — Quincenal (bi-weekly, por defecto) o Mensual.

Al confirmar, crea los períodos del año completo en un solo paso.

Acciones masivas en períodos¶

Al seleccionar períodos aparece la barra con: - Eliminar — Eliminación permanente con doble confirmación.

Importación masiva de comprobantes¶

La página de importación masiva (payroll-bulk) permite cargar múltiples comprobantes usando una hoja de cálculo.

Estructura de la hoja¶

La hoja tiene columnas fijas y columnas dinámicas de conceptos:

Columnas fijas: | # | Columna | Obligatorio | Notas | |---|---------|-------------|-------| | 1 | Empleado | Sí | Autocompletado por nombre | | 2 | Período | Sí | Nombre del período de pago | | 3 | Tipo | Sí | Tipo de comprobante | | 4 | Fecha de liquidación | Sí | Formato AAAA-MM-DD |

Columnas de conceptos (dinámicas): Se agregan columnas adicionales para cada concepto a incluir (ej. "Salario", "Aux. Transporte", "Salud"). Cada columna tiene una categoría asignada:

D — Devengado (earnings).
D-C — Devengado compensatorio (comp_earnings).
D-NS — Devengado no salarial (non_taxed_earnings).
D-O — Otros devengados (o_earnings).
D-OS — Otros devengados salariales (o_salarial_earnings).
D-R — Vacaciones/Cesantías (o_rights).
P — Provisión (provisions).
D− — Deducción (deductions).

Conceptos por defecto preconfigurados: - Salario (Devengado) - Aux. Transporte (Devengado no salarial) - Horas Extras (Devengado compensatorio) - Salud (Deducción) - Pensión (Deducción) - Retefuente (Deducción)

Agregar conceptos¶

Botón "+ Concepto" abre un modal donde se define: - Nombre — Nombre del concepto (ej. "Comisiones"). - Categoría — Selector del tipo contable.

Al confirmar, se añade la columna al final de la hoja.

Panel de nuevos tipos detectados¶

Si la hoja contiene tipos de comprobante que no existen en el catálogo: - Lista de Tipos nuevos detectados con casilla de selección. - Botones "Todos" / "Ninguno" para selección rápida. - Campo de búsqueda para filtrar la lista. - Botón Crear seleccionados — Crea los tipos en el catálogo antes de importar. - Botón Omitir — Cierra el panel sin crear; esas filas quedarán con error.

Indicador de estado de la hoja¶

Badge en la barra de la tabla: - Verde "Listo para importar" — Sin errores. - Amarillo "N celda(s) con error" — Hay celdas inválidas que deben corregirse antes de guardar.

Guardar importación¶

Botón Guardar envía los datos en bloques al servidor. Muestra el progreso en porcentaje ("Guardando 45%"). Al terminar correctamente, redirige a la lista de comprobantes.

Reglas de validación: - Empleado debe existir en el sistema. - Período y Tipo deben existir en los catálogos. - Los valores numéricos deben ser números válidos (se toleran separadores de miles colombianos: "1.234.567,89"). - Filas completamente vacías se ignoran.

Permisos¶

Acción	Permiso requerido
Ver comprobantes	`payroll: view`
Crear comprobante	`payroll: create`
Editar / cambiar estado	`payroll: edit`
Eliminar	`payroll: delete`
Exportar	`payroll: export`
Importar	`payroll: import`

Páginas relacionadas¶

Empleados — Los empleados que aparecen como destinatarios de los comprobantes.
Contratos — La información contractual del empleado (salario base, tipo de contrato).
Configuración — Valores de auxilio de transporte y alimentación usados en liquidación.

Preguntas frecuentes¶

¿Qué empleados puedo seleccionar al crear un comprobante? Solo empleados que tienen un contrato activo registrado en el módulo de Contratos. Si un empleado no aparece en el autocompletado, verifica que tenga contrato.

¿Puedo editar los conceptos de un comprobante ya verificado o pagado? No. La edición de líneas solo está disponible en estado Borrador. Para modificar un comprobante en otro estado, primero cámbialo a Borrador.

¿Qué significa "Causado"? Un comprobante causado se registra contablemente pero no implica un pago directo al empleado (por ejemplo, cuando se utiliza un sistema ERP externo para el pago).

¿Puedo crear períodos para años futuros? Sí, el generador anual acepta cualquier año entre 2000 y 2100.

¿Cómo ingreso valores con decimales en la importación masiva? El sistema acepta el formato colombiano con punto como separador de miles y coma como decimal (ej. "1.234.567,89") o formato internacional (ej. "1234567.89"). El último separador se interpreta como decimal.