Nóminas

Conceptos de nómina (Payroll Concepts)

Antes de generar nóminas, 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	Descripción	Ejemplos
earning	Devengo (lo que cobra el empleado)	Salario base, plus transporte, comisiones
deduction	Deducción (lo que se descuenta antes de IRPF)	Seguridad Social empleado, anticipos
tax	Impuesto (IRPF)	Retención IRPF
security_contribution	Aportación 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
  }
]

---

Nóminas 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 nóminas 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 según su tipo de cálculo
4. Genera las líneas de nómina
5. Calcula el neto

Ver nómina

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

Método	Ruta	Descripción
POST	/api/hr/payrolls/generate	Generar nóminas de un periodo
GET	/api/hr/payrolls	Listar nóminas
GET	/api/hr/payrolls/:id	Ver nómina
PATCH	/api/hr/payrolls/:id	Editar línea de nómina
POST	/api/hr/payrolls/:id/approve	Aprobar nómina
POST	/api/hr/payrolls/:id/pay	Marcar como pagada
POST	/api/hr/payrolls/:id/cancel	Anular nómina
GET	/api/hr/payrolls/:id/pdf	Generar pdf de nómina

---

Nóminas de todxs lxs empleados

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

Lista todas las nóminas de un periodo con el estado y el neto de cada una.

---

Marcado como pagado

Al marcar una nómina como pagada, se crea automáticamente 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

Método	Ruta	Descripción
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 nóminas del periodo
GET	/api/hr/payrolls	Listar nóminas
GET	/api/hr/payrolls/:id	Ver nómina
PATCH	/api/hr/payrolls/:id	Editar nómina
POST	/api/hr/payrolls/:id/approve	Aprobar nómina
POST	/api/hr/payrolls/:id/pay	Marcar como pagada
POST	/api/hr/payrolls/:id/cancel	Anular nómina
GET	/api/hr/payrolls/:id/pdf	Generar PDF de nómina