What is ZKTeco PUSH Protocol?

The ZKTeco PUSH Protocol (also called ADMS/iclock protocol) is an HTTP-based communication protocol where ZKTeco biometric devices initiate connections to your server, pushing attendance records, user data, fingerprint templates, face templates, and photos in real time. It works over Ethernet, Wi-Fi, GPRS, 3G and 4G networks.

How does the PUSH Protocol SDK work?

The SDK provides a complete server-side implementation that receives HTTP requests from ZKTeco devices. It handles device initialization (options=all), configuration exchange, heartbeat monitoring, real-time attendance data upload, biometric template sync (fingerprints, faces), user management commands, and photo capture processing.

Is the PUSH Protocol SDK free?

The PUSH Protocol SDK is a professional development kit designed for developers and system integrators. It is not free. Contact StandTech via WhatsApp at +212 635 509 160 for pricing, licensing, and technical support.

Which ZKTeco devices support the PUSH Protocol?

All ZKTeco Green Label Series standalone devices with Attendance PUSH Protocol support are compatible. This includes popular models like xFace600, SpeedFace-V5L, ProFace X, MB460, K40, and many more terminals supporting PUSH protocol v2.0+.

What is the difference between PUSH and PULL protocol in ZKTeco?

PUSH protocol: The device initiates the connection to the server and pushes data automatically (HTTP-based, ADMS). PULL protocol: The server connects to the device using the ZKTeco SDK (zkemkeeper.dll) via TCP to pull data. PUSH is recommended for cloud/web-based systems like ZKBioTime, while PULL is used with desktop software like ZKAccess.

How to integrate ZKTeco devices with my own software?

You can integrate ZKTeco devices using: 1) PUSH Protocol SDK - devices push data to your HTTP server (best for web apps). 2) ZKTeco zkemkeeper SDK - your software pulls data via TCP (for desktop apps). 3) ZKBioTime REST API - connect through ZKBioTime software as middleware. Contact StandTech for the PUSH Protocol SDK package.

Can ZKTeco PUSH protocol work with Node.js or Python?

Yes. The PUSH protocol is HTTP-based, so you can build a receiver server in any language: Node.js, Python, PHP, Java, C#, or Go. The device sends standard HTTP POST requests with attendance records, user data, and biometric templates. You just need an HTTP server listening on the configured port.

How to get real-time attendance data from ZKTeco devices?

Using the PUSH Protocol: Configure the device Cloud Server to point to your server. The device will send heartbeat requests every 30 seconds and push new attendance records immediately when they occur. Your server receives the data via HTTP POST with the transaction details including employee ID, timestamp, and verification mode.

Kit de Developpement Logiciel SDK Payant / Paid SDK

ZKTeco Attendance
PUSH Protocol SDK

Integrez les terminaux biometriques ZKTeco avec votre propre logiciel. Synchronisation automatique des pointages, gestion des utilisateurs, templates biometriques — concu pour les developpeurs.

Integrate ZKTeco biometric devices with your own software. Automatic attendance sync, user management, biometric templates — designed for developers.

Obtenir le SDK Documentation

PUSH Protocol v2.4.1 LIVE
// Device → Your Server GET /iclock/cdata?SN=DEVICE_SN&options=all // Server Response GET OPTION FROM: DEVICE_SN ATTLOGStamp=0 OPERLOGStamp=0 Realtime=1 ServerVer=3.0.1 TransFlag=111111111111 // Real-time attendance upload POST /iclock/cdata?table=ATTLOG 2 2026-02-15 09:01:33 255 15 // → User 2 clocked in via face

SDK FEATURES

Pourquoi le SDK PUSH Protocol ?

Tout ce dont un developpeur a besoin pour integrer les terminaux ZKTeco a son propre systeme.

Synchronisation Automatique

Les terminaux poussent les donnees en temps reel vers votre serveur. Pointages, utilisateurs, photos — tout est synchronise automatiquement.

Templates Biometriques

Recevez les templates d'empreintes digitales, photos faciales (biophoto), et templates de visage encodes en base64 directement depuis les appareils.

Gestion des Utilisateurs

Ajoutez, modifiez et supprimez des utilisateurs a distance via des commandes envoyees depuis votre serveur vers les terminaux.

Photos de Pointage

Capturez automatiquement les photos au moment du pointage (ATTPHOTO). Ideale pour la verification visuelle et l'audit.

Commandes a Distance

Envoyez des commandes aux terminaux via le heartbeat : ajout d'utilisateurs, redemarrage, mise a jour — controle total a distance.

Multi-Connectivite

Fonctionne via Ethernet, Wi-Fi, GPRS, 3G et 4G. Le protocole PUSH est independant du type de connexion reseau.

PROTOCOL FLOW

Comment fonctionne le protocole PUSH ?

Le terminal ZKTeco initie toutes les connexions HTTP vers votre serveur. Voici le flux complet :

1. Initialisation — Device envoie options=all

2. Serveur repond avec la configuration (Stamps, Delay, TransFlag...)

3. Device pousse ses infos (table=options) → Serveur repond OK

4. Heartbeat (/iclock/getrequest) — Boucle continue

5. Upload des donnees (ATTLOG, OPERLOG, ATTPHOTO, BIODATA...)

6. Commandes via heartbeat → Reponse via /iclock/devicecmd

TECHNICAL REFERENCE

Documentation du Protocole PUSH

Reference technique complete du ZKTeco TA PUSH Protocol. Ce guide couvre chaque etape du protocole de communication.

Table des Matieres

1. Initialisation — Echange d'informations
2. Configuration du terminal (table=options)
3. Heartbeat — Detection de presence
4. Backup Heartbeat (Ping)
5. Upload des donnees de pointage (ATTLOG)
6. Types de donnees uploadees (table=xxx)
7. OPERLOG — Donnees detaillees
8. Envoi de commandes (devicecmd)
9. Reference TransFlag — 12 parametres

Initialisation — Echange d'informations

La premiere requete envoyee par le terminal ZKTeco a votre serveur est une requete d'initialisation. Le terminal envoie options=all pour signaler qu'il demande la configuration complete.

Device → Server (GET Request) INIT
GET /iclock/cdata?SN=5881195100001&options=all&language=83&pushver=2.4.1&DeviceType=att&PushOptionsFlag=1

Si options=all, c'est une requete d'initialisation. Votre serveur doit repondre avec :

Server → Device (Response Body) RESPONSE
GET OPTION FROM: 5881195100001 // SN du terminal ATTLOGStamp=0 // timestamp dernier pointage recu OPERLOGStamp=0 // timestamp dernier log recu BIODATAStamp=0 // timestamp dernier biodata recu ATTPHOTOStamp=0 // timestamp derniere photo recue ErrorDelay=10 // delai reconnexion apres erreur (sec) Delay=5 // intervalle heartbeat (1-5 sec recommande) TimeZone=8 // fuseau horaire Realtime=1 // 1 = upload en temps reel ServerVer=3.0.1 // OBLIGATOIRE - version serveur PushProtVer=2.4.1 // version du protocole PUSH TransFlag=111111111111 // 12 flags (voir reference) SupportPing=1 // active le backup heartbeat

Important : Le parametre ServerVer est obligatoire. L'intervalle heartbeat (Delay) est recommande entre 1 et 5 secondes.

PushOptionsFlag : Si le parametre PushOptionsFlag envoye par le terminal est egal a 1, vous devez egalement repondre avec :

PushOptions=RegDeviceType,FingerFunOn,FaceFunOn,FPVersion,FaceVersion,NetworkType,HardwareId3,HardwareId5,HardwareId56,LicenseStatus3,LicenseStatus5,LicenseStatus56

Configuration du terminal (table=options)

Apres l'initialisation, le terminal pousse sa configuration vers votre serveur via une requete POST.

Device → Server (POST Request) CONFIG
POST /iclock/cdata?SN=0316144680030&table=options

Le corps de la requete POST contient les informations de configuration du terminal :

Request Body — Device Configuration Data BODY
~DeviceName=xFace600,MAC=00:17:61:12:0c:31,TransactionCount=2 ~MaxAttLogCount=10,UserCount=1,~MaxUserCount=100 PhotoFunOn=1,FingerFunOn=1,FPVersion=10,~MaxFingerCount=100 FaceFunOn=1,FaceVersion=58,~MaxFaceCount=10000 Language=83,IPAddress=192.168.51.239 ~Platform=ZAM170_TFT,~OEMVendor=ZKTeco Inc. FWVersion=ZAM170-NF-Ver1.1.20,PushVersion=Ver 2.0.32S-20200423 MultiBioDataSupport=0:1:0:0:0:0:0:0:0:1 MultiBioPhotoSupport=0:0:0:0:0:0:0:0:0:1 // ... autres parametres de configuration

Reponse du serveur : Quand table=options, repondez simplement OK (en majuscules). Sauvegardez les donnees de configuration dans votre base de donnees.

Heartbeat — Detection de presence

Le terminal envoie des requetes heartbeat regulierement pour signaler qu'il est en ligne. C'est egalement par cette interface que vous envoyez des commandes au terminal.

Device → Server (GET Request) HEARTBEAT
GET /iclock/getrequest?SN=5881195100001 // Identifier par "getrequest" dans l'URL // Si pas de commande a envoyer : repondre OK // Si commande a envoyer : repondre avec la commande

Logique : Identifiez cette requete via getrequest dans l'URL. S'il n'y a pas de commande en attente, repondez OK en majuscules. Sinon, renvoyez la commande a executer.

Backup Heartbeat (Ping)

Le terminal peut envoyer un heartbeat de secours quand il est occupe a uploader un grand volume de donnees (et ne peut donc pas envoyer le heartbeat principal via getrequest).

Device → Server (GET Request) PING
GET /iclock/ping?SN=5881195100001 // Identifier par "ping" dans l'URL // TOUJOURS repondre OK (pas de commande possible ici)

Attention : Pour la requete ping, vous ne pouvez repondre que OK. Aucune commande ne peut etre envoyee via cette interface.

Upload des donnees de pointage (ATTLOG)

Les donnees de pointage sont poussees via des requetes POST. Identifiez le type de donnees par le parametre table=ATTLOG.

Device → Server (POST Request) ATTLOG
POST /iclock/cdata?SN=5881195100001&table=ATTLOG&Stamp=9999 // Request Body (donnees de pointage) : 2	2020-07-10 16:34:02	255	15	0	0 10

Analyse des champs de pointage :

Champ	Valeur exemple	Description
`PIN`	2	Identifiant de l'utilisateur (User ID)
`DateTime`	2020-07-10 16:34:02	Date et heure du pointage
`Status`	255	Statut de pointage (255 = normal)
`Verify`	15	Methode de verification (15 = reconnaissance faciale)
Les champs suivants sont reserves (work code, etc.). Contactez le support pour plus de details.

Types de donnees uploadees (table=xxx)

Le parametre table dans l'URL identifie le type de donnees poussees par le terminal :

table=	Type de donnees	Description
`ATTLOG`	Pointages	Enregistrements de pointage (entree/sortie)
`ATTPHOTO`	Photos de pointage	Photos capturees au moment du pointage (snap photo)
`OPERLOG`	Donnees multiples	Utilisateurs, logs, empreintes, biophotos, visages, veines
`ERRORLOG`	Logs d'erreur	Journaux d'erreurs du terminal
`BIODATA`	Template tout-en-un	Rarement utilise — peut etre ignore si biophoto est traite

Note : La table OPERLOG est la plus complexe car elle contient plusieurs types de donnees (voir section suivante).

OPERLOG — Donnees detaillees

Quand table=OPERLOG, le corps de la requete POST peut contenir differents types de donnees, identifies par leur prefixe :

USER Informations utilisateur

USER PIN=1	Name=	Pri=0	Passwd=	Card=	Grp=1	TZ=0000000100000000	Verify=-1

Upload des informations utilisateur : ID, nom, privilege, mot de passe, carte, groupe, fuseau, methode de verification.

OPLOG Journal d'operations

OPLOG 30	0	2020-07-10 17:50:33	1	0	0	0

Journal des operations effectuees sur le terminal (ajout utilisateur, suppression, etc.).

FP Template empreinte digitale

FP PIN=1	FID=6	Size=1340	Valid=1	TMP=[base64 fingerprint template data]

Template d'empreinte digitale. Size = longueur du template binaire encode en base64. FID = index du doigt.

BIOPHOTO Photo biometrique (visage)

BIOPHOTO PIN=1	FileName=1.jpg	Type=9	Size=41356	Content=[base64 encoded face image]

Photo de comparaison biometrique (visage). Size = longueur de l'image apres encodage base64. Content = image binaire encodee en base64.

Envoi de commandes & reponse (devicecmd)

Vous pouvez envoyer des commandes aux terminaux via l'interface heartbeat. Le terminal execute la commande et renvoie le resultat via devicecmd.

Exemple : Ajouter un utilisateur a distance

Server → Device (via heartbeat response) COMMAND
// Commande envoyee au terminal via getrequest C:3:DATA UPDATE USERINFO PIN=123	Name=zhangsan	Pri=0	Passwd=	Grp=0

Le terminal execute la commande et renvoie le resultat :

Device → Server (POST Command Reply) REPLY
POST /iclock/devicecmd?SN=5881195100001 // Request Body : ID=3&Return=0&CMD=DATA // Return=0 signifie succes // Autres codes d'erreur : voir documentation PUSH complette

Return=0 signifie que la commande a ete executee avec succes. Pour les autres codes d'erreur, consultez la documentation technique complete fournie avec le SDK.

Reference TransFlag — 12 parametres

Le parametre TransFlag est une combinaison de 12 caracteres (0 ou 1). Chaque position controle l'upload d'un type de donnee specifique :

TransFlag Format 12 FLAGS
TransFlag=111111111111 | | | | | | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 // 1 = upload active | 0 = upload desactive

Pointages (attendance)

Journal d'operations

Photos de pointage

Nouvelles empreintes

Nouveaux utilisateurs

Images empreintes

Modif. infos utilisateur

Modif. empreintes

Nouveaux visages

Photos utilisateur

Work code

Biophoto

KIT DE DEVELOPPEMENT LOGICIEL (SDK) PAYANT

Obtenez le SDK PUSH Protocol ZKTeco

Ce SDK professionnel est concu pour les developpeurs et integrateurs systeme qui souhaitent connecter les terminaux ZKTeco a leur propre logiciel. Synchronisation automatique, plus de metadonnees, documentation complete, support technique.

Documentation complete

Support technique

Exemples de code

Sync automatique

Ce SDK n'est PAS gratuit. C'est un kit de developpement professionnel concu pour les developpeurs avances et les integrateurs. Contactez-nous par WhatsApp pour le prix et les conditions.

Contacter via WhatsApp

+212 635 509 160 — StandTech, Tanger, Maroc

COMPATIBILITY

Terminaux compatibles

Tous les terminaux ZKTeco Green Label Series avec protocole PUSH Attendance sont compatibles.

Face Recognition xFace600, SpeedFace-V5L, ProFace X, MateFace30

Fingerprint K40, K50, MB460, UA760, iClock 990

Multi-Biometric MultiBio 700, SilkBio, iClock 880

Access Control inBio, C2-260, TF1700, F18

Green Label Series : Tous les appareils autonomes ZKTeco avec le protocole Attendance PUSH (version 2.0+) sont compatibles. Verifiez les specifications de votre terminal ou contactez-nous pour confirmation.

ZKTeco AttendancePUSH Protocol SDK