Documentación API de Clocki

Autenticación

Todos los endpoints requieren un token de API válido que se envía como parámetro en cada petición.

Crear un Token

1. Accede al panel de administración de Clocki
2. Ve a Admin → API y Exportación
3. Click en "Nuevo Token"
4. Configura:
   • Descripción: Para qué usarás este token
   • Permisos: Qué endpoints puede acceder
   • Fecha de expiración: Opcional, para tokens temporales
5. Click en "Generar Token"
6. ¡Importante! Copia el token inmediatamente (solo se muestra una vez)

Usar el Token

Incluye el token como parámetro token en la URL de cada petición:

GET https://tu-servidor.com/clocki/api/export/users.php?token=TU_TOKEN_AQUI

Permisos Granulares

Puedes crear tokens con acceso solo a endpoints específicos:

• Solo lectura de usuarios: Acceso únicamente a /users.php
• Estadísticas completas: Acceso a estadísticas, fichajes y eventos
• Acceso total: Todos los endpoints disponibles

Gestión de Tokens

Desde el panel de administración puedes:

• Ver todos los tokens: Descripción, permisos, fechas
• Desactivar tokens: Sin eliminarlos (puedes reactivarlos)
• Eliminar tokens: Revocación inmediata de acceso
• Ver logs de acceso: Auditoría completa por token

Endpoints Disponibles

{
  "success": true,
  "data": [
    {
      "id": 5,
      "email": "juan@example.com",
      "first_name": "Juan",
      "last_name": "Pérez",
      "full_name": "Juan Pérez",
      "location": "Oficina Central",
      "schedule": "Horario Normal",
      "schedule_abbr": "HN",
      "active": true,
      "created_at": "2025-01-01 10:00:00"
    }
  ],
  "count": 1,
  "generated_at": "2025-11-17 12:00:00"
}

GET /api/export/punches.php?token=abc123&from=2025-01-01&to=2025-01-31&format=json

Otros Endpoints

Los siguientes endpoints funcionan de manera similar con parámetros token y format:

• /api/export/schedules.php - Horarios y turnos configurados
• /api/export/holidays.php - Festivos y días no laborables
• /api/export/locations.php - Ubicaciones y centros de trabajo
• /api/export/week_types.php - Tipos de semana (patrones horarios)
• /api/export/user_calendar.php - Planificación de jornadas de usuarios

Integraciones

🔷 PowerBI Desktop

Integra Clocki con PowerBI para crear dashboards ejecutivos en tiempo real.

Configuración Paso a Paso

1. Abrir PowerBI Desktop
2. Click en Obtener datos → Web
3. Seleccionar Avanzado
4. Configurar URL:

   https://tu-servidor.com/clocki/api/export/statistics.php

5. Añadir parámetro de URL:
   • Nombre: token
   • Valor: tu_token_aqui
6. Click Aceptar
7. PowerBI descargará los datos en formato JSON
8. Expandir la columna data para ver todos los registros
9. Configurar actualización automática en opciones

📊 Excel

Importa datos de Clocki directamente en Excel para análisis y reportes.

Método 1: CSV Directo (Recomendado)

1. Datos → Obtener datos → Desde Web
2. Usar formato CSV:

   https://tu-servidor.com/clocki/api/export/punches.php?token=tu_token&format=csv&from=2025-01-01

3. Excel importará directamente como tabla
4. Configurar actualización automática:
   • Click derecho en tabla → Propiedades de consulta
   • Marcar "Actualizar cada X minutos"

Método 2: JSON con Power Query

1. Datos → Obtener datos → De otras fuentes → Desde Web
2. Pegar URL con token (formato JSON)
3. Excel parseará el JSON automáticamente
4. Seleccionar tabla data y expandir columnas

📈 Tableau

Tableau puede conectarse usando:

• Web Data Connector con la URL del endpoint JSON
• Importación CSV directa desde la URL

🔧 Sistemas Personalizados

Cualquier sistema que pueda hacer peticiones HTTP puede integrar con la API de Clocki:

Ejemplo en Python

import requests

url = "https://tu-servidor.com/clocki/api/export/users.php"
params = {
    "token": "tu_token_aqui",
    "format": "json"
}

response = requests.get(url, params=params)
data = response.json()

if data['success']:
    users = data['data']
    print(f"Usuarios encontrados: {data['count']}")
    for user in users:
        print(f"{user['full_name']} - {user['email']}")

Ejemplo en JavaScript/Node.js

const fetch = require('node-fetch');

const url = 'https://tu-servidor.com/clocki/api/export/statistics.php';
const token = 'tu_token_aqui';

fetch(`${url}?token=${token}&month=2025-11`)
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log(`Registros encontrados: ${data.count}`);
      data.data.forEach(stat => {
        console.log(`${stat.user_name}: ${stat.total_hours}h trabajadas`);
      });
    }
  });

Seguridad y Buenas Prácticas

🔐 Gestión de Tokens

Buenas Prácticas

• Tokens únicos: Crea un token diferente para cada integración
• Permisos mínimos: Solo otorga acceso a los endpoints necesarios
• Expiración: Configura fechas de caducidad para tokens temporales
• Rotación: Rota tokens periódicamente (cada 6-12 meses)
• Revocación: Elimina tokens que ya no se usan

🔒 Seguridad en Producción

• HTTPS obligatorio: Usa siempre SSL/TLS en producción
• Tokens hasheados: Los tokens se almacenan hasheados en BD
• Logs de acceso: Cada petición se registra para auditoría
• Validación de permisos: En cada endpoint antes de devolver datos

📊 Monitoreo

Desde el panel de administración puedes:

• Ver logs de acceso: Endpoint, timestamp, IP
• Detectar uso anómalo: Tokens con muchas peticiones
• Identificar tokens inactivos: Para revocarlos
• Auditar integraciones: Qué sistemas acceden a qué datos

⚡ Límites y Consideraciones

🐛 Manejo de Errores

La API devuelve códigos HTTP estándar:

• 200 OK: Petición exitosa
• 400 Bad Request: Parámetros incorrectos
• 401 Unauthorized: Token inválido o expirado
• 403 Forbidden: Token sin permisos para este endpoint
• 500 Internal Server Error: Error del servidor

Ejemplo de Respuesta de Error

{
  "success": false,
  "error": "Token expirado"
}

✅ Checklist de Seguridad

• ☑ Usar HTTPS en producción
• ☑ No compartir tokens en código público
• ☑ Configurar permisos granulares por token
• ☑ Establecer fechas de expiración
• ☑ Revisar logs de acceso regularmente
• ☑ Revocar tokens no utilizados
• ☑ Rotar tokens periódicamente
• ☑ Documentar qué token usa cada sistema

Soporte

Para problemas o preguntas sobre la API:

1. Verifica que el token sea válido y activo
2. Revisa los logs de acceso en el panel de administración
3. Confirma que el token tenga permisos para el endpoint
4. Verifica que la fecha de expiración no haya pasado

Contacto: hola@clocki.es