Intégrer une pointeuse Hikvision dans une application : architecture, API et événements temps réel

Retour d’expérience — Cet article présente l’intégration réelle d’un terminal Hikvision DS-K1T808MFWX dans un système de gestion de présence, via Hik-Partner Pro. L’intégration couvre l’authentification, la découverte du terminal, la réception des événements de badgeage en temps réel et la gestion des employés à distance.

L’objectif n’est pas simplement de connecter une pointeuse à une application.

Le véritable enjeu est de construire une intégration fiable, idempotente et suffisamment abstraite pour que le reste du système ne dépende pas directement du fonctionnement particulier de Hikvision.

🎯 1. Comprendre l’architecture

La première chose à comprendre est que l’application ne communique pas directement avec la pointeuse.

Dans cette architecture, le terminal Hikvision communique avec Hik-Partner Pro via le protocole ISUP 5.0.

L'application communique ensuite avec Hik-Partner Pro via son API.

Architecture générale

Terminal Hikvision → ISUP 5.0 → Hik-Partner Pro → OpenAPI REST / MQ → Backend → Système de gestion de présence

Le rôle de chaque élément est différent :

• Terminal Hikvision : capture les événements de badgeage et contient les informations des personnes enrôlées.
• Hik-Partner Pro : sert d'intermédiaire cloud entre le terminal et l'application.
• OpenAPI : permet au backend de communiquer avec Hik-Partner Pro.
• MQ : permet de récupérer les événements remontés par les terminaux.
• Canal transparent : permet de transmettre des requêtes ISAPI directement au terminal à travers Hik-Partner Pro.
• Backend : transforme les événements reçus en données exploitables par l'application.

Cette architecture est importante car elle permet au backend de rester indépendant du réseau local où se trouve physiquement la pointeuse.

Une différence importante avec ZKTeco

Dans une intégration ZKTeco via BioTime, on peut récupérer les transactions historiques depuis le serveur intermédiaire.

Avec Hikvision et Hik-Partner Pro, on travaille davantage avec une file d'événements temps réel.

C'est une différence fondamentale dans la conception du système.

🔐 2. Authentification auprès de Hik-Partner Pro

L'authentification utilise une paire :

• appKey
• secretKey

L'endpoint utilisé est :

POST /api/hpcgw/v1/token/get

sur le domaine global :

https://api.hik-partner.com

Le corps de la requête contient :

• appKey
• secretKey

La réponse contient notamment :

• accessToken
• expireTime
• areaDomain

Le point particulièrement important : areaDomain

L'API ne fournit pas seulement un token.

Elle indique également le domaine régional qui devra être utilisé pour les appels suivants.

Par exemple :

https://apiieu.hik-partner.com

Il ne faut donc pas coder le domaine régional en dur.

Le fonctionnement recommandé est :

token/get → récupérer accessToken + areaDomain → utiliser areaDomain pour les autres appels

C'est une petite décision d'architecture qui évite beaucoup de problèmes lorsqu'on travaille avec des comptes rattachés à différentes régions.

🔌 3. Les principaux endpoints

Voici les endpoints utilisés dans cette intégration :

Besoin

Endpoint

Méthode

Authentification

/api/hpcgw/v1/token/get

POST

Lister les devices

/api/hpcgw/v1/device/list

POST

S'abonner aux événements

/api/hpcgw/v1/mq/subscribe

POST

Lire les événements

/api/hpcgw/v1/mq/messages

POST

Confirmer la consommation

/api/hpcgw/v1/mq/offset

POST

Canal transparent

/api/hpcgw/v1/device/transparent/{isapiUri}

POST

Une particularité de cette API est que même certaines opérations qui ressemblent à des lectures utilisent POST avec un corps JSON.

Les réponses utilisent également errorCode.

Une opération réussie correspond à :

errorCode: "0"

Il faut donc vérifier le code métier de la réponse et pas uniquement le statut HTTP.

🧱 4. Construire un client HTTP robuste

Une intégration avec une API externe ne devrait pas disperser les appels Axios dans toute l'application.

Il est préférable de créer un client centralisé responsable de :

• récupérer le token ;
• conserver le token en cache ;
• renouveler le token avant expiration ;
• ajouter automatiquement le header Authorization;
• utiliser le areaDomain fourni par Hikvision ;
• gérer les timeouts ;
• effectuer un retry lorsque le token est expiré.

Le header utilisé pour les appels authentifiés est :

Authorization: Bearer <accessToken>

Gestion de l'expiration

L'erreur :

LAP500004

indique que le token a expiré.

Le client peut alors :

supprimer le token en cache ;

récupérer un nouveau token ;

rejouer une seule fois la requête initiale.

Cette logique évite de dupliquer la gestion de l'authentification dans chaque service.

🔎 5. Découvrir les pointeuses

Une fois authentifié, le backend peut récupérer les terminaux associés au compte.

Endpoint :

POST /api/hpcgw/v1/device/list

Paramètres principaux :

• page
• pageSize

La réponse contient notamment :

• deviceSerial
• deviceName
• deviceType
• deviceCategory
• deviceOnlineStatus

Par exemple, le modèle du terminal utilisé pendant l'intégration était :

DS-K1T808MFWX

Le deviceSerial

Le deviceSerial est particulièrement important.

Il permet d'identifier précisément la pointeuse et devient également une partie de la clé d'idempotence des événements.

Par exemple :

hikvision:GC0292541:52

où :

• GC0292541 correspond au terminal ;
• 52 correspond au numéro de série de l'événement.

Pagination

Contrairement à BioTime, qui peut fournir une URL next, Hik-Partner Pro utilise ici une pagination basée sur :

• page
• totalPage

Le backend doit donc parcourir les pages jusqu'à atteindre totalPage.

📡 6. La file MQ : le cœur de l'intégration

La partie la plus importante de l'intégration Hikvision est probablement la MQ.

Elle permet de récupérer les événements remontés par les terminaux.

Le fonctionnement repose sur trois opérations :

s'abonner ;

récupérer les messages ;

confirmer leur consommation.

S'abonner aux événements

Endpoint :

POST /api/hpcgw/v1/mq/subscribe

Le corps peut notamment contenir :

• subType
• subMode
• deviceSerialList

L'abonnement peut être rejoué : il est donc possible de l'intégrer dans le processus de synchronisation.

Lire les événements

Endpoint :

POST /api/hpcgw/v1/mq/messages

La réponse contient notamment :

• batchId
• list

La propriété list contient les événements reçus.

Cette API fonctionne avec un mécanisme de long-polling : le serveur peut conserver la connexion pendant plusieurs secondes dans l'attente de nouveaux événements.

Il faut donc éviter un timeout trop faible.

Un timeout de l'ordre de 30 secondes ou plus est préférable.

Confirmer la consommation

Une fois le batch traité, le backend confirme sa consommation avec :

POST /api/hpcgw/v1/mq/offset

avec :

• batchId

Le flux devient donc :

Lire → traiter → confirmer → recommencer

Il est important de ne pas confirmer le batch avant d'avoir correctement traité les événements.

⏱️ 7. Une contrainte importante : la durée de conservation des événements

La file MQ n'est pas un historique permanent.

Les événements sont conservés pendant une durée limitée, d'environ deux heures dans l'intégration observée.

Cela implique une conséquence directe :

Une application qui dépend de MQ doit avoir un consommateur actif en permanence.

Dans notre cas, un processus de polling est exécuté régulièrement, environ toutes les deux minutes.

Pourquoi ?

Parce qu'une interruption prolongée pourrait entraîner la perte d'événements.

Pour une architecture plus robuste, il faut également prévoir une stratégie de rattrapage, notamment via les événements AcsEvent accessibles à travers le canal transparent ISAPI lorsque cela est possible sur le terminal.

🧾 8. Comprendre le format des événements

Les événements Hikvision ne sont pas directement des « pointages ».

Un événement peut représenter :

• une tentative de badgeage ;
• un accès refusé ;
• une authentification ;
• un événement de contrôle d'accès ;
• ou une opération qui ne doit pas être matérialisée comme un pointage.

Parmi les informations importantes :

• deviceSerial
• dateTime
• eventType
• AccessControllerEvent
• serialNo
• employeeNoString
• cardNo
• currentVerifyMode
• majorEventType
• subEventType
• attendanceStatus

🧠 9. Tous les événements ne sont pas des pointages

C'est une distinction importante dans une application de gestion de présence.

Par exemple, un événement peut être généré alors que la personne n'a pas été correctement authentifiée.

Un événement avec :

currentVerifyMode: "invalid"

ne doit pas être automatiquement transformé en Punch.

De même, si aucun employé n'est identifié avec employeeNoString, il faut éviter de créer un pointage associé à un employé inconnu.

Le parser doit donc avoir une étape de validation avant la matérialisation.

Exemple de logique

Événement reçu → validation → identification de l'employé → création du pointage

Les événements refusés peuvent cependant rester intéressants pour l'audit ou la sécurité.

Ils ne doivent simplement pas être confondus avec les événements de présence.

🔑 10. L'idempotence avec serialNo

Un système de synchronisation doit pouvoir recevoir deux fois le même événement sans créer deux pointages.

Le serialNo de l'événement constitue une bonne base pour créer une clé unique.

Mais attention : le serialNo n'est pas nécessairement unique à l'échelle de tous les terminaux.

La clé doit donc combiner :

• le fournisseur ;
• le terminal ;
• le numéro de l'événement.

Par exemple :

hikvision:GC0292541:52

Cette valeur peut être utilisée comme naturalKey.

La base de données peut ensuite imposer un index unique sur cette propriété.

Le traitement devient alors idempotent :

Le même événement peut être traité plusieurs fois sans créer plusieurs pointages.

C'est particulièrement important avec une file de messages et des mécanismes de retry.

⚠️ 11. Le cas particulier de attendanceStatus

Un piège intéressant rencontré lors de l'intégration concerne :

attendanceStatus

Lorsque le mode Time & Attendance n'est pas activé sur le terminal, la valeur peut être littéralement :

"undefined"

Ce n'est donc pas la valeur JavaScript undefined.

C'est une chaîne de caractères.

Il faut donc traiter explicitement ce cas.

Lorsque le statut checkIn ou checkOut n'est pas disponible, le système peut conserver l'événement brut et déduire ensuite l'entrée et la sortie chronologiquement, comme dans une intégration ZKTeco.

👤 12. Le canal transparent Hik-Partner Pro

C'est l'une des parties les plus intéressantes de l'intégration.

Hik-Partner Pro propose un canal transparent permettant de transmettre des requêtes ISAPI au terminal.

L'endpoint général est :

POST /api/hpcgw/v1/device/transparent/{isapiUri}

La requête utilise notamment :

X-Devserial: <deviceSerial>

ainsi que :

Authorization: Bearer <accessToken>

Le cloud agit alors comme un relais :

Backend → Hik-Partner Pro → ISAPI → Terminal

Cela permet d'accéder à certaines fonctionnalités natives du terminal sans établir directement une connexion réseau avec celui-ci.

👥 13. Lire les personnes présentes sur le terminal

L'une des opérations utilisées est :

POST

/ISAPI/AccessControl/UserInfo/Search?format=json

avec notamment :

• searchID
• searchResultPosition
• maxResults

Le terminal peut retourner des informations comme :

• employeeNo
• name
• cardNo
• numOfFP
• numOfFace

Cette fonctionnalité permet notamment de comparer les utilisateurs présents sur la pointeuse avec ceux enregistrés dans le système de gestion de présence.

➕ 14. Créer un employé à distance

Il est également possible de transmettre une requête ISAPI permettant de créer un utilisateur sur le terminal.

L'URI utilisée pendant l'intégration était :

/ISAPI/AccessControl/UserInfo/Record?format=json

Les informations importantes peuvent notamment comprendre :

• employeeNo
• name
• userType
• Valid
• doorRight
• RightPlan
• cardNo

Le terminal peut alors créer directement la personne.

Cette possibilité permet au système central de pousser les informations d'un employé vers une pointeuse sans intervention manuelle pour certaines données.

🗑️ 15. Supprimer un utilisateur

La suppression peut être réalisée avec :

/ISAPI/AccessControl/UserInfo/Delete?format=json

en fournissant la liste des numéros d'employés concernés.

Cette fonctionnalité complète le cycle :

Créer → synchroniser → modifier → supprimer

🚧 16. Les limites du canal transparent

Toutes les fonctionnalités d'un système de gestion de personnel ne sont pas nécessairement disponibles de la même manière sur le terminal.

Dans cette intégration :

Les départements

Le concept de département utilisé dans le système métier n'est pas reproduit comme une structure native équivalente sur la pointeuse.

Les départements restent donc gérés dans la base de données de l'application.

Les empreintes

L'enrôlement biométrique se fait principalement directement sur le terminal.

Il ne faut donc pas concevoir le système en supposant que toutes les données biométriques pourront être créées via une API classique.

Les visages

La gestion des visages peut potentiellement passer par les mécanismes FDLib, mais ce point doit être validé selon le modèle du terminal et la configuration utilisée.

Les endpoints non officiellement documentés

Certaines URI ISAPI peuvent fonctionner via le canal transparent sans apparaître dans la liste officielle des URI transparentes.

C'est le cas notamment de :

UserInfo/Record

ou

UserInfo/Delete

Lorsqu'une fonctionnalité repose sur un comportement non documenté, il faut le considérer comme une dépendance technique à surveiller et non comme une garantie universelle.

🔄 17. Synchroniser les pointages avec l'application

Une fois les événements récupérés, le traitement peut suivre plusieurs étapes.

Étape 1 — Récupérer le batch

mq/messages

Étape 2 — Parser chaque événement

Transformer le format Hikvision en un format interne commun.

Étape 3 — Filtrer

Écarter notamment :

• les événements invalides ;
• les événements sans employé ;
• les terminaux inconnus ;
• les événements qui ne correspondent pas à un pointage.

Étape 4 — Résoudre l'employé

Utiliser employeeNoString pour retrouver l'employé dans la base.

Étape 5 — Créer ou mettre à jour le pointage

Utiliser la naturalKey pour garantir l'idempotence.

Étape 6 — Confirmer le batch

Appeler :

mq/offset

Étape 7 — Recalculer les journées concernées

Les journées impactées sont recalculées afin de mettre à jour la présence, les retards, les absences et les autres indicateurs.

Cette séparation entre journal brut et présence calculée reste essentielle.

🧩 18. Le mapping entre Hikvision et les employés

Le numéro d'employé présent sur la pointeuse doit être associé à un employé de l'application.

Une stratégie robuste consiste à utiliser deux niveaux de résolution.

Niveau 1 — Mapping explicite

Conserver dans l'employé une référence propre au fournisseur, par exemple :

hikvisionEmpCode

Niveau 2 — Fallback

Si aucun mapping explicite n'existe, utiliser le matricule de l'employé lorsque celui-ci correspond au employeeNo du terminal.

Cela permet d'avoir une intégration flexible sans dépendre d'un seul système d'identification.

🔁 19. Synchronisation bidirectionnelle

Avec la MQ et le canal transparent, l'intégration devient bidirectionnelle.

Application → Pointeuse

Le système peut :

• créer un employé ;
• transmettre certaines informations ;
• supprimer un employé.

Pointeuse → Application

Le système peut :

• récupérer les personnes présentes sur le terminal ;
• récupérer les événements ;
• identifier les nouveaux utilisateurs ;
• associer les utilisateurs aux employés existants.

Cette architecture permet donc d'éviter que la pointeuse et le système métier deviennent deux bases indépendantes difficiles à maintenir.

🏗️ 20. Pourquoi utiliser un provider pattern ?

Lorsqu'une application doit gérer plusieurs fabricants de pointeuses, il serait problématique de mettre toute la logique ZKTeco et Hikvision directement dans les services métier.

Une meilleure approche consiste à définir une interface commune.

Par exemple, un provider peut exposer conceptuellement :

• testConnection
• listAvailableDevices
• fetchStatus
• syncEvents
• listPersons
• pushPerson
• removePerson

L'application métier utilise alors cette interface sans connaître les détails propres à Hikvision ou ZKTeco.

Exemple d'architecture

Application

↓

Device Service

↓

Provider

↙︎ ↘︎

ZKTeco Hikvision

Chaque fournisseur possède son propre fonctionnement interne.

Cela permet d'ajouter plus facilement un troisième fabricant sans modifier toute l'application.

🧯 21. Les principaux pièges rencontrés

Voici les problèmes qui méritent particulièrement d'être anticipés :

Problème

Conséquence

Solution

Réponse enveloppée dans data

Impossible de trouver le token

Lire data ou la réponse directe

Mauvais domaine API

Appels qui échouent

Utiliser areaDomain

attendanceStatus = "undefined"

Statut de présence incorrect

Tester explicitement la chaîne

employeeNoString absent

Pointage impossible à associer

Filtrer ou traiter comme événement non exploitable

serialNo non unique

Doublons entre terminaux

Inclure deviceSerial dans la clé

MQ temporaire

Événements perdus

Polling continu + stratégie de rattrapage

Long-polling

Timeout prématuré

Timeout suffisamment élevé

Provider mal configuré

Erreur au démarrage

Vérification isConfigured()

Secrets exposés

Risque de compromission

Variables d'environnement + rotation

🔐 22. Sécuriser les informations de connexion

Les informations suivantes ne doivent jamais être écrites directement dans le code :

• App Key ;
• Secret Key ;
• clés de chiffrement ;
• tokens ;
• identifiants sensibles.

Elles doivent être stockées dans les variables d'environnement ou dans un système sécurisé de gestion des secrets.

Exemples de variables :

HIK_APP_KEY

HIK_SECRET_KEY

HIK_TOKEN_DOMAIN

HIKVISION_ENABLED

EMPLOYEE_DATA_ENCRYPTION_KEY

Les clés et secrets utilisés pour l'intégration doivent également pouvoir être renouvelés sans modifier le code source.

🚀 23. Checklist avant la mise en production

Hik-Partner Pro

• Compte Hik-Partner Pro configuré
• App Key et Secret Key disponibles
• Terminal rattaché au compte
• Terminal en ligne
• Mode Time & Attendance configuré si nécessaire
• Personnes correctement enrôlées ou synchronisées

Backend

• Variables d'environnement configurées
• Token mis en cache
• Renouvellement automatique
• Retry sur expiration
• Timeout adapté au long-polling
• Provider Hikvision activable/désactivable

Base de données

• deviceSerial correctement enregistré
• Mapping employé configuré
• naturalKey unique
• Données sensibles protégées

Synchronisation

• mq/subscribe fonctionnel
• Polling continu
• mq/messages traité correctement
• mq/offset appelé après traitement
• Logs de synchronisation disponibles
• Mécanisme de rattrapage prévu

🧪 24. Tester l'intégration de bout en bout

Un test complet peut suivre cet ordre :

1. Authentification

Appeler :

token/get

Vérifier :

• accessToken
• expireTime
• areaDomain

2. Découverte

Appeler :

device/list

Vérifier que le terminal apparaît avec :

deviceOnlineStatus: 1

3. Abonnement

Appeler :

mq/subscribe

avec le deviceSerial du terminal.

4. Création d'un utilisateur

Utiliser :

UserInfo/Record

pour créer un utilisateur de test.

5. Badgeage physique

Effectuer un badgeage sur la pointeuse.

6. Réception

Vérifier que l'événement apparaît dans :

mq/messages

7. Matérialisation

Vérifier la création du Punch avec une clé du type :

hikvision:<deviceSerial>:<serialNo>

8. Calcul

Vérifier que le service de présence recalcule correctement la journée concernée.

Ce type de test permet de valider toute la chaîne plutôt que de tester chaque API isolément.

⚖️ 25. ZKTeco vs Hikvision

L'intégration de ces deux fournisseurs montre bien pourquoi une architecture d'abstraction est utile.

Aspect

ZKTeco / BioTime

Hikvision / Hik-Partner Pro

Intermédiaire

Serveur BioTime

Cloud Hik-Partner Pro

Authentification

JWT

Token applicatif

Pointages

Historique via API

File MQ temps réel

Pagination

URL next

page / totalPage

Employés

API personnel BioTime

ISAPI via canal transparent

Départements

Supportés par BioTime

Gérés côté application

Idempotence

zkteco:<transaction>

hikvision:<serial>:<serialNo>

Conservation des événements

Historique disponible

MQ temporaire

Risque principal

Mapping / pagination

Perte d'événements MQ

Le fonctionnement est donc différent, mais l'application peut exposer une même logique métier grâce au provider pattern.

💡 26. Ce que cette intégration m'a appris

L'intégration d'une pointeuse ne consiste pas simplement à appeler quelques endpoints.

Elle oblige à résoudre plusieurs problèmes d'ingénierie :

• comprendre une architecture distribuée ;
• gérer une authentification externe ;
• gérer l'expiration des tokens ;
• travailler avec un système de messages ;
• gérer le long-polling ;
• rendre la synchronisation idempotente ;
• gérer les événements invalides ;
• faire correspondre des identifiants provenant de plusieurs systèmes ;
• gérer les contraintes de conservation des événements ;
• isoler les spécificités d'un fournisseur ;
• construire une architecture capable d'accueillir plusieurs fabricants.

C'est justement cette partie qui rend l'intégration intéressante d'un point de vue logiciel.

Le terminal n'est qu'un élément du système.

Le vrai travail consiste à construire une couche d'intégration fiable entre un équipement physique, une plateforme cloud et une application métier.

🏁 Conclusion

L'intégration Hikvision avec Hik-Partner Pro repose principalement sur trois mécanismes.

1. areaDomain

Le domaine régional retourné lors de l'authentification doit être utilisé pour les appels suivants.

2. La file MQ

Elle permet de recevoir les événements de manière quasi temps réel, mais sa durée de conservation limitée impose un consommateur actif.

3. Le canal transparent

Il permet de transmettre des requêtes ISAPI au terminal et ouvre notamment la possibilité de gérer les utilisateurs à distance.

À cela s'ajoutent deux principes essentiels :

l'idempotence, pour éviter les doublons, et le provider pattern, pour isoler Hikvision du reste de l'application.

Cette approche permet de construire une intégration qui ne dépend pas directement d'un seul fabricant et qui peut évoluer vers plusieurs types de pointeuses.Retour d'expérience technique — Cette intégration a été réalisée autour d'un terminal Hikvision DS-K1T808MFWX, avec Hik-Partner Pro, Node.js, Express, MongoDB/Mongoose et Axios. Les identifiants, secrets et données sensibles ne sont volontairement pas publiés.