Nominas

Conceptos de nomina (Payroll Concepts)

Antes de generar nominas, necesitas configurar los conceptos salariales disponibles.

Modelo

interface PayrollConcept {
  id: string;
  name: string;                // "Salario base", "Plus transporte", "IRPF"
  code: string;                 // "SAL_BASE", "PLUS_TRANS", "IRPF"
  type: 'earning' | 'deduction' | 'tax' | 'security_contribution';
  calculation: 'fixed' | 'percentage' | 'formula';
  default_value?: number;       // Valor por defecto (fijo o porcentaje)
  formula?: string;             // Formula personalizada
  is_mandatory: boolean;
  applies_to: 'all' | 'department_ids[]' | 'contract_type[]';
  active: boolean;
  sort_order: number;
}

Tipos de concepto

Tipo	Descripcion	Ejemplos
earning	Devengo (lo que cobra el empleado)	Salario base, plus transporte, comisiones
deduction	Deduccion (lo que se descuenta antes de IRPF)	Seguridad Social empleado, anticipos
tax	Impuesto (IRPF)	Retencion IRPF
security_contribution	Aportacion a SS de la empresa	Seguridad Social empresa

Endpoints

GET    /api/hr/payroll-concepts
POST   /api/hr/payroll-concepts
PATCH  /api/hr/payroll-concepts/:id
DELETE /api/hr/payroll-concepts/:id

Ejemplos de conceptos

[
  {
    "id": "pc_sal_base",
    "name": "Salario base",
    "code": "SAL_BASE",
    "type": "earning",
    "calculation": "fixed",
    "is_mandatory": true,
    "active": true
  },
  {
    "id": "pc_plus_trans",
    "name": "Plus transporte",
    "code": "PLUS_TRANS",
    "type": "earning",
    "calculation": "fixed",
    "default_value": 180.00,
    "is_mandatory": false,
    "active": true
  },
  {
    "id": "pc_irpf",
    "name": "IRPF",
    "code": "IRPF",
    "type": "tax",
    "calculation": "percentage",
    "default_value": 19.0,
    "is_mandatory": true,
    "active": true
  }
]

---

Nominas generadas

Modelo

interface Payroll {
  id: string;
  employee_id: string;
  period: string;                // "2026-05" (ano-mes)
  year: number;
  month: number;
  worked_days: number;          // Dias trabajados
  base_days: number;            // Dias naturales del mes
  lines: PayrollLine[];
  subtotal_earnings: number;
  subtotal_deductions: number;
  taxable_base: number;         // Base imponible
  irpf_amount: number;          // Retencion IRPF
  ss_employee: number;          // Seguridad Social empleado
  ss_company: number;           // Seguridad Social empresa
  gross_salary: number;         // Salario bruto
  net_salary: number;           // Salario neto
  status: 'draft' | 'calculated' | 'sent' | 'paid' | 'cancelled';
  generated_by: string;
  generated_at: string;
  paid_at?: string;
}

interface PayrollLine {
  concept_id: string;
  concept_name: string;
  concept_type: string;
  quantity: number;
  unit_price: number;
  amount: number;
}

Generar nominas del periodo

POST /api/hr/payrolls/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "period": "2026-05",
  "employee_ids": ["emp_001", "emp_002"],
  "worked_days": 21
}

El sistema:

1. Recoge el salario base de cada empleado
2. Aplica los conceptos obligatorios (IRPF, SS)
3. Calcula cada concepto segun su tipo de calculo
4. Genera las lineas de nomina
5. Calcula el neto

Ver nomina

GET /api/hr/payrolls/:id

{
  "data": {
    "id": "pay_2026_05_emp001",
    "employee": {
      "id": "emp_001",
      "name": "Maria Garcia Lopez",
      "employee_number": "EMP-2026-001"
    },
    "period": "2026-05",
    "worked_days": 21,
    "lines": [
      { "concept_name": "Salario base", "type": "earning", "amount": 1800.00 },
      { "concept_name": "Plus transporte", "type": "earning", "amount": 180.00 },
      { "concept_name": "Seguridad Social", "type": "deduction", "amount": -148.50 },
      { "concept_name": "IRPF 19%", "type": "tax", "amount": -348.00 }
    ],
    "gross_salary": 1980.00,
    "ss_company": 560.00,
    "net_salary": 1483.50,
    "status": "draft"
  }
}

Endpoints

Metodo	Ruta	Descripcion
POST	/api/hr/payrolls/generate	Generar nominas de un periodo
GET	/api/hr/payrolls	Listar nominas
GET	/api/hr/payrolls/:id	Ver nomina
PATCH	/api/hr/payrolls/:id	Editar linea de nomina
POST	/api/hr/payrolls/:id/approve	Aprobar nomina
POST	/api/hr/payrolls/:id/pay	Marcar como pagada
POST	/api/hr/payrolls/:id/cancel	Anular nomina
GET	/api/hr/payrolls/:id/pdf	Generar pdf de nomina

---

Nóminas de todxs lxs empleados

GET /api/hr/payrolls?period=2026-05

Lista todas las nominas de un periodo con el estado y el neto de cada una.

---

Marcado como pagado

Al marcar una nomina como pagada, se crea automaticamente un apunte en la contabilidad y se registra el pago:

POST /api/hr/payrolls/:id/pay
Content-Type: application/json

{
  "payment_date": "2026-05-31",
  "payment_method": "transfer",
  "notes": "Nómina mayo 2026 transferida"
}

---

Resumen de endpoints

Metodo	Ruta	Descripcion
GET	/api/hr/payroll-concepts	Listar conceptos
POST	/api/hr/payroll-concepts	Crear concepto
PATCH	/api/hr/payroll-concepts/:id	Editar concepto
DELETE	/api/hr/payroll-concepts/:id	Eliminar concepto
POST	/api/hr/payrolls/generate	Generar nominas del periodo
GET	/api/hr/payrolls	Listar nominas
GET	/api/hr/payrolls/:id	Ver nomina
PATCH	/api/hr/payrolls/:id	Editar nomina
POST	/api/hr/payrolls/:id/approve	Aprobar nomina
POST	/api/hr/payrolls/:id/pay	Marcar como pagada
POST	/api/hr/payrolls/:id/cancel	Anular nomina
GET	/api/hr/payrolls/:id/pdf	Generar PDF de nomina