Skip to main content

Overview

The nominas module manages employee information, payroll processing, and bonus/bonification tracking with full audit trails.

Empleado

Employee model with contract information and system user integration.
id
AutoField
required
Primary key for the employee. Auto-generated by Django.
user
OneToOneField
Link to Django authentication user.
  • to: User (Django auth)
  • on_delete: SET_NULL
  • null: True
  • blank: True
  • related_name: ‘empleado’
  • verbose_name: “Usuario del sistema”
nombre
CharField
required
Employee’s full name.
  • max_length: 100
  • verbose_name: “Nombre completo”
cargo
CharField
Job position/title.
  • max_length: 100
  • blank: True
  • null: True
  • verbose_name: “Cargo”
  • help_text: “Descripción del cargo (se usa el rol del usuario si está vinculado)”
  • Note: If linked to a user with a role, the role name is used instead
salario
DecimalField
required
Base salary.
  • max_digits: 10
  • decimal_places: 2
  • verbose_name: “Salario base”
fecha_contratacion
DateField
required
Date of hire.
  • verbose_name: “Fecha de contratación”
estado
CharField
Current employment status.
  • max_length: 20
  • choices: ESTADO_CHOICES
  • default: ‘activo’
  • verbose_name: “Estado”
tipo_contrato
CharField
Type of employment contract.
  • max_length: 20
  • choices: TIPO_CONTRATO_CHOICES
  • default: ‘tiempo_completo’
  • verbose_name: “Tipo de contrato”
email
EmailField
Employee email address.
  • max_length: 100
  • blank: True
  • null: True
  • verbose_name: “Correo electrónico”
telefono
CharField
Phone number.
  • max_length: 20
  • blank: True
  • null: True
  • validators: RegexValidator for international format
  • verbose_name: “Teléfono”
  • Pattern: ^\+?1?\d{9,15}$
direccion
TextField
Employee address.
  • blank: True
  • null: True
  • verbose_name: “Dirección”
fecha_creacion
DateTimeField
Record creation timestamp.
  • auto_now_add: True
  • verbose_name: “Fecha de registro”
fecha_actualizacion
DateTimeField
Last update timestamp.
  • auto_now: True
  • verbose_name: “Última actualización”

Choice Fields

ESTADO_CHOICES
list
Available employment states:
ValueDisplay
activoActivo
inactivoInactivo
vacacionesVacaciones
permisoPermiso
suspendidoSuspendido
TIPO_CONTRATO_CHOICES
list
Available contract types:
ValueDisplay
tiempo_completoTiempo Completo
medio_tiempoMedio Tiempo
temporalTemporal
por_proyectoPor Proyecto

Methods

Properties

  • pagos: Reverse relation to Pago (related_name=‘pagos’)
  • bonificaciones: Reverse relation to Bonificacion (related_name=‘bonificaciones’)

Pago

Payment record model with audit trail.
id
AutoField
required
Primary key for the payment. Auto-generated by Django.
empleado
ForeignKey
required
Reference to the employee.
  • to: Empleado
  • on_delete: CASCADE
  • related_name: ‘pagos’
  • verbose_name: “Empleado”
fecha_pago
DateField
Payment date.
  • default: timezone.now
  • verbose_name: “Fecha de pago”
monto
DecimalField
required
Payment amount.
  • max_digits: 10
  • decimal_places: 2
  • verbose_name: “Monto”
tipo
CharField
Payment type.
  • max_length: 20
  • choices: TIPO_CHOICES
  • default: ‘salario’
  • verbose_name: “Tipo de pago”
descripcion
TextField
Payment description or notes.
  • blank: True
  • null: True
  • verbose_name: “Descripción”
comprobante
FileField
Payment receipt/proof document.
  • upload_to: ‘nominas/comprobantes/’
  • blank: True
  • null: True
  • verbose_name: “Comprobante”
created_by
ForeignKey
User who created this payment record.
  • to: User
  • on_delete: SET_NULL
  • null: True
  • blank: True
  • related_name: ‘pagos_creados’
  • verbose_name: “Creado por”
modified_by
ForeignKey
User who last modified this payment record.
  • to: User
  • on_delete: SET_NULL
  • null: True
  • blank: True
  • related_name: ‘pagos_modificados’
  • verbose_name: “Modificado por”
fecha_creacion
DateTimeField
Record creation timestamp.
  • auto_now_add: True
  • verbose_name: “Fecha de creación”
fecha_modificacion
DateTimeField
Last modification timestamp.
  • auto_now: True
  • verbose_name: “Última modificación”

Choice Fields

TIPO_CHOICES
list
Available payment types:
ValueDisplay
salarioSalario
bonoBonificación
vacacionesPago Vacaciones
liquidacionLiquidación
otroOtro

Meta Options

  • ordering: ['-fecha_pago'] (most recent first)
  • verbose_name: “Pago”
  • verbose_name_plural: “Pagos”

Bonificacion

Employee bonus/bonification model with validity period and audit trail.
id
AutoField
required
Primary key for the bonus. Auto-generated by Django.
empleado
ForeignKey
required
Reference to the employee.
  • to: Empleado
  • on_delete: CASCADE
  • related_name: ‘bonificaciones’
  • verbose_name: “Empleado”
nombre
CharField
required
Bonus name/description.
  • max_length: 100
  • verbose_name: “Nombre”
monto
DecimalField
required
Bonus amount.
  • max_digits: 10
  • decimal_places: 2
  • verbose_name: “Monto”
recurrente
BooleanField
Whether the bonus is recurring.
  • default: False
  • verbose_name: “¿Es recurrente?”
fecha_inicio
DateField
required
Start date of bonus validity.
  • verbose_name: “Fecha de inicio”
fecha_fin
DateField
End date of bonus validity (optional for permanent bonuses).
  • blank: True
  • null: True
  • verbose_name: “Fecha de finalización (opcional)”
activa
BooleanField
Whether the bonus is currently active.
  • default: True
  • verbose_name: “Activa”
created_by
ForeignKey
User who created this bonus.
  • to: User
  • on_delete: SET_NULL
  • null: True
  • blank: True
  • related_name: ‘bonificaciones_creadas’
  • verbose_name: “Creado por”
modified_by
ForeignKey
User who last modified this bonus.
  • to: User
  • on_delete: SET_NULL
  • null: True
  • blank: True
  • related_name: ‘bonificaciones_modificadas’
  • verbose_name: “Modificado por”
fecha_creacion
DateTimeField
Record creation timestamp.
  • auto_now_add: True
  • verbose_name: “Fecha de creación”
fecha_modificacion
DateTimeField
Last modification timestamp.
  • auto_now: True
  • verbose_name: “Última modificación”

Methods

Properties

Meta Options

  • ordering: ['-fecha_inicio'] (most recent first)
  • verbose_name: “Bonificación”
  • verbose_name_plural: “Bonificaciones”

Usage Examples

Creating an Employee

from nominas.models import Empleado
from django.contrib.auth.models import User
from datetime import date

# Create employee with system user
user = User.objects.create_user(
    username='jperez',
    email='[email protected]',
    password='securepass123'
)

empleado = Empleado.objects.create(
    user=user,
    nombre="Juan Pérez",
    cargo="Mesero",
    salario=1500000.00,
    fecha_contratacion=date(2024, 1, 15),
    estado='activo',
    tipo_contrato='tiempo_completo',
    email='[email protected]',
    telefono='+573001234567',
    direccion='Calle 123 #45-67'
)

# Check employee properties
print(f"Antigüedad: {empleado.antiguedad} años")
print(f"Tiene usuario: {empleado.tiene_usuario}")
print(f"Usuario activo: {empleado.usuario_activo}")

Recording Payments

from nominas.models import Pago
from datetime import date

# Regular salary payment
pago = Pago.objects.create(
    empleado=empleado,
    fecha_pago=date(2024, 3, 1),
    monto=empleado.salario,
    tipo='salario',
    descripcion='Pago de salario Marzo 2024',
    created_by=admin_user
)

# Bonus payment with receipt
pago_bono = Pago.objects.create(
    empleado=empleado,
    fecha_pago=date(2024, 3, 15),
    monto=500000.00,
    tipo='bono',
    descripcion='Bono por desempeño Q1 2024',
    comprobante=uploaded_file,
    created_by=admin_user
)

# Get all payments for an employee
pagos = empleado.pagos.all()
total_pagado = sum(p.monto for p in pagos)

Managing Bonuses

from nominas.models import Bonificacion
from datetime import date

# Permanent recurring bonus
bono_transporte = Bonificacion.objects.create(
    empleado=empleado,
    nombre="Auxilio de Transporte",
    monto=150000.00,
    recurrente=True,
    fecha_inicio=date(2024, 1, 1),
    activa=True,
    created_by=admin_user
)

# Temporary bonus
bono_temporal = Bonificacion.objects.create(
    empleado=empleado,
    nombre="Bono Temporada Alta",
    monto=300000.00,
    recurrente=False,
    fecha_inicio=date(2024, 12, 1),
    fecha_fin=date(2024, 12, 31),
    activa=True,
    created_by=admin_user
)

# Check if bonus is valid
if bono_temporal.esta_vigente:
    print("Bonus is currently valid")

# Calculate total salary
salario_total = empleado.get_salario_total()
print(f"Salario Total: ${salario_total:,.2f}")

Querying Employees

from django.db.models import Q, Sum
from nominas.models import Empleado

# Get active employees
activos = Empleado.objects.filter(estado='activo')

# Get employees on vacation
vacaciones = Empleado.objects.filter(estado='vacaciones')

# Get full-time employees
tiempo_completo = Empleado.objects.filter(tipo_contrato='tiempo_completo')

# Get employees with linked users
con_usuario = Empleado.objects.filter(user__isnull=False)

# Get employees hired in the last year
from datetime import date, timedelta
hace_un_ano = date.today() - timedelta(days=365)
recientes = Empleado.objects.filter(fecha_contratacion__gte=hace_un_ano)

# Calculate total payroll
total_nomina = Empleado.objects.filter(
    estado='activo'
).aggregate(total=Sum('salario'))['total']

Audit Trail

# Track payment modifications
pago = Pago.objects.get(id=1)
print(f"Created by: {pago.created_by}")
print(f"Modified by: {pago.modified_by}")
print(f"Created on: {pago.fecha_creacion}")
print(f"Last modified: {pago.fecha_modificacion}")

# Track bonus modifications
bono = Bonificacion.objects.get(id=1)
print(f"Bonus created by: {bono.created_by.username}")
if bono.modified_by:
    print(f"Last modified by: {bono.modified_by.username}")

Build docs developers (and LLMs) love