Comisiones

Comisiones

Modelo

interface Commission {
  id: string;
  employee_id: string;
  period: string;           // "2026-Q1", "2026-05"
  commission_type: 'sales' | 'profit' | 'collection' | 'custom';
  calculation_base: 'revenue' | 'profit' | 'volume';
  rate: number;            // Porcentaje (ej: 5.0 = 5%)
  fixed_amount?: number;    // Cantidad fija adicional
  base_amount: number;     // Importe base sobre el que se calcula
  commission_amount: number;
  status: 'pending' | 'calculated' | 'approved' | 'paid';
  paid_at?: string;
  paid_payroll_id?: string;  // Vinculado a la nomina donde se pagó
  notes?: string;
  created_at: string;
}

Tipos de comisión

Tipo	Descripción
sales	Por ventas realizadas (facturado)
profit	Por beneficios generados (margen)
collection	Por cobros realizados (porcentaje de lo cobrado)
custom	Formula personalizada

Base de cálculo

Base	Descripción
revenue	Sobre el importe facturado (sin impuestos)
profit	Sobre el margen de beneficio del documento
volume	Sobre el número de unidades vendidas

---

Endpoints

Método	Ruta	Descripción
GET	/api/hr/commissions	Listar comisiones
POST	/api/hr/commissions	Crear comisión
GET	/api/hr/commissions/:id	Ver comisión
PATCH	/api/hr/commissions/:id	Editar comisión
POST	/api/hr/commissions/:id/approve	Aprobar comisión
POST	/api/hr/commissions/:id/mark-paid	Marcar como pagada
DELETE	/api/hr/commissions/:id	Eliminar comisión

Crear comisión

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

{
  "employee_id": "emp_001",
  "period": "2026-Q1",
  "commission_type": "sales",
  "calculation_base": "revenue",
  "rate": 5.0,
  "fixed_amount": 100.00,
  "base_amount": 25000.00,
  "notes": "5% sobre facturacion + bono fijo de 100 EUR"
}

Respuesta:

{
  "data": {
    "id": "comm_001",
    "commission_amount": 1350.00,
    "calculation_detail": "5% de 25000.00 = 1250.00 + 100.00 fijo",
    "status": "calculated"
  }
}

Calcular comisiones automáticamente

POST /api/hr/commissions/calculate
Content-Type: application/json

{
  "period": "2026-Q1",
  "employee_ids": ["emp_001", "emp_002"],
  "calculation_base": "revenue"
}

Recorre todos los documentos facturados del periodo para cada empleado y calcula automáticamente las comisiones según la tasa configurada.

Listar comisiones por empleado

GET /api/hr/commissions?employee_id=emp_001&status=pending

---

Vinculación con nóminas

Las comisiones aprobadas se pueden incluir automáticamente en la nómina del siguiente periodo:

POST /api/hr/commissions/:id/approve

Las comisiones aprobadas aparecen como concepto en la nómina del empleado:

{
  "concept_name": "Comision Q1 2026",
  "amount": 1350.00,
  "type": "earning"
}

---

Resumen de endpoints

Método	Ruta	Descripción
GET	/api/hr/commissions	Listar comisiones
POST	/api/hr/commissions	Crear comisión
POST	/api/hr/commissions/calculate	Calcular automáticamente
GET	/api/hr/commissions/:id	Ver comisión
PATCH	/api/hr/commissions/:id	Editar comisión
POST	/api/hr/commissions/:id/approve	Aprobar
POST	/api/hr/commissions/:id/mark-paid	Marcar como pagada