zklib-js-zkteko

> 📦 Mejorada librería Node.js para conectarse a dispositivos biométricos ZKTeco (Asistencia y Huellas) vía UDP.

Esta es una versión mejorada del proyecto original zklib-js, con mejoras en compatibilidad, manejo de errores y nuevas funciones para dispositivos de control de asistencia.

---

✨ Características

- Conexión vía UDP a dispositivos ZKTeco (modelos compatibles con ZKLib)
- Obtención de registros de asistencia
- Listado de usuarios
- Manejo de fechas desde/hasta
- Compatibilidad con múltiples modelos
- Mejor manejo de desconexiones y errores

---

📦 Instalación

npm install zklib-js-zkteko

🚀 Uso Básico

const ZKLib = require('zklib-js-zkteko');

const zk = new ZKLib('192.168.1.201', 4370); // IP y puerto del dispositivo

(async () => {
try {
// 1. Conexión al dispositivo
await zk.createSocket();

// 2. Obtener registros de asistencia
const attendance = await zk.getAttendances();
console.log(attendance.data);

// 3. Cerrar conexión
await zk.disconnect();
} catch (e) {
console.error('Error:', e);
}
})();

🛠️ Funciones disponibles

Método Descripción
createSocket() Establece la conexión con el dispositivo
getAttendances() Recupera todos los registros de asistencia
getUsers() Obtiene la lista de usuarios registrados
getInfo() Devuelve información del dispositivo
disconnect() Finaliza la conexión de forma segura

✅ Compatibilidad probada

Tested en los siguientes modelos de ZKTeco:

. K14

. MB160

. iClock680

. VF380

. (y más modelos compatibles con protocolo ZKLib UDP)

⚠️ Errores comunes

Error / Excepción Causa probable Solución sugerida
-Timeout: device not responding -IP/puerto incorrecto o fuera de red -Verifica IP, conexión y que el puerto sea 4370
-UDP socket closed -El dispositivo cerró la conexión -Asegúrate de no exceder solicitudes
Error code 5 Comando inválido o no soportado por el modelo -Cambia de función o actualiza firmware

⏱️ Ejemplo avanzado: Obtener registros desde una fecha

const fromDate = new Date("2024-01-01T00:00:00");

const logs = await zk.getAttendances({
from: fromDate
});

🛠️ API disponible
Método Parámetros Descripción
createSocket() — Conecta al dispositivo
disconnect() — Cierra la conexión de forma segura
getUsers() — Devuelve los usuarios registrados
getAttendances() { from, to } (op.) Registros de asistencia (puedes filtrar)

🧪 Script de prueba

Puedes ejecutar pruebas rápidamente con:

node test

📚 Créditos y origen

Basado en: zklib-js
Autor original: Merouane Zouaid
Mejoras y mantenimiento: Alexander Saenz

📄 Licencia

MIT License