Pointage Biométrique pour ERPNext : Guide Complet d'Intégration

Pourquoi le Pointage Biométrique dans ERPNext Bloque à Grande Échelle

Vous avez des lecteurs d'empreintes ZKTeco dans vos bureaux et ERPNext gère les RH. L'outil officiel Frappe Biometric Attendance Sync Tool utilise pyzk pour interroger les terminaux sur votre réseau local. Un bureau, un terminal, un réseau — ça fonctionne.

Ajoutez un deuxième site et tout se complique.

pyzk nécessite un script Python sur le même réseau local que chaque terminal. Si ERPNext tourne sur Frappe Cloud, impossible d'installer pyzk sur leurs serveurs. Si vous avez des agences, chacune a besoin de sa propre machine de synchronisation. Si un terminal change d'IP via DHCP, la connexion se coupe en silence — et vous le découvrez quand la paie tourne avec des pointages manquants.

PunchConnect élimine toute cette infrastructure. Les terminaux envoient les données de pointage vers une API cloud. ERPNext les reçoit par webhook en temps réel. Pas de scripts locaux. Pas de dépendance réseau. Pas de cron qui interroge des données périmées.

Ce guide couvre l'intégration complète : configuration du terminal, récepteur webhook, mapping des employés, pointage automatique et mise en production. Chaque bloc de code est prêt à copier-coller.

Architecture : Comment l'Intégration Fonctionne

L'approche pyzk classique et l'approche PunchConnect résolvent le même problème différemment :

Classique (pyzk) :

- Réseau partagé obligatoire
- Délai de 10 à 30 minutes
- Ne passe pas à l'échelle multi-sites

PunchConnect (webhook cloud) :

- Fonctionne depuis n'importe quel réseau
- Temps réel (1 à 3 secondes)
- Un seul endpoint pour tous les sites

Le terminal envoie les pointages à l'infrastructure cloud de PunchConnect. PunchConnect normalise les données entre les versions de firmware et les transmet sous forme de webhook JSON propre à votre instance ERPNext. ERPNext crée un enregistrement Employee Checkin, et le module Auto Attendance intégré convertit automatiquement les checkins en fiches de présence.

Pas de serveur intermédiaire. Pas de tunnel VPN. Pas d'infrastructure par site.

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

Prérequis

Avant de commencer :

- ERPNext v14+ ou v15+ avec l'app HRMS installée
- Un terminal ZKTeco avec connectivité cloud (SpeedFace V5L, ProFace X, uFace 800, MB460, iClock 680, série K, ou similaire)
- Un compte PunchConnect — essai gratuit de 7 jours, sans carte bancaire
- HTTPS sur votre instance ERPNext — les webhooks nécessitent un certificat SSL valide

Étape 1 : Créer un Compte PunchConnect et Enregistrer un Terminal

Inscrivez-vous sur punchconnect.com/signup. Après vérification de l'email, vous accédez au tableau de bord.

Cliquez sur Add Device et saisissez le numéro de série de votre terminal. PunchConnect génère une configuration cloud — appliquez-la via le tableau de bord PunchConnect. Le processus entier prend environ 5 minutes par terminal.

Une fois configuré, le terminal apparaît comme « Online » dans votre tableau de bord en moins de 60 secondes.

Plusieurs sites ? Enregistrez tous les terminaux sous un seul compte. PunchConnect gère plus de 50 sites et des centaines de terminaux depuis un tableau de bord unique. Chaque terminal est identifié par son numéro de série, organisable par localisation.

Étape 2 : Créer le Récepteur Webhook dans ERPNext

PunchConnect envoie une requête POST à votre instance ERPNext chaque fois qu'un employé pointe. Vous avez besoin d'une méthode API autorisée pour la recevoir.

Option A : Installation Rapide avec l'App PunchConnect ERPNext

Installez l'app officielle PunchConnect pour ERPNext pour une configuration sans code :

Après installation :

1. Allez dans PunchConnect Settings → entrez votre clé API et secret webhook
2. Cliquez sur Test Connection pour vérifier
3. Dans le tableau de bord PunchConnect, ajoutez l'URL du webhook :

L'app gère tout : vérification de signature HMAC, détection des doublons, mapping des employés, journaux de synchronisation et tableau de bord de monitoring.

# Depuis votre répertoire bench
bench get-app https://github.com/punchconnect/erpnext-punchconnect.git
bench --site votre-site.local install-app punchconnect
bench --site votre-site.local migrate

Option B : Récepteur Webhook Personnalisé (Contrôle Total)

Si vous préférez créer votre propre récepteur, ajoutez une méthode API dans votre app Frappe personnalisée :

Ajoutez le secret dans le site_config.json :

# votre_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():
    """Reçoit les événements de pointage depuis PunchConnect."""

    # 1. Vérifier la signature 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(_("Signature webhook invalide"), frappe.AuthenticationError)

    # 2. Parser l'événement
    data = frappe.parse_json(payload)
    event_type = data.get("event")

    if event_type != "attendance":
        return {"status": "ok", "message": f"Événement {event_type} acquitté"}

    # 3. Trouver l'employé par ID utilisateur du terminal
    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"Aucun employé trouvé pour l'ID terminal : {device_user_id}",
            "PunchConnect Webhook"
        )
        return {"status": "error", "message": "Employé non trouvé"}

    # 4. Vérifier les doublons
    timestamp = data.get("timestamp")
    existing = frappe.db.exists("Employee Checkin", {
        "employee": employee.name,
        "time": timestamp
    })

    if existing:
        return {"status": "ok", "message": "Doublon, ignoré"}

    # 5. Créer l'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 la direction PunchConnect en type de log ERPNext."""
    mapping = {
        "IN": "IN",
        "OUT": "OUT",
        "0": "IN",
        "1": "OUT",
    }
    return mapping.get(str(direction).upper(), "")

Étape 3 : Mapper les Employés aux ID Terminaux

Chaque employé utilisant un terminal biométrique doit avoir son attendance_device_id configuré. Ce champ lie l'ID utilisateur du terminal au dossier Employee dans ERPNext.

Mapping Manuel

1. Ouvrez le doctype Employee
2. Allez dans Attendance and Leave Details
3. Renseignez Attendance Device ID avec l'ID utilisateur sur le terminal

Mapping en Masse via Import de Données

Pour les organisations avec des centaines d'employés, utilisez l'import de données ERPNext :

Uploadez via Paramètres → Import de données → Employee (mise à jour des enregistrements existants).

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

Mapping par API

Automatisez le mapping avec un script qui récupère les utilisateurs depuis PunchConnect :

import requests
import frappe

API_KEY = "votre_cle_api_punchconnect"

def sync_employee_ids():
    """Récupère les utilisateurs depuis PunchConnect et les mappe aux employés 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)} utilisateurs mappés aux employés")

Étape 4 : Configurer le Pointage Automatique

ERPNext v14+ inclut Auto Attendance — il convertit automatiquement les enregistrements Employee Checkin en fiches de présence.

Activer Auto Attendance

1. Allez dans HR Settings → activez Auto Attendance
2. Naviguez vers Shift Type → créez ou modifiez un type de quart
3. Configurez les horaires :

4. Assignez les quarts aux employés : allez dans Shift Assignment → créez les assignations

Nom du quart : Quart Matin
Heure de début : 08:00
Heure 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

Le Pipeline Complet en Action

# 08:02 → Le terminal capture l'empreinte (User ID: 101)
# 08:02 → PunchConnect reçoit le pointage
# 08:03 → Le webhook part vers ERPNext (1-3 secondes)
# 08:03 → Employee Checkin créé (HR-EMP-00001, IN, 08:02)
# ...
# 17:05 → Le même employé pointe à la sortie
# 17:05 → Employee Checkin créé (HR-EMP-00001, OUT, 17:05)
# ...
# Auto Attendance s'exécute → Fiche de présence : Présent, 9h03 travaillées

Étape 5 : Surveiller et Dépanner

Problèmes Courants et Solutions

L'Employee Checkin n'est pas créé ?
- Vérifiez que l'attendance_device_id de l'employé correspond à l'ID utilisateur du terminal
- Consultez les PunchConnect Sync Logs pour le message d'erreur
- Activez « Log Raw Payloads » dans les paramètres PunchConnect

Le webhook retourne 401 ou 403 ?
- Confirmez que le secret webhook est identique dans PunchConnect et ERPNext
- Vérifiez que la méthode API a allow_guest=True
- Vérifiez la validité de votre certificat SSL

Auto Attendance ne crée pas de fiches de présence ?
- Confirmez qu'Auto Attendance est activé dans HR Settings
- Vérifiez que les employés ont des Shift Assignments pour la bonne période
- Contrôlez le Scheduled Job Type pour process_auto_attendance

Modèles de Déploiement

Frappe Cloud

Impossible d'installer pyzk sur les serveurs Frappe Cloud. Les webhooks PunchConnect sont la seule voie viable pour l'intégration biométrique. Le récepteur webhook fonctionne comme un endpoint API Frappe standard.

Auto-hébergé / Docker

Vous pourriez utiliser pyzk, mais PunchConnect est plus rapide à déployer et plus fiable. Pas de cron à maintenir, pas de suivi d'IP, pas de problèmes de compatibilité firmware.

Organisations Multi-Sites

C'est là que PunchConnect apporte le plus de valeur. 100 terminaux répartis sur 20 bureaux ? Un seul compte PunchConnect, un seul endpoint webhook, une seule instance ERPNext. Pas d'infrastructure par site.

Actuellement en production avec 24 000+ employés actifs sur plus de 50 sites. Lire l'étude de cas AgriWise.

Sécurité

Terminal → PunchConnect : connexion chiffrée TLS. Les terminaux s'authentifient avec leur numéro de série enregistré.

PunchConnect → ERPNext : HTTPS avec vérification de signature HMAC-SHA256. Chaque webhook inclut un en-tête X-PunchConnect-Signature.

Données au repos : PunchConnect traite les événements en temps réel et les transmet. Il ne stocke pas les modèles biométriques (empreintes, données faciales). Seules les métadonnées — ID utilisateur, horodatage, numéro de série — transitent par l'API.

Pour approfondir la sécurisation des flux biométriques, lisez notre guide sur la sécurisation des données biométriques en transit. La conformité au RGPD est un enjeu majeur pour les entreprises européennes — PunchConnect minimise les données personnelles qui transitent par le cloud.

Tarification

200 $ par terminal — licence unique. Pas de frais mensuels. Pas de facturation par employé.

Comparez cela au coût caché de l'infrastructure pyzk : un serveur de synchronisation par site, la configuration VPN, le temps développeur pour le débogage firmware, et la maintenance continue.

Démarrez votre essai gratuit de 7 jours — sans carte bancaire.

Questions Fréquentes

Le pointage biométrique pour ERPNext fonctionne-t-il avec Frappe Cloud ?
Oui. PunchConnect envoie les données par webhook vers un endpoint API Frappe standard. Aucune installation sur les serveurs Frappe Cloud n'est nécessaire.

Quels terminaux ZKTeco sont compatibles ?
Tout modèle avec connectivité cloud : SpeedFace V5L, ProFace X, uFace 800, MB460, iClock 680, série K, et d'autres. Contactez-nous pour vérifier votre modèle.

Quelle est la vitesse de transmission des données vers ERPNext ?
1 à 3 secondes par webhook. Contre 10 à 30 minutes avec le polling cron de pyzk.

Puis-je utiliser PunchConnect en parallèle avec l'outil de synchronisation Frappe ?
Oui. Les deux créent des documents Employee Checkin. Faites tourner les deux pendant la migration, puis désactivez le script cron.

Que se passe-t-il si ERPNext est temporairement indisponible ?
PunchConnect retente les livraisons webhook avec un backoff exponentiel. Aucune donnée de pointage n'est perdue.

Ai-je besoin d'une IP fixe pour mon serveur ERPNext ?
Non. Vous avez besoin d'un nom de domaine avec un certificat SSL valide. PunchConnect envoie les webhooks vers votre URL — le DNS gère le reste.

---

Prêt à connecter vos terminaux biométriques à ERPNext ? Démarrez votre essai gratuit de 7 jours — enregistrez votre premier terminal, configurez le webhook, et voyez les Employee Checkins en temps réel dans ERPNext en 30 minutes.

Questions ? Contactez-nous — nous avons intégré tous les modèles de déploiement ERPNext et toutes les variantes de firmware ZKTeco.