Vacaciones - Editar vacaciones

Descripción

El endpoint de edición de vacaciones permite actualizar registros existentes de vacaciones de trabajadores a través de la API de Dataemunah. Este endpoint está diseñado específicamente para la integración entre las plataformas Dataemunah (gestión de nómina) y Colab (gestión logística).

Importante: En Dataemunah no existe una actualización directa de registros. El proceso de edición siempre ejecuta una eliminación del registro anterior seguida de la creación de uno nuevo con los datos actualizados. Este enfoque garantiza:

Integridad completa de los datos
Trazabilidad y auditoría de todos los cambios
Validación exhaustiva antes de cualquier modificación
Generación de un nuevo código PILA único para cada edición

El endpoint valida primero que el registro exista y que cumpla con todas las reglas de negocio antes de proceder con la eliminación, minimizando así el riesgo de pérdida de datos.

Endpoint disponible

✏️ Editar vacaciones

Edita un registro de vacaciones existente mediante eliminación del registro anterior y creación de uno nuevo con los datos actualizados. Este proceso garantiza la integridad de los datos y mantiene la auditoría completa.

POST /api/vacaciones/edit

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
`codigoPila`	string	Sí	Código PILA único del registro de vacaciones a editar
`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/edit' \
  -H 'X-Api-Key: Bearer {tu_api_key}' \
  -F 'codigoPila=VAC_1759780755_9535_87c1b528' \
  -F 'documentoAsociado=1101758869' \
  -F 'vacFechaInicio=2025-09-21' \
  -F 'vacDiasVacaciones=2' \
  -F 'vacPagado=0' \
  -F 'vaclaboraSabado=1' \
  -F 'vacCompensado=0' \
  -F 'vacSeguridadEnNomina=1' \
  -F 'emailUserResponsable=esteban.avila@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(
    'codigoPila' => 'VAC_1759780755_9535_87c1b528',
    'documentoAsociado' => '1101758869',
    'vacFechaInicio' => '2025-09-21',
    'vacDiasVacaciones' => 2,
    'vacPagado' => 0,
    'vaclaboraSabado' => 1,
    'vacCompensado' => 0,
    'vacSeguridadEnNomina' => 1,
    'emailUserResponsable' => 'esteban.avila@conectera.co'
);

// Configuración de cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, URL_API . 'vacaciones/edit');
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
    echo "Vacaciones editadas correctamente\n";
    echo "Código PILA anterior: " . $api_response['data']['codigoPilaAnterior'] . "\n";
    echo "Código PILA nuevo: " . $api_response['data']['codigoPilaNuevo'] . "\n";
    echo "ID nuevo registro: " . $api_response['data']['id'];
}

Ejemplo de Respuestas

✅ Éxito - Edición Exitosa (200 OK)

{
  "success": true,
  "statusCode": 200,
  "message": "Vacaciones editadas correctamente",
  "data": {
    "id": 789,
    "codigoPilaAnterior": "VAC_1759780755_9535_87c1b528",
    "codigoPilaNuevo": "VAC_1728234567_1234_b8e2c9f3",
    "fechaEdicion": "2025-10-06 14:30:25",
    "vacaciones": {
      "vacAsociado": 123,
      "vacFechaInicio": "2025-09-21",
      "vacFechaFinal": "2025-09-23",
      "vacDiasVacaciones": 2,
      "vacDiasCalendario": 3,
      "vacSalario": 1500000,
      "vacValorTotal": 100000,
      "vacCodigoPila": "VAC_1728234567_1234_b8e2c9f3"
    }
  }
}

❌ Error - Código PILA No Encontrado (404 Not Found)

{
  "success": false,
  "statusCode": 404,
  "message": "Registro de vacaciones no encontrado",
  "errors": {
    "codigoPila": "No existe un registro con el código PILA proporcionado"
  }
}

❌ Error - Campos Requeridos Faltantes (400 Bad Request)

{
  "success": false,
  "statusCode": 400,
  "message": "Datos requeridos faltantes",
  "errors": {
    "codigoPila": "El código PILA es obligatorio para editar",
    "vacfechainicio": "El campo 'Fecha de inicio' es requerido"
  }
}

❌ Error - Usuario Responsable No Encontrado (404 Not Found)

{
  "success": false,
  "statusCode": 404,
  "message": "Usuario responsable no encontrado",
  "errors": {
    "emailUserResponsable": "El email proporcionado no está registrado en el sistema"
  }
}

❌ Error - Inconsistencia de Datos (400 Bad Request)

{
  "success": false,
  "statusCode": 400,
  "message": "Validación fallida: datos inconsistentes",
  "errors": {
    "inconsistencia": "El código PILA proporcionado no pertenece al trabajador con el documento especificado"
  }
}

❌ Error - Vacaciones Ya Aprobadas (422 Unprocessable Entity)

{
  "success": false,
  "statusCode": 422,
  "message": "No se puede editar. Las vacaciones ya están aprobadas",
  "errors": {
    "detalle": "Las vacaciones están aprobadas y no pueden ser modificadas"
  }
}

❌ Error - Validación de Reglas de Negocio Fallida (422 Unprocessable Entity)

{
  "success": false,
  "statusCode": 422,
  "message": "No se puede editar. Validación de datos falló",
  "errors": [
    "Las vacaciones disfrutadas deben ser de mínimo 6 días. Días solicitados: 2",
    "No hay suficientes días de vacaciones disponibles"
  ]
}

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

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

Lógica de Negocio del Endpoint de Edición

El endpoint de edición ejecuta un proceso de eliminación + creación con validaciones exhaustivas para garantizar la integridad de los datos. A continuación se detalla el flujo completo:

Flujo de Validación y Procesamiento

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 POST.
Validación de Campos Requeridos
- Código PILA: Campo obligatorio único para identificar el registro a editar.
- Email del usuario responsable: Valida formato y existencia del usuario administrador.
- Documento del asociado: Verifica que el trabajador exista en el sistema.
- Fecha de inicio y días de vacaciones: Valida formato y valores numéricos.
Validación de Existencia del Registro
- Busca el registro de vacaciones por el código PILA proporcionado.
- Si no existe, devuelve error 404 inmediatamente.
Validación de Consistencia
- Verifica que el código PILA corresponda al trabajador especificado por documento.
- Previene modificaciones cruzadas entre diferentes empleados.
Pre-validación de Reglas de Negocio (Antes de eliminar)
- Crítico: Simula el procesamiento completo ANTES de eliminar el registro anterior.
- Valida todas las reglas de negocio con los nuevos datos:
  - Días disponibles suficientes
  - Días mínimos disfrutados (si aplica)
  - Vacaciones anticipadas permitidas
  - Límites de concurrencia por subgerencia
  - Cruces de fechas con otras vacaciones
- Si falla cualquier validación, NO se elimina el registro y se devuelve error 422.
Eliminación del Registro Anterior
- Solo se ejecuta si todas las validaciones previas fueron exitosas.
- Valida que las vacaciones NO estén aprobadas (si están aprobadas, devuelve error 422).
- Ejecuta eliminación lógica con auditoría completa.
Creación del Nuevo Registro
- Calcula automáticamente fecha final, valor total y días calendario.
- Genera nuevo código PILA único.
- Guarda el nuevo registro con todos los datos actualizados.
- Procesa amortizaciones asociadas si existen.
Auditoría Completa
- Registra inicio de edición con código PILA anterior.
- Registra eliminación exitosa.
- Registra creación del nuevo registro.
- Registra cualquier error en cualquier etapa del proceso.
- Mantiene trazabilidad completa con IDs anterior y nuevo.

Consideraciones importantes

No hay actualización parcial: Siempre se elimina completamente el registro anterior y se crea uno nuevo.
Proceso transaccional: Si la creación falla después de la eliminación, se registra como error crítico en logs.
Sin rollback automático: El sistema no revierte la eliminación si falla la creación (esto se registra como error crítico).
Validación preventiva: La pre-validación antes de eliminar minimiza la posibilidad de errores críticos.
Vacaciones aprobadas: No se pueden editar registros que ya han sido aprobados en el sistema.
Código PILA único: Cada edición genera un nuevo código PILA, manteniendo el anterior para referencia.

Estados HTTP Retornados

Código	Significado	Descripción
200	OK	Edición exitosa, registro actualizado correctamente
400	Bad Request	Datos inválidos, campos faltantes o inconsistencia de datos
404	Not Found	Registro no encontrado, asociado no existe o usuario responsable no encontrado
405	Method Not Allowed	Se usó un método HTTP diferente a POST
422	Unprocessable Entity	Validaciones de negocio fallidas o vacaciones ya aprobadas
500	Internal Server Error	Error crítico en eliminación o creación