📝 Contratos

Descripción

Los endpoints de contratos te permiten automatizar la consulta del estado de un trabajador según su contrato en Dataemunah desde cualquier sistema externo entre otras funcionalidades más.

Verificar Contrato Activo

Verifica si un trabajador tiene un contrato activo vigente en el sistema.

Endpoint

GET /api/contratos/verificarContratoActivo

Parámetros de Consulta (Query Params)

Parámetro	Tipo	Requerido	Descripción
`tipoDocumento`	string	No	Tipo de documento del trabajador (ej: CC, TI, CE)
`numeroDocumento`	string	Sí	Número de documento de identidad del trabajador
`emailResponsable`	string	Sí	Correo electrónico del usuario administrador responsable

Autenticación

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

X-Api-Key: Bearer {tu_api_key}

Ejemplo de Petición

Ejemplo práctico en los headers

curl -X GET \
  'https://{{productionhost_dt_cohoriente}}/contratos/verificarContratoActivo?tipoDocumento=C.C&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
);

// Configuración de cURL
$ch =  curl_init();
curl_setopt($ch, CURLOPT_URL, URL_API . 'contratos/verificarContratoActivo?tipoDocumento=C.C&numeroDocumento=1101758869&emailResponsable=esteban.avila@conectera.co');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

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

Ejemplo de respuestas

✅ Éxito - Contrato Activo (200 OK)

{
  "success": true,
  "activo": true,
  "estado": "activo",
  "contrato": {
    "fechaInicio": "2025-09-01",
    "fechaFin": "2025-09-30",
    "esAdicional": true
  }
}

✅ Éxito - Sin Contrato Activo (200 OK)

{
  "success": true,
  "activo": false,
  "estado": "sin contrato"
}

✅ Éxito - Sin Contrato Registrado (200 OK)

{
  "success": true,
  "activo": false,
  "estado": "sin contrato registrado"
}

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

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

❌ Error - Acceso Denegado (403 Forbidden)

{
    "success": false,
    "status": 403,
    "error": {
        "message": "Acceso denegado. Tu no tienes los permisos necesarios para acceder a este recurso."
    }
}

❌ Error - Trabajador No Encontrado (404 Not Found)

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

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

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

❌ Error - Error del Servidor (500 Internal Server Error)

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

Lógica de Negocio

Este endpoint ejecuta 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.
Parámetros requeridos
- Confirma que se haya proporcionado el número de documento (numerodocumento) en la solicitud.
Búsqueda del trabajador
- Se realiza la búsqueda del trabajador en base al número de documento.
Verificación de usuario responsable
- Se valida que el correo (emailresponsable) corresponda a un usuario administrador válido.
**Registro de auditoría **
- Se guarda un historial de la solicitud, incluyendo el usuario responsable y los parámetros utilizados.
Validación de contratos
- Se verifica si el trabajador tiene contratos laborales registrados en el sistema.
Verificación de vigencia
- El sistema determina si el trabajador posee un contrato vigente, aplicando las siguientes condiciones:
  - La fecha de inicio del contrato es menor o igual a la fecha actual.
  - La fecha de fin del contrato es mayor o igual a la fecha actual.
  - El contrato no ha sido liquidado.