[02] 2026
Pointage ZKTeco
La présence depuis une vraie pointeuse, en direct dans un dashboard
Le problème
L’équipe pointe sur une ZKTeco K40 Pro, et les pointages restaient dans l’appareil. Personne ne voyait qui était présent, les feuilles du mois se refaisaient à la main et les demandes de congé n’avaient aucun endroit où vivre.
Mon rôle
J’ai tout construit : le récepteur du protocole ADMS, l’API REST, les dashboards admin et employé, le simulateur de pointeuse, Docker Compose en local et un blueprint Render pour la production.
Décisions
Les renvois sont sans risque, par conception
Au premier contact, le serveur répond avec des stamps vides : la pointeuse renvoie tout son historique et tous les utilisateurs. Un index unique (n° de série, PIN, heure) transforme les doublons en non-événements : relancer le simulateur répond toujours OK 7, et le log indique 0 nouvelles, 6 doublons.
Une seule pointeuse a le droit de parler
Sans numéro de série, réponse 400 ; hors ALLOWED_SN, réponse 403. Une erreur de base répond 500 volontairement : la pointeuse réessaie plus tard, aucun pointage n’est perdu. Les gabarits d’empreintes envoyés par l’appareil ne sont jamais stockés.
Des règles pour les vrais pointages
Quand les employés n’utilisent pas les touches de fonction, la K40 envoie le statut 0 partout. Le départ retombe donc sur le dernier pointage après l’arrivée, les pauses se lisent par paires 2 et 3, et toutes les heures sont lues en Africa/Tunis. Un code fixé par l’admin prime sur un congé validé, qui prime sur le calcul automatique.
La pointeuse garde le serveur éveillé
L’offre gratuite de Render s’endort après 15 minutes sans requête. La pointeuse interroge le serveur toutes les 10 secondes : le backend ne dort jamais. Le blueprint indique quand passer à l’offre payante pour un service garanti.
Ce qu’il fait aujourd’hui
- On pointe la pointeuse vers le serveur, et elle apparaît en ligne dans le dashboard en une à deux minutes, employés synchronisés.
- Vues du jour et du mois, export CSV prêt pour Excel, demandes de congé et de télétravail validées par l’admin en temps réel.
- Des tests unitaires couvrent les parseurs du protocole et le calcul journalier ; un simulateur en shell rejoue une journée sans matériel.