Control de Asistencia Biométrico para ERPNext: Guía Completa de Integración

Por Qué el Control de Asistencia Biométrico en ERPNext Falla a Escala

Tienes lectores de huella ZKTeco en tus oficinas y ERPNext administrando RRHH. La herramienta oficial Frappe Biometric Attendance Sync Tool usa pyzk para consultar los dispositivos por tu red local. Una oficina, un dispositivo, una red — funciona.

Agrega una segunda ubicación y todo se desmorona.

pyzk requiere un script Python ejecutándose en la misma red local que cada dispositivo. Si ERPNext corre en Frappe Cloud, no puedes instalar pyzk en sus servidores. Si tienes sucursales, cada una necesita su propia máquina de sincronización. Si un dispositivo cambia de IP por DHCP, la conexión se rompe sin aviso — y lo descubres cuando la nómina se ejecuta con registros faltantes.

PunchConnect elimina toda esta arquitectura. Los dispositivos envían datos de asistencia a una API en la nube. ERPNext los recibe por webhook en tiempo real. Sin scripts locales. Sin dependencia de red. Sin cron jobs consultando datos obsoletos.

Esta guía cubre la integración completa: configuración del dispositivo, receptor webhook, mapeo de empleados, asistencia automática y puesta en producción. Cada bloque de código está listo para copiar y pegar.

Arquitectura: Cómo Funciona la Integración

El enfoque tradicional con pyzk y el enfoque PunchConnect resuelven el mismo problema de forma diferente:

Tradicional (pyzk):

- Requiere red compartida
- Retraso de 10 a 30 minutos
- No escala entre sitios

PunchConnect (webhook en la nube):

- Funciona desde cualquier red
- Tiempo real (1 a 3 segundos)
- Un solo endpoint para todos los sitios

El dispositivo envía los fichajes a la infraestructura cloud de PunchConnect. PunchConnect normaliza los datos entre versiones de firmware y los reenvía como un webhook JSON limpio a tu instancia ERPNext. ERPNext crea un registro Employee Checkin, y el módulo Auto Attendance integrado convierte los checkins en registros de asistencia automáticamente.

Sin servidor intermediario. Sin túneles VPN. Sin infraestructura por sitio.

Dispositivo → [LAN] → script pyzk → [cron] → API ERPNext → Employee Checkin

Requisitos Previos

Antes de comenzar:

- ERPNext v14+ o v15+ con la app HRMS instalada
- Un dispositivo ZKTeco con conectividad cloud (SpeedFace V5L, ProFace X, uFace 800, MB460, iClock 680, serie K, o similar)
- Una cuenta PunchConnect — prueba gratuita de 7 días, sin tarjeta de crédito
- HTTPS en tu instancia ERPNext — los webhooks requieren un certificado SSL válido

Paso 1: Crear tu Cuenta PunchConnect y Registrar un Dispositivo

Regístrate en punchconnect.com/signup. Después de verificar tu email, accedes al panel de control.

Haz clic en Add Device e ingresa el número de serie de tu dispositivo. PunchConnect genera una configuración cloud — aplícala a través del panel de PunchConnect. El proceso completo toma unos 5 minutos por dispositivo.

Una vez configurado, el dispositivo aparece como "Online" en tu panel en menos de 60 segundos.

¿Múltiples sitios? Registra todos los dispositivos bajo una sola cuenta. PunchConnect maneja más de 50 sitios y cientos de dispositivos desde un único panel. Cada dispositivo se identifica por su número de serie, organizable por ubicación.

Paso 2: Construir el Receptor Webhook en ERPNext

PunchConnect envía una solicitud POST a tu instancia ERPNext cada vez que alguien ficha. Necesitas un método API autorizado para recibirla.

Opción A: Instalación Rápida con la App PunchConnect ERPNext

Instala la app oficial PunchConnect para ERPNext para configuración sin código:

Después de la instalación:

1. Ve a PunchConnect Settings → ingresa tu clave API y secreto webhook
2. Haz clic en Test Connection para verificar
3. En el panel de PunchConnect, agrega la URL del webhook:

La app maneja todo: verificación de firma HMAC, detección de duplicados, mapeo de empleados, logs de sincronización y panel de monitoreo.

# Desde tu directorio bench
bench get-app https://github.com/punchconnect/erpnext-punchconnect.git
bench --site tu-sitio.local install-app punchconnect
bench --site tu-sitio.local migrate

Opción B: Receptor Webhook Personalizado (Control Total)

Si prefieres crear tu propio receptor, agrega un método API en tu app Frappe personalizada:

Agrega el secreto en site_config.json:

# tu_app/api.py
import frappe
import hmac
import hashlib
from frappe import _

WEBHOOK_SECRET = frappe.conf.get("punchconnect_webhook_secret", "")

@frappe.whitelist(allow_guest=True)
def punchconnect_webhook():
    """Recibe eventos de asistencia desde PunchConnect."""

    # 1. Verificar firma HMAC
    payload = frappe.request.data
    signature = frappe.request.headers.get("X-PunchConnect-Signature", "")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        frappe.throw(_("Firma webhook inválida"), frappe.AuthenticationError)

    # 2. Parsear el evento
    data = frappe.parse_json(payload)
    event_type = data.get("event")

    if event_type != "attendance":
        return {"status": "ok", "message": f"Evento {event_type} registrado"}

    # 3. Buscar el empleado por ID de usuario del dispositivo
    device_user_id = str(data.get("user_id"))
    employee = frappe.db.get_value(
        "Employee",
        {"attendance_device_id": device_user_id, "status": "Active"},
        ["name", "employee_name", "company"],
        as_dict=True
    )

    if not employee:
        frappe.log_error(
            f"Empleado no encontrado para ID de dispositivo: {device_user_id}",
            "PunchConnect Webhook"
        )
        return {"status": "error", "message": "Empleado no encontrado"}

    # 4. Verificar duplicados
    timestamp = data.get("timestamp")
    existing = frappe.db.exists("Employee Checkin", {
        "employee": employee.name,
        "time": timestamp
    })

    if existing:
        return {"status": "ok", "message": "Duplicado, omitido"}

    # 5. Crear Employee Checkin
    checkin = frappe.get_doc({
        "doctype": "Employee Checkin",
        "employee": employee.name,
        "employee_name": employee.employee_name,
        "time": timestamp,
        "device_id": data.get("device_serial"),
        "log_type": map_punch_direction(data.get("punch_direction"))
    })
    checkin.insert(ignore_permissions=True)
    frappe.db.commit()

    return {
        "status": "ok",
        "checkin": checkin.name,
        "employee": employee.employee_name
    }


def map_punch_direction(direction):
    """Convertir dirección PunchConnect a tipo de log ERPNext."""
    mapping = {
        "IN": "IN",
        "OUT": "OUT",
        "0": "IN",
        "1": "OUT",
    }
    return mapping.get(str(direction).upper(), "")

Paso 3: Mapear Empleados a IDs de Dispositivo

Cada empleado que use un dispositivo biométrico necesita su attendance_device_id configurado. Este campo vincula el ID de usuario del dispositivo con el registro Employee en ERPNext.

Mapeo Manual

1. Abre el doctype Employee
2. Ve a Attendance and Leave Details
3. Configura Attendance Device ID con el ID de usuario en el dispositivo

Mapeo Masivo vía Importación de Datos

Para organizaciones con cientos de empleados:

Sube vía Configuración → Importación de datos → Employee (actualizar registros existentes).

name,attendance_device_id
HR-EMP-00001,101
HR-EMP-00002,102
HR-EMP-00003,103

Mapeo por API

Automatiza el mapeo con un script que obtiene usuarios desde PunchConnect:

import requests
import frappe

API_KEY = "tu_clave_api_punchconnect"

def sync_employee_ids():
    """Obtiene usuarios del dispositivo desde PunchConnect y los mapea a empleados ERPNext."""
    response = requests.get(
        "https://api.punchconnect.com/v1/users",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    device_users = response.json()["data"]

    for user in device_users:
        employee = frappe.db.get_value(
            "Employee",
            {"employee_name": user["name"], "status": "Active"},
            "name"
        )
        if employee:
            frappe.db.set_value(
                "Employee", employee,
                "attendance_device_id", str(user["user_id"])
            )

    frappe.db.commit()
    print(f"{len(device_users)} usuarios mapeados a empleados")

Paso 4: Configurar la Asistencia Automática

ERPNext v14+ incluye Auto Attendance — convierte automáticamente los registros Employee Checkin en registros de Asistencia.

Activar Auto Attendance

1. Ve a HR Settings → activa Auto Attendance
2. Navega a Shift Type → crea o edita un tipo de turno
3. Configura los horarios:

4. Asigna turnos a empleados: ve a Shift Assignment → crea las asignaciones

Nombre del turno: Turno Mañana
Hora de inicio: 08:00
Hora de fin: 17:00
Enable Auto Attendance: ✓
Determine Check-in and Check-out: Alternating
Working Hours Threshold for Half Day: 4
Working Hours Threshold for Absent: 2

El Pipeline Completo en Acción

# 08:02 → El dispositivo captura la huella (User ID: 101)
# 08:02 → PunchConnect recibe el fichaje
# 08:03 → El webhook dispara hacia ERPNext (1-3 segundos)
# 08:03 → Employee Checkin creado (HR-EMP-00001, IN, 08:02)
# ...
# 17:05 → El mismo empleado ficha a la salida
# 17:05 → Employee Checkin creado (HR-EMP-00001, OUT, 17:05)
# ...
# Auto Attendance se ejecuta → Registro de asistencia: Presente, 9h 3min trabajadas

Paso 5: Monitorear y Solucionar Problemas

Problemas Comunes y Soluciones

¿Employee Checkin no se crea?
- Verifica que el attendance_device_id del empleado coincida con el ID del dispositivo
- Revisa los PunchConnect Sync Logs para el mensaje de error
- Activa "Log Raw Payloads" en la configuración de PunchConnect

¿El webhook devuelve 401 o 403?
- Confirma que el secreto webhook es idéntico en PunchConnect y ERPNext
- Verifica que el método API tiene allow_guest=True
- Comprueba que tu certificado SSL es válido

¿Auto Attendance no crea registros?
- Confirma que Auto Attendance está activado en HR Settings
- Verifica que los empleados tienen Shift Assignments para el rango de fechas correcto
- Revisa el Scheduled Job Type para process_auto_attendance

Modelos de Despliegue

Frappe Cloud

No puedes instalar pyzk en los servidores de Frappe Cloud. Los webhooks de PunchConnect son la única vía viable para integración biométrica.

Auto-alojado / Docker

Podrías usar pyzk, pero PunchConnect es más rápido de implementar y más confiable. Sin cron jobs, sin rastreo de IPs, sin problemas de compatibilidad de firmware.

Organizaciones Multi-Sitio

Aquí es donde PunchConnect aporta más valor. ¿100 dispositivos en 20 oficinas? Una sola cuenta PunchConnect, un solo endpoint webhook, una sola instancia ERPNext. Sin infraestructura por sitio.

Actualmente en producción con 24,000+ empleados activos en más de 50 sitios. Lee el caso de estudio AgriWise.

Seguridad

Dispositivo → PunchConnect: conexión cifrada con TLS. Los dispositivos se autentican con su número de serie registrado.

PunchConnect → ERPNext: HTTPS con verificación de firma HMAC-SHA256. Cada webhook incluye un encabezado X-PunchConnect-Signature.

Datos en reposo: PunchConnect procesa los eventos en tiempo real y los reenvía. No almacena plantillas biométricas (huellas, datos faciales). Solo metadatos — ID de usuario, marca de tiempo, número de serie — transitan por la API.

Para cumplimiento normativo en Latinoamérica, PunchConnect minimiza los datos personales que transitan por la nube, alineándose con regulaciones como la Ley Federal de Protección de Datos en México y la normativa de protección de datos de cada país.

Precios

$200 USD por dispositivo — licencia única. Sin cuotas mensuales. Sin cargos por empleado.

Compara eso con el costo oculto de la infraestructura pyzk: un servidor de sincronización por sitio, configuración VPN, tiempo de desarrollador para depurar firmware, y mantenimiento continuo.

Inicia tu prueba gratuita de 7 días — sin tarjeta de crédito.

Preguntas Frecuentes

¿El control de asistencia biométrico para ERPNext funciona con Frappe Cloud?
Sí. PunchConnect envía datos por webhook a un endpoint API Frappe estándar. No se necesita instalar software en los servidores de Frappe Cloud.

¿Qué dispositivos ZKTeco son compatibles?
Cualquier modelo con conectividad cloud: SpeedFace V5L, ProFace X, uFace 800, MB460, iClock 680, serie K, y más. Contáctanos para verificar tu modelo.

¿Qué tan rápido llegan los datos de asistencia a ERPNext?
1 a 3 segundos por webhook. Compara eso con 10 a 30 minutos del polling con cron de pyzk.

¿Puedo usar PunchConnect junto con la herramienta de sincronización Frappe existente?
Sí. Ambos crean documentos Employee Checkin. Ejecuta ambos en paralelo durante la migración, luego desactiva el script cron.

¿Qué pasa si ERPNext está temporalmente caído?
PunchConnect reintenta las entregas webhook con backoff exponencial. No se pierden datos de asistencia.

¿Necesito una IP fija para mi servidor ERPNext?
No. Necesitas un nombre de dominio con un certificado SSL válido. PunchConnect envía webhooks a tu URL — el DNS se encarga del resto.

---

¿Listo para conectar tus dispositivos biométricos a ERPNext? Inicia tu prueba gratuita de 7 días — registra tu primer dispositivo, configura el webhook, y ve Employee Checkins en tiempo real en ERPNext en 30 minutos.

¿Preguntas? Contáctanos — tenemos experiencia con todos los modelos de despliegue ERPNext y todas las variantes de firmware ZKTeco.