Deep-dive

Protocole Push ZKTeco expliqué : pourquoi c'est essentiel pour la pointeuse cloud

Les appareils ZKTeco supportent deux modes de connexion : pull (SDK) et push (cloud). Découvrez comment le mode push élimine les IP statiques, les serveurs locaux et le polling — et comment recevoir les données de pointage en temps réel via une API REST.

PunchConnect Team·Mar 27, 2026·10 min read

Introduction

Vous avez acheté un appareil ZKTeco. Vous l'avez connecté au réseau. Maintenant vous devez récupérer les données de pointage dans votre application cloud. La question est : l'appareil vous envoie-t-il les données, ou allez-vous les chercher sur l'appareil ?

Cette décision architecturale — push vs. pull — détermine si votre intégration fonctionne de manière fiable à grande échelle ou casse dès que vous ajoutez un deuxième bureau. La plupart des développeurs commencent par l'approche pull (bibliothèques SDK), se heurtent à un mur, puis découvrent que le mode push existe. À ce stade, ils ont déjà perdu des semaines.

Cet article explique ce qu'est le mode push, pourquoi il existe, comment il se compare à l'approche SDK, et comment obtenir des données de pointage en temps réel sans toucher aux protocoles bruts des appareils.

Mode Pull : l'approche SDK (et pourquoi ça casse)

La méthode traditionnelle pour récupérer les données d'un appareil ZKTeco est le mode pull. Votre serveur se connecte à l'appareil sur le réseau local, s'authentifie et demande les enregistrements. Des bibliothèques comme pyzk, node-zklib et zklib fonctionnent toutes de cette façon.

Ça paraît simple au début. Écrire un script, se connecter à l'IP de l'appareil, appeler get_attendance(), c'est fait. Mais la simplicité est trompeuse.

Voici ce qui se passe mal en production :

- Votre application tourne dans le cloud. AWS, OVH, Scaleway, Railway — aucun de ces services ne peut atteindre un appareil derrière un routeur sur un LAN d'entreprise. Il vous faut un serveur local qui tourne 24h/24 comme pont.
- Les appareils changent d'IP. L'informatique réinitialise le routeur, le bail DHCP expire, quelqu'un débranche le switch. Votre chaîne de connexion est maintenant fausse, et vous ne recevez plus de données tant que personne ne s'en aperçoit.
- Le polling n'est pas temps réel. Vous demandez à l'appareil « des nouveaux enregistrements ? » toutes les 30 secondes. C'est de la bande passante gaspillée sur des réponses vides 95% du temps.
- Ça ne passe pas à l'échelle. Gérer des connexions persistantes vers 50+ appareils dans plusieurs bureaux ? C'est un job à plein temps.

Le mode pull fonctionne pour un seul appareil sur un LAN. Dès que vous passez en multi-sites ou en cloud, il vous faut le mode push.

Mode Push : l'appareil se connecte à vous

Le mode push inverse la direction de connexion. L'appareil initie la connexion vers un serveur cloud, pas l'inverse. L'appareil n'a pas besoin d'IP statique. Votre serveur n'a pas besoin d'être sur le même réseau. L'appareil a juste besoin d'un accès internet.

En mode push, c'est l'appareil qui fait le gros du travail. Il se connecte vers le cloud en sortant, envoie les données de pointage en temps réel, reçoit des commandes (synchroniser l'heure, inscrire des employés, redémarrer), et rapporte son statut — tout cela sans que votre serveur n'ait jamais besoin d'initier une connexion.

Pourquoi le mode Push gagne

| Facteur | Pull (SDK) | Push (Cloud) |
|---------|-----------|--------------|
| Réseau requis | Même LAN | Internet uniquement |
| IP de l'appareil | Statique requise | N'importe laquelle (DHCP OK) |
| Latence | 30s–5min de polling | Temps réel (<1s) |
| Apps cloud | ❌ Pont local nécessaire | ✅ Natif |
| Multi-sites | ❌ VPN par site | ✅ Tout converge vers un point |
| Passage à l'échelle | 1 thread par appareil | Événementiel, sans polling |
| Pare-feu | Ports entrants ouverts | Sortant uniquement |

La partie difficile : construire un serveur de protocole push

C'est là que la plupart des équipes coincent. Le mode push est meilleur, mais implémenter le serveur qui reçoit les données push est complexe. L'appareil parle un protocole propriétaire. Il faut :

- Analyser correctement le handshake de connexion de l'appareil
- Gérer l'authentification et l'enregistrement des appareils
- Traiter les enregistrements de pointage dans le format brut
- Mettre en file d'attente et délivrer les commandes aux appareils
- Gérer l'état de connexion de dizaines d'appareils simultanément
- Gérer les reconnexions, les timeouts et la déduplication

Ce n'est pas un projet de week-end. Construire un serveur de protocole push en production a nécessité des mois de travail à notre équipe et des milliers d'heures de tests avec 80+ appareils sur le terrain.

L'approche middleware : protocole en entrée, API REST en sortie

PunchConnect se place entre vos appareils et votre application. Les appareils poussent les données vers le moteur de protocole de PunchConnect. Vous consommez des endpoints REST API et des webhooks propres. Vous ne touchez jamais au protocole brut.

Obtenir les données de pointage en temps réel (exemples de code)

Une fois votre appareil configuré dans le tableau de bord PunchConnect (environ 5 minutes), vous interagissez exclusivement avec l'API REST :

Récupérer les enregistrements de pointage

bash

# Obtenir les événements de pointage d'aujourd'hui
curl -X GET "https://api.punchconnect.com/v1/attendance?from=2026-03-27T00:00:00Z" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json"

Python — Récupérer et traiter le pointage

python

import requests
from datetime import datetime, timezone

API_KEY = "VOTRE_CLE_API"
BASE_URL = "https://api.punchconnect.com/v1"

def get_attendance(from_date: str = None):
    """Récupère les enregistrements de pointage depuis PunchConnect."""
    params = {}
    if from_date:
        params["from"] = from_date

    response = requests.get(
        f"{BASE_URL}/attendance",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
    )
    response.raise_for_status()
    return response.json()["data"]


def sync_vers_votre_systeme(records):
    """Envoie les enregistrements de pointage vers votre système RH."""
    for record in records:
        print(
            f"[{record['punch_time']}] "
            f"{record['employee_id']} — "
            f"{record['punch_type']} "
            f"({record['verify_mode']})"
        )


if __name__ == "__main__":
    today = datetime.now(timezone.utc).strftime("%Y-%m-%dT00:00:00Z")
    records = get_attendance(from_date=today)
    print(f"{len(records)} enregistrements récupérés")
    sync_vers_votre_systeme(records)

JavaScript — Écouter les webhooks en temps réel

javascript

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook/attendance", (req, res) => {
  const event = req.body;

  console.log(`Nouveau pointage : ${event.employee_id} à ${event.punch_time}`);
  console.log(`  Type : ${event.punch_type} | Méthode : ${event.verify_mode}`);
  console.log(`  Appareil : ${event.device_serial}`);

  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log("Listener webhook en écoute sur le port 3000");
});

Quels appareils ZKTeco supportent le mode push ?

La plupart des appareils ZKTeco modernes supportent le mode push. Tout appareil avec le firmware ZMM (la majorité des appareils fabriqués après 2015) a cette capacité. Cela inclut :

- Reconnaissance faciale : SpeedFace V5L, SpeedFace-H5, ProFace X
- Empreinte digitale : UA860, K40, IN01-A, X7
- Multi-modal : SpeedFace V4L, MultiBio 800
- Contrôle d'accès : inBio 160/260, C3-100/200/400

Comment vérifier : Cherchez le réglage « Cloud Server » ou « ADMS Server » dans le menu de configuration réseau de votre appareil. S'il est là, votre appareil supporte le mode push.

Mode push en entreprise française : conformité RGPD

Pour les déploiements en France et dans l'UE, le mode push présente un avantage conformité important : les données biométriques transitent directement de l'appareil vers le cloud, sans serveur intermédiaire local qui ajouterait un point de stockage supplémentaire soumis aux exigences RGPD et CNIL.

PunchConnect chiffre toutes les données en transit (TLS 1.3) et ne stocke que les données nécessaires au fonctionnement du service, conformément au principe de minimisation des données du RGPD.

Questions fréquentes sur le mode push

Faut-il ouvrir des ports pare-feu pour le mode push ?

Non. Le mode push utilise des connexions sortantes depuis l'appareil, comme un navigateur web. Si votre appareil peut accéder à internet, il peut pousser les données. Aucun port entrant, aucune IP statique, aucune redirection de port nécessaire.

Quelle est la latence en temps réel du mode push ?

Moins d'une seconde. Quand un employé pointe sur l'appareil, l'événement atteint PunchConnect et déclenche votre webhook en moins d'une seconde. Comparé au polling SDK (30 secondes à 5 minutes), le mode push est pratiquement instantané.

Que se passe-t-il si internet coupe ?

L'appareil stocke localement. Les appareils ZKTeco gardent les enregistrements en mémoire embarquée (généralement 50 000 à 100 000 enregistrements). Quand la connectivité revient, l'appareil pousse automatiquement tous les enregistrements en tampon. PunchConnect les déduplique pour éviter les doublons.

Peut-on envoyer des commandes aux appareils en mode push ?

Oui. PunchConnect met en file d'attente les commandes (inscrire des employés, synchroniser l'heure, redémarrer, mettre à jour les réglages) et les délivre à l'appareil au prochain cycle push. Vous envoyez les commandes via l'API REST, PunchConnect gère la livraison.

Le mode push est-il compatible avec tous les modèles ZKTeco ?

Le mode push fonctionne avec tout appareil ZKTeco ayant le réglage « Cloud Server » ou « ADMS Server » — soit la grande majorité des appareils fabriqués après 2015. Les anciens appareils (pré-2015) ne supportent que le mode pull, mais ils sont de plus en plus rares en déploiement actif.

Pour commencer

Si vous construisez une intégration biométrique et hésitez entre push et pull :

1. Commencez par le mode push. C'est la bonne architecture pour toute application cloud.
2. Ne construisez pas le serveur de protocole vous-même — sauf si vous avez des mois devant vous et une expérience approfondie des protocoles ZKTeco.
3. Essayez PunchConnect gratuitement pendant 7 jours — enregistrez votre appareil, obtenez votre clé API, et recevez votre premier webhook de pointage en moins de 15 minutes. Sans carte bancaire.

Si vous utilisez déjà une bibliothèque SDK et rencontrez des problèmes de passage à l'échelle, lisez notre comparaison : Pourquoi les bibliothèques open-source ZKTeco ne passent pas à l'échelle. Et si votre principal blocage est l'IP statique, consultez Pointage biométrique sans IP statique.

---

*PunchConnect est un middleware éprouvé en production qui connecte les appareils biométriques ZKTeco à n'importe quel système logiciel. Actuellement utilisé pour le pointage de 24 000+ employés sur 50+ sites.*