Integra NexoLabor con tu sistema externo

1. Objetivo de la integración

La API de NexoLabor permite intercambiar información laboral entre la plataforma y sistemas externos. Está pensada para automatizar altas de empleados, consultar fichajes, sincronizar vacaciones, conectar clientes/proyectos y preparar informes para asesorías o departamentos de recursos humanos.

2. Requisitos previos

• Disponer de una empresa activa en NexoLabor.
• Acceder con un usuario administrador autorizado.
• Generar un token API desde Integraciones API.
• Usar siempre HTTPS.
• No compartir el token en frontend público, apps sin protección o repositorios.

3. Crear un token API

Entra en el panel de empresa o superadministrador y abre:

/integraciones/index.php

Crea un token con nombre descriptivo, por ejemplo:

Asesoría laboral - Lectura fichajes
ERP interno - Empleados y proyectos
App móvil empleados - Fichajes

Asigna solo los permisos necesarios. Evita usar * salvo en integraciones internas de confianza.

4. Autenticación

Todos los endpoints protegidos aceptan token por cabecera compatible:

Authorization: Bearer nl_TU_TOKEN_API

También puedes usar la cabecera simple:

token: nl_TU_TOKEN_API

Ejemplo mínimo:

curl --location 'https://nexolabor.com/api/v1/empresa.php' \
  --header 'Accept: application/json' \
  --header 'token: nl_TU_TOKEN_API'

5. Flujo recomendado de integración

1. Probar conexión: consultar /api/v1/empresa.php.
2. Sincronizar empleados: leer /api/v1/empleados.php.
3. Crear o actualizar datos: enviar JSON por POST en endpoints permitidos.
4. Consultar fichajes: filtrar por fecha y empleado.
5. Validar errores: gestionar respuestas 400, 401, 403 y 404.
6. Automatizar: programar sincronizaciones periódicas desde tu sistema.

6. Integrar empleados

Devuelve los empleados de la empresa vinculada al token.

curl --location 'https://nexolabor.com/api/v1/empleados.php' \
  --header 'token: nl_TU_TOKEN_API'

Permite crear un empleado si el token tiene permiso de escritura.

curl --location 'https://nexolabor.com/api/v1/empleados.php' \
  --header 'Content-Type: application/json' \
  --header 'token: nl_TU_TOKEN_API' \
  --data '{
    "nombre":"Empleado Demo",
    "dni":"00000000X",
    "correo":"empleado@empresa.com",
    "telefono":"600000000"
  }'

7. Integrar fichajes

Consulta fichajes por rango de fechas. Útil para asesorías, control horario y exportaciones.

curl --location 'https://nexolabor.com/api/v1/fichajes.php?desde=2026-06-01&hasta=2026-06-30' \
  --header 'token: nl_TU_TOKEN_API'

Crea un fichaje de entrada, salida o pausa.

curl --location 'https://nexolabor.com/api/v1/fichajes.php' \
  --header 'Content-Type: application/json' \
  --header 'token: nl_TU_TOKEN_API' \
  --data '{
    "id_empleado":15,
    "tipo":"entrada",
    "latitud":36.43,
    "longitud":-5.45,
    "origen":"api"
  }'

8. Integrar vacaciones

Obtiene solicitudes de vacaciones y sus estados.

Crea una nueva solicitud.

curl --location 'https://nexolabor.com/api/v1/vacaciones.php' \
  --header 'Content-Type: application/json' \
  --header 'token: nl_TU_TOKEN_API' \
  --data '{
    "id_empleado":15,
    "fecha_inicio":"2026-08-01",
    "fecha_fin":"2026-08-15",
    "motivo":"Vacaciones de verano"
  }'

9. Integrar clientes y proyectos

Los planes PRO pueden usar clientes y proyectos para asociar fichajes, costes y trabajos.

curl --location 'https://nexolabor.com/api/v1/proyectos.php' \
  --header 'Content-Type: application/json' \
  --header 'token: nl_TU_TOKEN_API' \
  --data '{"nombre":"Obra Centro","id_cliente":3,"estado":"activo"}'

10. Integrar gastos y justificantes

Permite consultar gastos registrados por empleados: dietas, kilometraje, comidas o importes asociados a proyectos.

curl --location 'https://nexolabor.com/api/v1/gastos.php' \
  --header 'Accept: application/json' \
  --header 'token: nl_TU_TOKEN_API'

11. Gestión de errores

{
  "ok": false,
  "error": "Token API no válido o inactivo"
}

12. Recomendaciones de seguridad

• Usa un token distinto por integración.
• Limita permisos por módulo.
• No pongas tokens en JavaScript público.
• Rota tokens periódicamente.
• Registra logs de llamadas importantes.
• Usa HTTPS siempre.
• Desactiva tokens que ya no se usen.

13. Ejemplo de integración en PHP

<?php
$token = 'nl_TU_TOKEN_API';
$url = 'https://nexolabor.com/api/v1/empleados.php';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'token: ' . $token,
    ],
]);

$respuesta = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($codigo !== 200) {
    throw new RuntimeException('Error API: ' . $respuesta);
}

$datos = json_decode($respuesta, true);
print_r($datos);
?>

14. Ejemplo de integración en JavaScript servidor

Este ejemplo debe ejecutarse en backend, no en navegador público.

const token = process.env.NEXOLABOR_TOKEN;

const res = await fetch('https://nexolabor.com/api/v1/fichajes.php?desde=2026-06-01', {
  headers: {
    'Accept': 'application/json',
    'token': token
  }
});

if (!res.ok) {
  throw new Error('Error API NexoLabor: ' + await res.text());
}

const data = await res.json();
console.log(data);