Remuneraciones API

API · Remuneraciones

APIOrchestratorRemuneraciones

Propósito

Esta página es el índice técnico de los endpoints HTTP del dominio de remuneraciones. Su función es ubicar qué familia de rutas expone cada capacidad y enlazarla con la documentación de dominio en Orchestrator, la lectura contable y las vistas de Sevastopol.

No reemplaza la documentación funcional de remuneraciones ni la explicación contable bajo NIC 19. Es la entrada para desarrolladores que necesitan ubicar rutas REST, contratos de entrada y servicios responsables.

Mapa de Familias

Familia	Rutas base	Servicio responsable	Vista relacionada
Empleados	/api/employees	EmployeeService	Empleados en Sevastopol
Contratos	/api/contracts	ContractService	Contratos en Sevastopol
Departamentos	/api/departments, /api/query/departments	Ruta de departamentos	Cargos y contratos
Cargos	/api/cargos, /api/query/cargos	CargoService	Contratos
Jornadas	/api/working_day, /api/query/working-days	WorkingDayService	Contratos y asistencia
Asistencia	/api/attendance	AttendanceService	Cálculo de remuneraciones
Liquidaciones	/api/remuneraciones/payroll	PayrollService	Cálculo de remuneraciones
Vacaciones	/api/vacations	VacationService	Asistencia y finiquitos
Permisos	/api/permissions	PermissionService	Asistencia y liquidaciones
Finiquitos	/api/finiquitos	FiniquitoService	Finiquitos
Documentos PDF	/api/contracts/:id/download, /api/remuneraciones/payroll/:id/pdf, /api/finiquitos/:id/pdf	Servicios de dominio	Descarga documental
Parámetros	/api/afp, /api/isapre, /api/previsiones, /api/common	Servicios de catálogos y previsión	Contratos y cálculo mensual

Flujo Técnico

1. La island de Sevastopol llama a una ruta local bajo /api.

2. El proxy local adjunta credenciales y reenvía la solicitud a Orchestrator.

3. Orchestrator autentica, resuelve tenant y obtiene conexión a la base correspondiente.

4. El endpoint delega al servicio de dominio.

5. El servicio valida, hidrata contexto, persiste o calcula y devuelve JSON en snake_case.

Empleados

Los endpoints de empleados mantienen el maestro de trabajadores usado por contratos, asistencia, liquidaciones y finiquitos.

Método	Ruta	Uso
GET	/api/employees	Lista empleados con filtros.
GET	/api/employees/:id	Obtiene un empleado específico.
POST	/api/employees	Crea un trabajador.
PUT	/api/employees/:id	Actualiza datos del trabajador.
DELETE	/api/employees/:id	Elimina o desactiva según regla vigente.

Consulta

GET /api/employees?rut=$RUT&estado=ACTIVO

[
  {
    "id": "$EMPLOYEE_ID",
    "rut": "$RUT",
    "nombres": "Juan",
    "apellido_paterno": "Pérez",
    "estado": "ACTIVO"
  }
]

Contratos

Los endpoints de contratos administran la relación laboral vigente: tipo de contrato, jornada, sueldo base, fechas, cargo y condiciones usadas por el cálculo mensual.

Método	Ruta	Uso
GET	/api/contracts	Lista contratos filtrables por empleado, estado o periodo.
GET	/api/contracts/:id	Obtiene contrato.
POST	/api/contracts	Crea contrato laboral.
PUT	/api/contracts/:id	Actualiza contrato.
GET	/api/contracts/:id/download	Descarga documento contractual cuando está disponible.

Los contratos se complementan con datos previsionales y de salud, especialmente AFP, APV, Fonasa o Isapre.

Departamentos, Cargos y Jornadas

Estos endpoints mantienen catálogos laborales usados por empleados, contratos y asistencia. No calculan remuneraciones por sí solos, pero parametrizan la estructura organizacional y la base horaria del cálculo.

Familia	Método	Ruta	Uso
Departamentos	GET	/api/query/departments	Lista áreas para selección y reportería.
Departamentos	POST	/api/departments	Crea o actualiza área organizacional según implementación vigente.
Cargos	GET	/api/query/cargos	Lista posiciones laborales.
Cargos	POST	/api/cargos	Crea cargo, código y descripción funcional.
Jornadas	GET	/api/query/working-days	Lista jornadas disponibles para contrato.
Jornadas	POST	/api/working_day	Crea jornada laboral y configuración horaria.

Catálogo	Relación principal	Lectura funcional
Departamentos	Empleados, cargos y centros de costo	Estructura organizacional y análisis de gasto.
Cargos	Contratos laborales	Función, jerarquía, banda salarial y aprobación.
Jornadas	Contratos y asistencia	Días esperados, horas pactadas y proporcionalidad.

Asistencia

Los endpoints de asistencia consolidan el tiempo trabajado y las novedades del periodo. Ese resumen alimenta directamente el cálculo de remuneraciones.

Método	Ruta	Uso
GET	/api/attendance	Lista registros de asistencia.
POST	/api/attendance	Registra o importa asistencia.
GET	/api/attendance/summary	Obtiene resumen mensual usado por payroll.

GET /api/attendance/summary?contrato_id=$CONTRATO_ID&periodo=2026-05

El resumen debe exponer días trabajados, ausencias, licencias, horas extra y otros datos que el motor necesite para calcular haberes y descuentos.

Vacaciones y Permisos

Estos endpoints administran ausencias justificadas y saldos que impactan asistencia, liquidaciones y finiquitos.

Familia	Método	Ruta	Uso
Vacaciones	GET	/api/vacations	Lista solicitudes y saldos de vacaciones.
Vacaciones	POST	/api/vacations	Crea solicitud con cálculo de días hábiles.
Permisos	GET	/api/permissions	Lista permisos, licencias y ausencias.
Permisos	POST	/api/permissions	Registra permiso o licencia.

Concepto	Efecto esperado
Vacaciones aprobadas	Consumen saldo y se reflejan como ausencia justificada.
Licencia médica	Puede excluir pago empresa y quedar como subsidio.
Permiso con goce	Mantiene remuneración si está aprobado.
Permiso sin goce	Genera descuento proporcional en payroll.

Liquidaciones

Los endpoints de liquidaciones orquestan el cálculo mensual. El patrón esperado separa previsualización, persistencia, consulta y emisión de PDF.

Método	Ruta	Uso
POST	/api/remuneraciones/payroll/generar	Ejecuta preview o guarda liquidación según flags.
GET	/api/remuneraciones/payroll	Lista liquidaciones por periodo o empleado.
GET	/api/remuneraciones/payroll/:id	Obtiene liquidación específica.
GET	/api/remuneraciones/payroll/:id/pdf	Genera o descarga PDF de liquidación.

Preview o Commit

{
  "contrato_id": "$CONTRATO_ID",
  "periodo_mes": "2026-05-01",
  "dry_run": true,
  "force": false
}

{
  "total_haberes": 2000000,
  "total_descuentos": 500000,
  "total_liquido": 1500000,
  "saved": false,
  "message": "DRY RUN"
}

Caution

La vista debe distinguir previsualización de persistencia. Un cálculo de preview no debe crear una liquidación definitiva ni afectar estados contables.

Finiquitos

Los endpoints de finiquitos cubren la simulación y generación del término de relación laboral. Usan empleado, contrato, vacaciones, remuneraciones y causal de término.

Método	Ruta	Uso
GET	/api/finiquitos	Lista finiquitos con filtros.
POST	/api/finiquitos/simulate	Simula montos antes de generar.
POST	/api/finiquitos	Genera finiquito definitivo.
GET	/api/finiquitos/:id	Obtiene detalle del finiquito.
GET	/api/finiquitos/:id/pdf	Descarga documento de finiquito.

Documentos PDF

La emisión PDF se mantiene asociada al servicio que origina el documento. No existe una familia funcional separada para calcular documentos; las rutas de descarga exponen contratos, liquidaciones y finiquitos ya validados por sus respectivos servicios.

Documento	Ruta	Servicio origen
Contrato laboral	GET /api/contracts/:id/download	ContractService
Liquidación de sueldo	GET /api/remuneraciones/payroll/:id/pdf	PayrollService
Finiquito	GET /api/finiquitos/:id/pdf	FiniquitoService

Caution

La regeneración documental no debe recalcular montos ni alterar estados funcionales. Si se fuerza una nueva emisión, debe quedar trazabilidad del usuario, fecha, motivo y documento de origen.

Parámetros

Los endpoints de parámetros entregan catálogos e indicadores usados por contratos y liquidaciones.

Familia	Rutas	Uso
AFP	/api/afp	Catálogo, tasas y cotización obligatoria.
Salud	/api/isapre	Catálogo de Isapres y contratos de salud.
Imposiciones	/api/previsiones	Consolidación previsional posterior a liquidaciones.
Indicadores	/api/common	UF, UTM, topes imponibles y parámetros legales.

La vigencia de indicadores es crítica. El cálculo mensual debe usar los parámetros del periodo liquidado, no necesariamente los valores vigentes al día de consulta.

Convenciones

Convención	Criterio
Fechas	Usar YYYY-MM-DD; para periodos mensuales usar primer día del mes.
Identificadores	Usar placeholders en documentación pública, como $CONTRATO_ID.
Respuestas	JSON en snake_case, alineado con columnas y DTOs del backend.
Tenant	Toda ruta operativa se resuelve contra el tenant autenticado o informado según proxy.
Errores	Validaciones de negocio deben volver 400 o 409 según corresponda.

Ver También

Employee Service Servicio backend para crear, validar y mantener empleados.

ContractService Servicio de contratos laborales, jornada, sueldo base y documentos.

AttendanceService Servicio de asistencia y resumen mensual usado por payroll.

PayrollService Servicio de cálculo, preview, persistencia y consulta de liquidaciones.

AfpService Servicio de catálogo y tasas previsionales.

IsapreService Servicio de instituciones y contratos de salud previsional.

PrevisionsService Servicio de generación y consolidación de imposiciones.

VacationService Servicio de solicitudes, saldos y días hábiles de vacaciones.

PermissionService Servicio de permisos, licencias y ausencias justificadas.

FiniquitoService Servicio de simulación y generación de finiquitos.

Servicio de Documentos PDF Lectura funcional de contratos, liquidaciones y finiquitos en PDF.

Remuneraciones en Sevastopol Mapa frontend de empleados, contratos y cálculo mensual.

Servicio de Empleados Lectura contable y operativa del maestro de trabajadores.

NIC 19 Beneficios a los Empleados Referencia IFRS para beneficios laborales devengados.