API y Desarrolladores

Documentación técnica para integrar otros sistemas con iKelma

API REST para desarrolladores

Esta documentación está orientada a desarrolladores e integradores técnicos que necesiten conectar iKelma con otros sistemas de su organización. Encontrarás información detallada sobre endpoints, autenticación, ejemplos de código y casos de uso comunes.

Introducción y autenticación Endpoints de fichajes Usuarios y empleados Integraciones y casos de uso

Introducción a la API

La API REST de ikelma permite a desarrolladores y terceros integrar las funcionalidades de gestión de presencia, fichajes y recursos humanos con sus propias aplicaciones y sistemas. Esta API sigue los estándares modernos de RESTful con versiones estables y documentadas.

Información general

URL Base:https://tu-dominio.com/api/v1
Formato de respuesta:JSON
Autenticación:Bearer Token JWT
Rate Limiting:100 peticiones por minuto por API Key

Autenticación y seguridad

La API de ikelma utiliza autenticación mediante tokens JWT (JSON Web Tokens) para garantizar el acceso seguro a los recursos. Todos los tokens expiran después de un período configurado y todas las comunicaciones deben realizarse a través de HTTPS.

Obtener un token de acceso

POST /auth/token
// Headers
Content-Type: application/json

// Body
{
  "username": "tu_usuario",
  "password": "tu_contraseña",
  "client_id": "tu_client_id",
  "client_secret": "tu_client_secret"
}

Respuesta exitosa

// Status: 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200641f3e..."
}

Uso del token en peticiones

Una vez obtenido el token, debe incluirse en todas las peticiones posteriores mediante el encabezado de autorización:

// Headers
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Renovación del token

Cuando un token está próximo a expirar, puede renovarse utilizando el refresh_token:

POST /auth/refresh
// Headers
Content-Type: application/json

// Body
{
  "refresh_token": "def50200641f3e...",
  "client_id": "tu_client_id",
  "client_secret": "tu_client_secret"
}

Seguridad importante

Nunca compartas tus credenciales de API o tokens de acceso. Almacena siempre las credenciales del cliente de forma segura y considera la implementación de políticas de rotación de secretos para evitar riesgos de seguridad.

Endpoints de fichajes

Los siguientes endpoints permiten gestionar todo lo relacionado con fichajes, desde registrar entradas y salidas hasta consultar históricos de jornadas y generar informes de presencia.

GET/fichajes

Obtiene un listado de fichajes aplicando los filtros especificados.

Parámetros de consulta

Parámetro	Tipo	Descripción
usuario_id	integer	ID del usuario
fecha_inicio	string (YYYY-MM-DD)	Fecha de inicio del periodo
fecha_fin	string (YYYY-MM-DD)	Fecha fin del periodo
estado	string	Estado del fichaje (entrada, salida, incidencia)
page	integer	Número de página (paginación)
limit	integer	Número de registros por página (max 100)

Respuesta

// Status: 200 OK
{
  "data": [
    {
      "id": 1245,
      "usuario_id": 105,
      "nombre_usuario": "María García",
      "tipo": "entrada",
      "fecha": "2025-05-28",
      "hora": "08:03:15",
      "ubicacion": "Oficina central",
      "dispositivo": "Web",
      "ip_address": "192.168.1.45",
      "validado": true
    },
    {
      "id": 1246,
      "usuario_id": 105,
      "nombre_usuario": "María García",
      "tipo": "salida",
      "fecha": "2025-05-28",
      "hora": "17:05:22",
      "ubicacion": "Oficina central",
      "dispositivo": "App móvil",
      "ip_address": "192.168.1.45",
      "validado": true
    }
  ],
  "pagination": {
    "total": 845,
    "page": 1,
    "limit": 10,
    "pages": 85
  }
}

POST/fichajes

Registra un nuevo fichaje (entrada o salida) para un usuario.

Cuerpo de la petición

{
  "usuario_id": 105,
  "tipo": "entrada", // entrada, salida
  "fecha": "2025-05-28", // Formato YYYY-MM-DD
  "hora": "08:03:15", // Formato HH:MM:SS
  "ubicacion": "Oficina central", // Opcional
  "coordenadas": { // Opcional
    "lat": 40.4168,
    "lng": -3.7038
  },
  "notas": "Entrada retrasada por tráfico" // Opcional
}

Respuesta

// Status: 201 Created
{
  "id": 1247,
  "usuario_id": 105,
  "tipo": "entrada",
  "fecha": "2025-05-28",
  "hora": "08:03:15",
  "ubicacion": "Oficina central",
  "dispositivo": "API",
  "ip_address": "192.168.1.45",
  "validado": true,
  "created_at": "2025-05-28T08:03:15.000Z"
}

GET/fichajes/{id}

Obtiene detalles completos de un fichaje específico.

Parámetros de ruta

Parámetro	Tipo	Descripción
id	integer	ID del fichaje

Respuesta

// Status: 200 OK
{
  "id": 1245,
  "usuario_id": 105,
  "nombre_usuario": "María García",
  "tipo": "entrada",
  "fecha": "2025-05-28",
  "hora": "08:03:15",
  "ubicacion": "Oficina central",
  "coordenadas": {
    "lat": 40.4168,
    "lng": -3.7038
  },
  "dispositivo": "Web",
  "ip_address": "192.168.1.45",
  "validado": true,
  "notas": "",
  "validado_por": null,
  "fecha_validacion": null,
  "created_at": "2025-05-28T08:03:15.000Z",
  "updated_at": "2025-05-28T08:03:15.000Z"
}

PUT/fichajes/{id}

Modifica un fichaje existente. Requiere permisos de administrador.

Cuerpo de la petición

{
  "fecha": "2025-05-28", // Opcional
  "hora": "08:00:00", // Opcional
  "tipo": "entrada", // Opcional
  "validado": true, // Opcional
  "notas": "Fichaje corregido por administrador" // Opcional
}

Respuesta

// Status: 200 OK
{
  "id": 1245,
  "usuario_id": 105,
  "tipo": "entrada",
  "fecha": "2025-05-28",
  "hora": "08:00:00",
  "ubicacion": "Oficina central",
  "validado": true,
  "notas": "Fichaje corregido por administrador",
  "validado_por": 1,
  "fecha_validacion": "2025-05-28T10:15:30.000Z",
  "updated_at": "2025-05-28T10:15:30.000Z"
}

Webhooks de fichajes

Puedes configurar webhooks para recibir notificaciones en tiempo real cuando se produzcan eventos relacionados con los fichajes, como nuevos registros, modificaciones por administradores o incidencias detectadas.

La configuración de los webhooks se realiza en el panel de administración de la API: Configuración → API → Webhooks

Endpoints de usuarios y empleados

Estos endpoints permiten gestionar usuarios y empleados dentro del sistema iKelma, desde la creación y modificación de perfiles hasta la asignación de roles y permisos.

GET/usuarios

Obtiene un listado paginado de usuarios con sus datos básicos.

Parámetros de consulta

Parámetro	Tipo	Descripción
nombre	string	Filtrar por nombre
email	string	Filtrar por email
departamento_id	integer	Filtrar por departamento
rol	string	Filtrar por rol (admin, empleado, supervisor)
activo	boolean	Estado del usuario (true/false)
page	integer	Número de página
limit	integer	Registros por página (max 50)

Respuesta

// Status: 200 OK
{
  "data": [
    {
      "id": 105,
      "nombre": "María García",
      "apellidos": "López Martínez",
      "email": "[email protected]",
      "rol": "empleado",
      "departamento_id": 3,
      "departamento_nombre": "Recursos Humanos",
      "activo": true,
      "ultima_conexion": "2025-06-07T08:30:15.000Z"
    },
    {
      "id": 106,
      "nombre": "Carlos",
      "apellidos": "Rodríguez Sánchez",
      "email": "[email protected]",
      "rol": "supervisor",
      "departamento_id": 5,
      "departamento_nombre": "Desarrollo",
      "activo": true,
      "ultima_conexion": "2025-06-06T18:45:22.000Z"
    }
  ],
  "pagination": {
    "total": 156,
    "page": 1,
    "limit": 10,
    "pages": 16
  }
}

POST/usuarios

Crea un nuevo usuario en el sistema. Requiere permisos de administrador.

Cuerpo de la petición

{
  "nombre": "Laura",
  "apellidos": "Martínez Fuentes",
  "email": "[email protected]",
  "telefono": "612345789", // Opcional
  "rol": "empleado",
  "departamento_id": 3,
  "jefe_id": 106, // ID del supervisor directo (opcional)
  "horario_id": 2, // Opcional
  "password": "Contraseña_Temporal123", // Opcional, si no se proporciona se generará automáticamente
  "enviar_email_bienvenida": true, // Opcional, por defecto es true
  "datos_adicionales": { // Opcional
    "puesto": "Analista de RRHH",
    "ubicacion": "Oficina central"
  }
}

Respuesta

// Status: 201 Created
{
  "id": 157,
  "nombre": "Laura",
  "apellidos": "Martínez Fuentes",
  "email": "[email protected]",
  "rol": "empleado",
  "departamento_id": 3,
  "departamento_nombre": "Recursos Humanos",
  "jefe_id": 106,
  "horario_id": 2,
  "activo": true,
  "created_at": "2025-06-07T13:40:22.000Z",
  "email_enviado": true
}

GET/usuarios/{id}

Obtiene información detallada de un usuario específico.

Parámetros de ruta

Parámetro	Tipo	Descripción
id	integer	ID del usuario

Respuesta

// Status: 200 OK
{
  "id": 105,
  "nombre": "María",
  "apellidos": "García López",
  "email": "[email protected]",
  "telefono": "612345678",
  "rol": "empleado",
  "departamento_id": 3,
  "departamento_nombre": "Recursos Humanos",
  "jefe_id": 106,
  "jefe_nombre": "Carlos Rodríguez",
  "horario_id": 1,
  "horario_nombre": "Jornada completa (9 a 18h)",
  "activo": true,
  "fecha_alta": "2023-03-15",
  "ultima_conexion": "2025-06-07T08:30:15.000Z",
  "permisos": ["gestion_ausencias", "visualizacion_informes"],
  "perfil": {
    "foto_url": "https://api.empresa.com/usuarios/105/foto",
    "puesto": "Técnico de RRHH",
    "ubicacion": "Oficina central",
    "extension": "2345"
  },
  "historial_departamentos": [
    {
      "departamento_id": 4,
      "departamento_nombre": "Marketing",
      "fecha_inicio": "2023-03-15",
      "fecha_fin": "2024-01-10"
    },
    {
      "departamento_id": 3,
      "departamento_nombre": "Recursos Humanos",
      "fecha_inicio": "2024-01-11",
      "fecha_fin": null
    }
  ]
}

PUT/usuarios/{id}

Actualiza la información de un usuario existente.

Cuerpo de la petición

{
  "nombre": "María Isabel", // Opcional
  "apellidos": "García López", // Opcional
  "email": "[email protected]", // Opcional
  "telefono": "612345678", // Opcional
  "rol": "supervisor", // Opcional
  "departamento_id": 3, // Opcional
  "jefe_id": 102, // Opcional
  "horario_id": 2, // Opcional
  "activo": true, // Opcional
  "datos_adicionales": { // Opcional
    "puesto": "Responsable de RRHH",
    "ubicacion": "Oficina central"
  }
}

Respuesta

// Status: 200 OK
{
  "id": 105,
  "nombre": "María Isabel",
  "apellidos": "García López",
  "email": "[email protected]",
  "rol": "supervisor",
  "departamento_id": 3,
  "departamento_nombre": "Recursos Humanos",
  "jefe_id": 102,
  "activo": true,
  "updated_at": "2025-06-07T13:45:30.000Z"
}

Acceso a datos adicionales

También existen endpoints específicos para gestionar aspectos relacionados con los usuarios:

GET /usuarios/{id}/ausencias - Historial de ausencias y vacaciones
GET /usuarios/{id}/jornadas - Resumen de jornadas laborales
GET /usuarios/{id}/permisos - Permisos asignados
POST /usuarios/{id}/imagen - Actualizar imagen de perfil

Integraciones y casos de uso

La API de ikelma ha sido diseñada para facilitar la integración con una amplia variedad de sistemas y herramientas, permitiendo una gestión unificada de la presencia laboral y los recursos humanos dentro de tu ecosistema tecnológico.

Webhooks

Los webhooks permiten a tu aplicación recibir notificaciones en tiempo real cuando ocurren eventos específicos en ikelma, como nuevos fichajes, solicitudes de ausencia o cambios en los calendarios laborales.

Configuración de webhooks

POST /webhooks
// Headers
Content-Type: application/json
Authorization: Bearer {token}

// Body
{
  "url": "https://tu-aplicacion.com/webhooks/ikelma",
  "eventos": ["fichaje.nuevo", "fichaje.modificado", "ausencia.solicitada"],
  "activo": true,
  "secret": "tu_clave_secreta_para_validar_firmas"
}

Formato de notificación

Cuando ocurre un evento, ikelma enviará una petición POST a tu URL con los siguientes datos:

{
  "id": "evt_123456789",
  "evento": "fichaje.nuevo",
  "timestamp": "2025-06-07T13:45:22.000Z",
  "datos": {
    "fichaje_id": 1247,
    "usuario_id": 105,
    "tipo": "entrada",
    "fecha": "2025-06-07",
    "hora": "08:03:15"
  },
  "firma": "sha256=5a22defa..."
}

Integración con sistemas de RRHH

ikelma puede integrarse con los principales sistemas de RRHH y nóminas para sincronizar datos de empleados, horas trabajadas y ausencias.

SAP SuccessFactors

Sincroniza empleados, departamentos, horarios y exporta informes de presencia y fichajes.

GET /integracion/sap/sync

Workday

Automatiza el flujo de datos entre ikelma y Workday para una gestión unificada.

GET /integracion/workday/status

Oracle HCM

Integra la gestión de presencia con Oracle Human Capital Management.

POST /integracion/oracle/empleados/sync

A3 Equipo

Conecta con A3 Equipo para la gestión de nóminas y recursos humanos.

POST /integracion/a3/export

Para cada integración específica, consulta la documentación detallada en la secciónIntegracionesdel panel de administración.

Casos de uso comunes

Sincronización con ERP

Integra iKelma con tu sistema ERP para mantener actualizada la información de empleados y automatizar el proceso de cálculo de horas trabajadas para nóminas.

Ejemplo: Exportar horas trabajadas por departamento

GET /informes/horas-trabajadas?departamento_id=3&fecha_inicio=2025-05-01&fecha_fin=2025-05-31&formato=json

Aplicaciones móviles personalizadas

Desarrolla aplicaciones móviles personalizadas para tu empresa que se integren con la API de ikelma para la gestión de fichajes y ausencias.

Ejemplo: Registrar un fichaje desde app móvil

POST /fichajes
{
  "usuario_id": 105,
  "tipo": "entrada",
  "fecha": "2025-06-07",
  "hora": "08:03:15",
  "ubicacion": "Oficina central",
  "coordenadas": {
    "lat": 40.4168,
    "lng": -3.7038
  },
  "dispositivo_info": {
    "tipo": "android",
    "version": "14.0",
    "modelo": "Pixel 7"
  }
}

Integración con calendarios

Sincroniza las ausencias y vacaciones de ikelma con Google Calendar, Microsoft Outlook o cualquier sistema compatible con iCal.

Ejemplo: Obtener calendario de ausencias

GET /ausencias/calendario/equipo/5?formato=ical

SDKs y librerías cliente

Para facilitar la integración con ikelma, proporcionamos SDKs oficiales y librerías cliente en varios lenguajes de programación:

Ejemplo de uso con JavaScript

import { IkelmaClient } from 'ikelma-sdk';

// Inicializar cliente
const ikelma = new IkelmaClient({
  apiKey: 'tu_api_key',
  apiSecret: 'tu_api_secret'
});

// Obtener listado de fichajes
const fichajes = await ikelma.fichajes.listar({
  fecha_inicio: '2025-06-01',
  fecha_fin: '2025-06-07',
  usuario_id: 105
});

console.log(fichajes.data);

Soporte y recursos adicionales

Para obtener ayuda adicional con la integración de la API de ikelma, no dudes en contactar con nuestro equipo de soporte o consultar los siguientes recursos:

API y Desarrolladores

API REST para desarrolladores

Introducción a la API

Información general

Autenticación y seguridad

Obtener un token de acceso

Respuesta exitosa

Uso del token en peticiones

Renovación del token

Seguridad importante

Endpoints de fichajes

Parámetros de consulta

Respuesta

Cuerpo de la petición

Respuesta

Parámetros de ruta

Respuesta

Cuerpo de la petición

Respuesta

Webhooks de fichajes

Endpoints de usuarios y empleados

Parámetros de consulta

Respuesta

Cuerpo de la petición

Respuesta

Parámetros de ruta

Respuesta

Cuerpo de la petición

Respuesta

Acceso a datos adicionales

Integraciones y casos de uso

Webhooks

Configuración de webhooks

Formato de notificación

Integración con sistemas de RRHH

SAP SuccessFactors

Workday

Oracle HCM

A3 Equipo

Casos de uso comunes

Sincronización con ERP

Aplicaciones móviles personalizadas

Integración con calendarios

SDKs y librerías cliente

JavaScript

Python

PHP

C#

Soporte y recursos adicionales

Artículos relacionados