Vacaciones

Descripción

Los endpoints de vacaciones te permiten automatizar el cálculo y registro de vacaciones de trabajadores en Dataemunah desde cualquier sistema externo. Puedes calcular vacaciones sin guardarlas o crear registros definitivos con toda la información calculada automáticamente.

Endpoints disponibles

🧮 Calcular vacaciones

Calcula las vacaciones de un trabajador sin guardar el registro en el sistema. Útil para previsualizar el cálculo antes de confirmar.

POST /api/vacaciones/calculate

Autenticación Este endpoint requiere autenticación mediante API Key en el header:

X-Api-Key: Bearer {tu_api_key}

Parámetros (Form Data)

Parámetro	Tipo	Requerido	Descripción
`documentoAsociado`	string	Sí	Número de documento de identidad del trabajador
`vacFechaInicio`	string	Sí	Fecha de inicio de las vacaciones (formato: `YYYY-MM-DD`)
`vacDiasVacaciones`	number	Sí	Cantidad de días de vacaciones solicitados
`emailUserResponsable`	string	Sí	Correo electrónico del usuario administrador responsable
`vacPagado`	string	No	Indica si son vacaciones anticipadas: `"1"` = Sí, `"0"` = No (default)
`vacLaboraSabado`	string	No	Indica si el trabajador labora sábados: `"1"` = Sí, `"0"` = No (default)
`vacCompensado`	string	No	Indica si son vacaciones compensadas: `"1"` = Sí, `"0"` = No (default)
`vacSeguridadEnNomina`	string	No	Define si se toma seguridad social en nómina: `"1"` = Sí, `"0"` = No

Ejemplo de Petición

Ejemplo práctico en los headers

curl -X POST \
  'https://{{localhost_dt_cohoriente}}/vacaciones/calculate' \
  -H 'X-Api-Key: Bearer {tu_api_key}' \
  -F 'documentoAsociado=1101758869' \
  -F 'vacFechaInicio=2025-09-01' \
  -F 'vacDiasVacaciones=2' \
  -F 'vacPagado=0' \
  -F 'vacLaboraSabado=1' \
  -F 'vacCompensado=0' \
  -F 'vacSeguridadEnNomina=1' \
  -F 'emailUserResponsable=mateus.uribe@conectera.co'

Ejemplo práctico de uso en PHP

    // Configuración de los encabezados
$headers = array(
    'x-api-key: Bearer ' . $TOKEN
);

// Datos del formulario
$postData = array(
    'documentoAsociado' => '1101758869',
    'vacFechaInicio' => '2025-09-01',
    'vacDiasVacaciones' => 2,
    'vacPagado' => 0,
    'vacLaboraSabado' => 1,
    'vacCompensado' => 0,
    'vacSeguridadEnNomina' => 1,
    'emailUserResponsable' => 'mateus.uribe@conectera.co'
);

// Configuración de cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, URL_API . 'vacaciones/calculate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));

// Ejecutar la solicitud
$response = curl_exec($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Verificar si hubo errores en la solicitud cURL
if (curl_errno($ch))
{
    throw new Exception('Error en la solicitud: ' . curl_error($ch));
}

// Cerrar la sesión cURL
curl_close($ch);

if ($status_code === 200)
{
    $api_response = json_decode($response, TRUE);
    // Procesar respuesta
    print_r($api_response);
}

➕ Crear Vacaciones

Calcula y guarda el registro de vacaciones en el sistema de forma definitiva. Genera automáticamente un código único para la PILA.

POST /api/vacaciones/add

Autenticación Este endpoint requiere autenticación mediante API Key en el header:

X-Api-Key: Bearer {tu_api_key}

Parámetros (Form Data)

Parámetro	Tipo	Requerido	Descripción
`documentoAsociado`	string	Sí	Número de documento de identidad del trabajador
`vacFechaInicio`	string	Sí	Fecha de inicio de las vacaciones (formato: `YYYY-MM-DD`)
`vacDiasVacaciones`	number	Sí	Cantidad de días de vacaciones solicitados
`emailUserResponsable`	string	Sí	Correo electrónico del usuario administrador responsable
`vacPagado`	string	No	Indica si son vacaciones anticipadas: `"1"` = Sí, `"0"` = No (default)
`vacLaboraSabado`	string	No	Indica si el trabajador labora sábados: `"1"` = Sí, `"0"` = No (default)
`vacCompensado`	string	No	Indica si son vacaciones compensadas: `"1"` = Sí, `"0"` = No (default)
`vacSeguridadEnNomina`	string	No	Define si se toma seguridad social en nómina: `"1"` = Sí, `"0"` = No

Ejemplo práctico de uso en PHP

// Configuración de los encabezados
$headers = array(
    'x-api-key: Bearer ' . $TOKEN
);

// Datos del formulario
$postData = array(
    'documentoAsociado' => '1101758869',
    'vacFechaInicio' => '2025-09-01',
    'vacDiasVacaciones' => 2,
    'vacPagado' => 0,
    'vacLaboraSabado' => 1,
    'vacCompensado' => 0,
    'vacSeguridadEnNomina' => 1,
    'emailUserResponsable' => 'mateus.uribe@conectera.co'
);

// Configuración de cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, URL_API . 'vacaciones/add');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));

// Ejecutar la solicitud
$response = curl_exec($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Verificar si hubo errores en la solicitud cURL
if (curl_errno($ch))
{
    throw new Exception('Error en la solicitud: ' . curl_error($ch));
}

// Cerrar la sesión cURL
curl_close($ch);

if ($status_code === 201)
{
    $api_response = json_decode($response, TRUE);
    // Procesar respuesta
    echo "Vacaciones creadas con ID: " . $api_response['data']['id'];
    echo "Código PILA: " . $api_response['data']['codigo_pila'];
}

Ejemplo de respuestas para ambos endpoints

✅ Éxito - Cálculo Exitoso (200 OK)

Endpoint de calculo

{
  "success": true,
  "statusCode": 200,
  "message": "Cálculo de vacaciones exitoso",
  "data": {
    "vacAsociado": 123,
    "vacFechaInicio": "2025-09-01",
    "vacFechaFinal": "2025-09-03",
    "vacDiasVacaciones": 2,
    "vacDiasCalendario": 3,
    "vacSalario": 1500000,
    "vacValorTotal": 100000,
    "vacPagado": "0",
    "vacLaboraSabado": "1",
    "vacCompensado": "0",
    "vacSeguridadEnNomina": "1",
    "DiasDisponibles": 15,
    "diasCausados": 30
  }
}

Endpoint de creación

{
  "success": true,
  "statusCode": 201,
  "message": "Vacaciones creadas correctamente",
  "data": {
    "codigo_pila": "VAC_1727640123_5847_a3f8d9e1",
    "id": 456,
    "vacaciones": {
      "vacAsociado": 123,
      "vacFechaInicio": "2025-09-01",
      "vacFechaFinal": "2025-09-03",
      "vacDiasVacaciones": 2,
      "vacDiasCalendario": 3,
      "vacSalario": 1500000,
      "vacValorTotal": 100000,
      "vacCodigoPila": "VAC_1727640123_5847_a3f8d9e1"
    }
  }
}

❌ Error - Email Responsable Faltante (400 Bad Request)

{
  "success": false,
  "statusCode": 400,
  "message": "Email del usuario responsable es requerido",
  "errors": {
    "emailUserResponsable": "El email del usuario responsable es obligatorio"
  }
}

❌ Error - Datos Requeridos Faltantes (400 Bad Request)

{
  "success": false,
  "statusCode": 400,
  "message": "Datos requeridos faltantes",
  "errors": [
    "El campo 'ID del asociado' es requerido",
    "El campo 'Fecha de inicio' es requerido"
  ]
}

❌ Error - Método No Permitido (405 Method Not Allowed)

{
  "success": false,
  "statusCode": 405,
  "message": "Método no permitido. Use POST"
}

❌ Error - Reglas de Negocio (422 Unprocessable Entity)

{
  "success": false,
  "statusCode": 422,
  "message": "No se pueden procesar las vacaciones",
  "errors": [
    "Las vacaciones disfrutadas deben ser de mínimo 6 días. Días solicitados: 2",
    "No hay suficientes días de vacaciones disponibles"
  ]
}

Lógica de Negocio

Ambos endpoints ejecutan una serie de validaciones internas para asegurar la integridad y seguridad del proceso. A continuación, se detalla el flujo completo:

Validaciones realizadas

Autenticación
- Verifica que el API Key esté presente en el encabezado X-Api-Key.
- Se valida que el token sea válido y autorizado.
Método HTTP
- Confirma que la petición sea de tipo POST.
Email del usuario responsable
- Valida que se haya proporcionado el email del usuario responsable.
- Verifica que el email corresponda a un usuario administrador válido en el sistema.
Búsqueda del trabajador
- Se realiza la búsqueda del trabajador en base al número de documento.
- Se obtiene el ID interno del asociado para el procesamiento.
Campos requeridos
- Valida que estén presentes los campos obligatorios: ID del asociado, fecha de inicio y días de vacaciones.
- Verifica el formato correcto de la fecha (YYYY-MM-DD).
- Confirma que los días de vacaciones sean un valor numérico válido.
Procesamiento y cálculo
- Calcula automáticamente la fecha final según los días solicitados y si el trabajador labora sábados.
- Calcula el valor total a pagar según el salario y días solicitados.
- Determina los días disponibles y causados del trabajador para esa fecha.
Reglas de negocio
- Días disponibles: Valida que el trabajador tenga suficientes días de vacaciones acumulados.
- Días mínimos disfrutados: Si las vacaciones son disfrutadas (no compensadas), verifica que se cumpla el mínimo establecido por la empresa en el contrato.
- Vacaciones anticipadas: Si están marcadas como pagadas por anticipado, aplica las reglas especiales correspondientes.
- Concurrencia por subgerencia: Verifica que no se excedan los límites de personal en vacaciones simultáneas dentro de la misma subgerencia.
- Cruce de fechas: Valida que el trabajador no tenga otras vacaciones registradas en el mismo rango de fechas.
Guardado (solo para POST /add)
- Genera un código único de control PILA con el formato: VAC_[timestamp]_[random]_[hash].
- Guarda el registro de vacaciones en la base de datos.
- Procesa y guarda amortizaciones asociadas si existen.
- Registra una auditoría completa de la operación realizada.