Vacaciones - Consultar Datos de Vacaciones

Descripción

Este endpoint proporciona los datos esenciales previos al cálculo de vacaciones de un trabajador. Consulta días laborados, vacaciones disponibles, ingreso base de cotización (IBC) y toda

Endpoint disponible

📋 Consultar Datos de Vacaciones

Recupera información previa necesaria para el proceso de solicitud de vacaciones: días disponibles y causados, IBC del trabajador, y los parámetros configurados en el contrato empresa.

GET /api/vacaciones/consultdatavacations

Autenticación

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

X-Api-Key: Bearer {tu_api_key}

Parámetros (Query Params)

Parámetro	Tipo	Requerido	Descripción
`numeroDocumento`	string	Sí	Número de documento de identidad del trabajador
`emailResponsable`	string	Sí	Correo electrónico del usuario administrador responsable

Ejemplo de Petición

Ejemplo práctico en los headers

curl -X GET \
  'https://{{localhost_dt_cohoriente}}/vacaciones/consultdatavacations?numeroDocumento=1101758869&emailResponsable=esteban.avila@conectera.co' \
  -H 'X-Api-Key: Bearer {tu_api_key}'

Ejemplo práctico de uso en PHP

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

// Parámetros de consulta
$queryParams = http_build_query([
    'numeroDocumento' => '1101758869',
    'emailResponsable' => 'esteban.avila@conectera.co'
]);

// Configuración de cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, URL_API . 'vacaciones/consultdatavacations?' . $queryParams);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// 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);
}

Ejemplo de respuestas

✅ Éxito - Consulta Exitosa (200 OK)

{
  "success": true,
  "asociadoId": 123,
  "diasLaboradosNomina": 360,
  "vacacionesDisponibles": 15,
  "ibcUltimoMes": 1500000,
  "parametrizacion": {
    "diasVacacionesAnuales": 15,
    "diasMinimosDisfrutados": 6,
    "vacacionesAnticipadas": true,
    "diasVacacionesAnticipadas": 3,
    "numeroPersonasVacaciones": 2
  }
}

✅ Éxito - Sin Contratos (200 OK)

{
  "success": true,
  "activo": false,
  "estado": "sin contratos"

}

✅ Éxito - Sin Parametrización (200 OK)

{
  "success": true,
  "activo": false,
  "estado": "sin información de parametrización de vacaciones en contrato empresa"

}

❌ Error - Parámetro Faltante (400 Bad Request)

{
  "success": false,
  "statusCode": 400,
  "message": "El número de documento es obligatorio."
}

```json
{
  "success": false,
  "statusCode": 400,
  "message": "El correo del responsable es obligatorio."
}

❌ Error - Trabajador No Encontrado (404 Not Found)

{
  "success": false,
  "statusCode": 404,
  "message": "Trabajador no encontrado."
}

❌ Error - Usuario No Encontrado (404 Not Found)

{
  "success": false,
  "statusCode": 404,
  "message": "Usuario administrador no encontrado para el correo proporcionado."
}

❌ Error - Reglas de Negocio (422 Unprocessable Entity)

{
  "success": false,
  "statusCode": 422,
  "message": "El contrato no tiene fechas de inicio o fin configuradas correctamente."
}

{
  "success": false,
  "statusCode": 422,
  "message": "El contrato no tiene asociado un contrato empresa válido."
}

{
  "success": false,
  "statusCode": 422,
  "message": "No se encuentra configurado el nivel de riesgo del contrato."
}

❌ Error - Error Interno (500 Internal Server Error)

{
  "success": false,
  "statusCode": 500,
  "message": "No fue posible calcular los días de vacaciones."
}

{
  "success": false,
  "statusCode": 500,
  "message": "No fue posible registrar la auditoría de la consulta."
}

{
  "success": false,
  "statusCode": 500,
  "message": "Error interno del servidor."
}

Lógica de Negocio

Este endpoint ejecuta las siguientes operaciones para obtener los datos de vacaciones:

Validaciones realizadas

Autenticación
- Verifica que el API Key esté presente en el encabezado X-Api-Key
- Valida que el token sea válido y autorizado
Método HTTP
- Confirma que la petición sea de tipo GET
Parámetros requeridos
- Valida que el número de documento esté presente
- Valida que el email del responsable esté presente
Búsqueda del trabajador
- Busca al asociado por número de documento
- Obtiene el ID interno del asociado
Búsqueda del usuario responsable
- Verifica que el email corresponda a un usuario administrador válido
- Obtiene el ID del usuario para auditoría
Validación de contratos
- Obtiene todos los contratos del asociado
- Valida que existan contratos activos
- Verifica que las fechas de inicio y fin estén configuradas
- Valida que exista un contrato empresa asociado
Cálculo de vacaciones
- Calcula días laborados en nómina según el rango de fechas del contrato
- Calcula días de vacaciones disponibles acumulados
Obtención del IBC
- Consulta la compensación básica del último mes liquidado en la sábana submensual
- Si no existe, toma el sueldo base del último contrato
Parametrización del contrato empresa
- Obtiene la configuración de vacaciones del contrato empresa
- Determina días anuales según nivel de riesgo (alto riesgo: 4-5 vs normal)
- Extrae días mínimos disfrutados, vacaciones anticipadas y máximo de personas
Auditoría
- Registra en el historial del contrato empresa la acción de consulta
- Almacena el ID del usuario que realizó la consulta

Campos de Respuesta

Parámetro	Tipo	Descripción
`asociadoId`	number	ID interno del asociado en el sistema
`diasLaboradosNomina`	number	Total de días laborados registrados en nómina
`vacacionesDisponibles`	number	Días de vacaciones acumulados y disponibles
`ibcUltimoMes`	number	Ingreso Base de Cotización del último mes liquidado
`parametrizacion.diasVacacionesAnuales`	number	Días de vacaciones que se causan anualmente según nivel riesgo
`parametrizacion.diasMinimosDisfrutados`	number	Cantidad mínima de días para vacaciones disfrutadas
`parametrizacion.vacacionesAnticipadas`	boolean	Indica si se permiten vacaciones anticipadas
`parametrizacion.diasVacacionesAnticipadas`	number	Días máximos que se pueden tomar anticipadamente
`parametrizacion.numeroPersonasVacaciones`	number	Máximo de personas que pueden estar de vacaciones simultáneamente por subgerencia