Guide d’intégration avec VAUBAN Visor

Bienvenue dans le guide d’implémentation officiel de l’intégration Hector + Vauban VISOR.

⚙️ Aperçu fonctionnel

L’intégration fonctionne sur deux couches distinctes : la Synchronisation des identités utilisateurs et le Provisionnement des accès.

🧠 Comment ça fonctionne

Synchronisation des identités (VISOR → Hector) : Hector se connecte à votre contrôleur VISOR et récupère la liste des utilisateurs. Chaque utilisateur VISOR est associé à un utilisateur Hector par adresse courriel, créant un lien persistant entre les deux identités afin que l’accès puisse être accordé ultérieurement au nom de la bonne personne.

Accès piloté par le prêt (Hector → VISOR) : Lorsqu’un prêt Hector (une réservation pour un endroit équipé d’un lecteur VISOR) est sur le point de commencer, Hector crée automatiquement un groupe d’accès VISOR temporaire qui autorise l’utilisateur associé sur les lecteurs configurés. Lorsque le prêt se termine, Hector supprime ce groupe — révoquant l’accès physique sans intervention manuelle.

✅ Fonctionnalités clés

L’intégration Hector-VISOR est un pont professionnel entre votre flux de gestion d’actifs/réservations et votre système de contrôle d’accès physique. Si vous souhaitez transformer automatiquement une réservation Hector en clé de porte fonctionnelle, voici les fonctionnalités principales à votre disposition :

• 🔑 Accès déclenché par le prêt : Dès qu’un prêt Hector entre dans la fenêtre d’activation, le badge VISOR de l’emprunteur obtient l’accès à chaque lecteur associé aux endroits prêtés — aucune configuration manuelle du badge n’est nécessaire.
• ⏱️ Activation et révocation avec délai configurable : Définissez précisément quand l’accès s’active et se désactive grâce à deux délais configurables (minutes avant le début du prêt et minutes après sa fin), afin que les utilisateurs ne trouvent jamais une porte verrouillée une minute trop tôt ou déverrouillée une minute trop longtemps.
• 👥 Association automatique des utilisateurs : À chaque cycle de synchronisation, Hector récupère la liste des utilisateurs VISOR et associe chaque titulaire de badge à son profil Hector par adresse courriel — aucun mappage manuel n’est requis.
• 🚪 Association flexible des lecteurs : Choisissez précisément quels endroits Hector doivent être liés à quels lecteurs VISOR. Les endroits non associés sont silencieusement ignorés, ce qui vous permet de déployer l’intégration progressivement.
• 🧹 Listes d’accès auto-nettoyées : Chaque groupe d’accès créé par Hector est nommé avec le préfixe "Hector-" et suivi en interne. Les groupes expirés sont supprimés automatiquement, ce qui maintient votre matrice d’accès VISOR propre et auditable.

🛡️ Configuration : Côté VISOR

Avant de connecter Hector, certains prérequis doivent être en place dans votre environnement Vauban VISOR. Ces étapes sont généralement effectuées par un administrateur VISOR (ou en collaboration avec votre intégrateur VISOR), et elles ne doivent être réalisées qu’une seule fois.

👤 Utiliser ou créer un compte administrateur pour l’API

Hector s’authentifie auprès de l’API VISOR à chaque cycle de synchronisation. Pour que ces appels aboutissent, vous devez lui fournir un compte VISOR disposant du bon ensemble de permissions. Ces permissions se configurent dans VISOR sous l’onglet Droits du profil utilisateur, et l’intégration requiert au minimum les réglages suivants :

• Listing des utilisateurs — au moins Lecture seule. Nécessaire pour récupérer la liste des utilisateurs VISOR et associer les porteurs de badges aux utilisateurs Hector.
• Utilisateurs — Contrôle total. Nécessaire pour permettre à Hector d’assigner les groupes d’accès nouvellement créés au bon emplacement de l’utilisateur.
• Groupes d’accès — Contrôle total. Nécessaire pour créer un groupe d’accès au démarrage d’un prêt et le supprimer à sa clôture.

Tous les autres droits peuvent être laissés à leur valeur par défaut. Accorder davantage que le strict minimum est tout à fait acceptable — par exemple, un profil administrateur existant qui dispose déjà d’un contrôle total partout fonctionnera sans modification — mais accorder moins sur l’un de ces trois droits empêchera l’intégration de fonctionner correctement.

Vous avez deux options :

• Réutiliser un compte administrateur existant. C’est la façon la plus rapide de démarrer, mais sachez que toute rotation de mot de passe sur ce compte cassera l’intégration jusqu’à ce que le nouveau mot de passe soit ressaisi dans Hector.
• Créer un compte administrateur dédié pour Hector. C’est l’approche recommandée. Un compte de service dédié facilite l’audit de l’intégration (chaque appel API apparaît sous cet utilisateur dans vos journaux VISOR), évite les verrouillages accidentels lors du départ d’un administrateur humain, et vous permet de changer le mot de passe indépendamment de vos autres administrateurs.

Quelle que soit l’option choisie, notez bien le nom d’utilisateur et le mot de passe — vous devrez les coller dans Hector lors de l’étape d’Authentification.

🌍 VISOR doit être accessible depuis Hector

Hector est un service hébergé qui appelle l’API VISOR via l’internet public depuis notre infrastructure d’hébergement. Avant que l’intégration puisse fonctionner, l’URL de l’API VISOR doit être accessible depuis l’extérieur de votre réseau d’entreprise. Un contrôleur VISOR qui réside uniquement sur un segment interne — accessible uniquement sur site — ne fonctionnera pas en production. La manière dont vous l’exposez (proxy inverse en DMZ, ouverture de pare-feu, nom d’hôte public dédié, etc.) dépend de votre équipe informatique ; l’intégration requiert uniquement que l’URL réponde aux appels HTTPS depuis notre IP sortante.

🌐 Mettre en liste blanche l’IP Hector dans les connexions externes

Par défaut, l’API VISOR rejette les appels provenant de sources inconnues. Vous devez explicitement autoriser l’adresse IP sortante de Hector avant que l’intégration puisse communiquer avec votre contrôleur VISOR.

1. Contactez l’équipe support Hector pour obtenir l’adresse IP que votre instance Hector utilise pour atteindre les systèmes externes. Cette adresse dépend de votre région d’hébergement, ne supposez donc pas une valeur générique — demandez-la toujours au support.
2. Dans VISOR, ouvrez Outils > Préférences et localisez la section Connexions externes.
3. Ajoutez l’adresse IP fournie par le support Hector à la liste des connexions externes autorisées.
4. Pour cette nouvelle entrée, assurez-vous que le mode d’authentification est défini sur « sécurisée ». Tout autre paramètre (ouvert / non sécurisée) sera refusé à l’exécution par l’intégration et empêchera Hector de s’authentifier.
5. Enregistrez vos modifications dans VISOR.

⚠️ Note : Si vous sautez cette étape (ou oubliez de basculer la nouvelle entrée sur « sécurisé »), le bouton Valider côté Hector échouera avec une erreur d’authentification ou de connexion, même si le nom d’utilisateur et le mot de passe sont corrects.

📋 Autres prérequis

• URL de l’API VISOR : L’URL de base de votre endpoint API VISOR (ex. : https://visor.votreentreprise.com). Hector utilise cette URL de base pour atteindre automatiquement les endpoints d’intégration.
• Courriel sur chaque titulaire de badge : Hector utilise le champ E-mail de chaque utilisateur VISOR pour le relier à l’utilisateur Hector correspondant. Assurez-vous que chaque titulaire de badge devant bénéficier de l’intégration a son courriel professionnel renseigné sur son profil VISOR.
• Inventaire des lecteurs : Les lecteurs qui seront exposés à Hector doivent déjà être créés et nommés de manière significative dans VISOR. Ils apparaîtront dans une liste déroulante lors de la configuration côté Hector.
• Emplacements de groupes libres : VISOR autorise jusqu’à 10 groupes d’accès par utilisateur. Hector consommera un emplacement par prêt concurrent actif. Planifiez vos groupes VISOR de façon à ce que les titulaires de badge conservent suffisamment d’emplacements libres pour le volume de prêts qu’ils sont censés recevoir.

🛠️ Configuration : Hector

Dans Hector, allez dans Réglages > Intégrations > Prêts et ouvrez Vauban VISOR, puis cliquez sur Ajouter. L’intégration Vauban VISOR est disponible sur invitation ; si vous ne la voyez pas dans votre liste, contactez le support Hector pour la faire activer sur votre instance.

L’écran de configuration est divisé en deux onglets : Authentification (affiché en premier) et Inventaire (déverrouillé après validation des identifiants).

🔐 Onglet Authentification

Remplissez les trois champs obligatoires :

• URL : L’URL de base de l’API VISOR collectée précédemment.
• Nom d’utilisateur : L’identifiant du compte de service VISOR.
• Mot de passe : Le mot de passe du compte de service. Hector chiffre cette valeur avant de la stocker ; elle n’est jamais écrite en clair dans la base de données.

Une fois enregistré, cliquez sur Valider. Hector ouvrira une session de test contre l’API VISOR et la fermera immédiatement. Si les identifiants sont corrects, l’intégration est marquée comme Validée et l’onglet Inventaire devient disponible. Si la validation échoue, une bannière d’erreur affichera la raison renvoyée par le serveur VISOR (le plus souvent un HTTP 403 pour des identifiants incorrects, ou une erreur de connexion pour une URL inaccessible).

⚠️ Re-validation : Toute modification des champs d’Authentification après la première validation remet l’intégration dans un état non validé et masque l’onglet Inventaire jusqu’à ce que vous validiez à nouveau. Cela vous protège contre une synchronisation vers une URL mal saisie ou un mot de passe révoqué.

🗂️ Onglet Inventaire

L’onglet Inventaire contient deux sous-sections : Lecteurs et Accès.

🚪 Lecteurs — Association des endroits Hector aux lecteurs VISOR

C’est le cœur de l’intégration : vous décidez quel endroit Hector contrôle quel lecteur VISOR. Chaque ligne de la table d’association contient deux listes déroulantes :

• Endroits Hector : La liste des endroits enregistrés dans votre instance Hector.
• Lecteurs VISOR : Les lecteurs retournés en temps réel par votre API VISOR.

Cliquez sur Ajouter pour créer des lignes d’association supplémentaires, ou sur l’icône de corbeille pour en supprimer une. Un endroit Hector peut être lié à un seul lecteur VISOR. Un endroit non associé ici ne déclenchera jamais d’accès à une porte — le prêt existera toujours dans Hector, mais sera silencieusement ignoré par la synchronisation des accès.

💡 Astuce : Si la liste déroulante des lecteurs VISOR est vide, cela signifie que Hector a reçu une liste vide de l’API VISOR. Vérifiez que votre compte de service a la permission de lire l’inventaire des lecteurs et qu’au moins un lecteur existe côté VISOR.

⏱️ Accès — Délais d’activation

Deux champs numériques obligatoires (exprimés en minutes) contrôlent le timing du provisionnement des accès :

• Délai pour permettre l’accès avant le prêt : Combien de minutes avant la date de début d’un prêt Hector doit commencer à accorder l’accès. Par exemple, un délai de 15 signifie qu’un prêt à 9h00 devient utilisable dès 8h45.
• Délai pour supprimer l’accès après le prêt : Combien de minutes après la date de fin d’un prêt Hector doit maintenir l’accès actif avant de supprimer le groupe VISOR. Un délai de 10 signifie qu’un prêt se terminant à 10h00 conserve son accès badge jusqu’à 10h10.

Les deux délais sont appliqués au moment où la synchronisation des accès s’exécute, ils définissent donc effectivement la fenêtre d’activation autour de chaque prêt. Saisissez 0 si vous souhaitez que l’accès commence et se termine exactement aux limites du prêt.

🔄 Utilisation et synchronisation

Une fois l’intégration validée et les lecteurs associés, Hector exécute deux tâches de fond indépendantes : la Synchronisation des utilisateurs et la Synchronisation des accès.

📥 Synchronisation des utilisateurs (VISOR → Hector)

Ce processus relie chaque titulaire de badge VISOR à un profil utilisateur Hector. C’est un prérequis à la synchronisation des accès — un prêt ne peut pas générer de groupe VISOR si l’emprunteur n’a pas été associé au préalable.

🕒 Fréquence de synchronisation

La synchronisation des utilisateurs s’exécute une fois par jour dans le cadre du cycle d’intégration quotidien de Hector. Elle peut également être lancée manuellement depuis l’écran d’intégration pour un recalcul immédiat (par exemple après l’import d’un lot de nouveaux badges dans VISOR).

🔁 Comportement de la synchronisation

• Pour chaque utilisateur VISOR, Hector recherche un utilisateur Hector dont le courriel correspond à l’E-mail de l’utilisateur VISOR (correspondance exacte, insensible à la casse).
• En cas de correspondance, un lien interne est stocké entre l’utilisateur Hector et l’utilisateur VISOR. Les synchronisations suivantes identifient l’utilisateur via ce lien, de sorte que le courriel peut changer des deux côtés sans casser l’association — seule la toute première correspondance est basée sur le courriel.
• Les utilisateurs qui existaient précédemment dans VISOR mais ont été supprimés sont automatiquement dissociés côté Hector — le profil utilisateur Hector est conservé, seul le lien VISOR est supprimé.

🧱 Mappage des champs utilisateur

Champ utilisateur VISOR	Champ utilisateur Hector	Notes
E-mail	Courriel	Utilisé pour associer un utilisateur VISOR à un utilisateur Hector lors de la synchronisation initiale (correspondance exacte, insensible à la casse).

⚠️ Prérequis d’identité : L’utilisateur Hector doit déjà exister avant l’exécution de la synchronisation. Les utilisateurs VISOR ne sont pas créés automatiquement comme nouveaux utilisateurs Hector — Hector traite VISOR comme un périphérique de contrôle d’accès, non comme un fournisseur d’identité. Utilisez l’interface de création d’utilisateurs Hector (ou la synchronisation Azure/Google si vous en avez une) pour provisionner les utilisateurs au préalable.

📤 Synchronisation des accès (Hector → VISOR)

Ce processus transforme les prêts Hector en groupes d’accès VISOR. Il est structuré en un cycle en deux phases : accorder les nouveaux accès d’abord, puis révoquer les accès expirés.

🕒 Fréquence de synchronisation

La synchronisation des accès s’exécute environ toutes les cinq minutes et réconcilie l’état de tous les prêts ouverts avec leurs équivalents VISOR.

🔁 Phase 1 — Attribution

Hector interroge ensuite chaque prêt satisfaisant toutes les conditions suivantes :

• Le statut est considéré comme Ouvert.
• La date de fin du prêt est dans le futur.
• La date de début du prêt est dans la fenêtre « maintenant + délai avant ». En pratique, cela signifie que le prêt est soit déjà actif, soit sur le point de commencer dans la fenêtre de délai.
• L’accès au prêt n’a pas encore été accordé (aucun enregistrement de suivi n’existe côté Hector).

Pour chaque prêt éligible, Hector effectue les étapes suivantes :

1. Résolution des lecteurs : Chaque ligne de prêt pointant vers un endroit est recherchée dans la table d’association des lecteurs. Les endroits non associés sont ignorés avec un avertissement. Les lecteurs en double sont dédupliqués.
2. Résolution de l’utilisateur : L’utilisateur Hector qui a demandé le prêt est associé à son utilisateur VISOR lié. Si l’utilisateur n’a pas été lié par la synchronisation des utilisateurs, l’attribution est abandonnée.
3. Recherche d’un emplacement libre : VISOR autorise jusqu’à 10 groupes d’accès par utilisateur. Hector choisit le premier emplacement vide. Si les dix sont occupés, l’attribution est abandonnée et sera retentée au prochain cycle.
4. Création du groupe : Hector crée un nouveau groupe d’accès nommé Hector-{CarteEmprunt} dans VISOR, contenant la liste des lecteurs autorisés.
5. Attribution du groupe : Hector inscrit le groupe nouvellement créé dans l’emplacement libre de l’utilisateur VISOR.
6. Suivi de l’attribution : Hector enregistre un lien entre le prêt et le groupe d’accès VISOR, ainsi que l’horodatage d’expiration calculé. Cet enregistrement est ce que la Phase 2 inspectera lors des exécutions futures.

🧱 Mappage des champs d’accès

Champ de prêt Hector	Champ du groupe d’accès VISOR	Notes
ID du prêt	Nom du groupe	Le groupe VISOR est nommé Hector-{ID du prêt}, ce qui rend chaque groupe généré par Hector immédiatement identifiable dans l’interface d’administration VISOR.
Lignes → Endroit	Lecteurs autorisés	Chaque endroit du prêt est résolu vers son lecteur VISOR associé. Les lecteurs non associés ou en double sont silencieusement filtrés.
Demandeur	Emplacement de groupe utilisateur	L’utilisateur VISOR associé reçoit le nouveau groupe sur son premier emplacement libre (jusqu’à 10 par utilisateur).

🔁 Phase 2 — Révocation

• Hector énumère chaque lien de prêt précédemment accordé et vérifie son horodatage d’expiration stocké (qui correspond à la date de fin du prêt plus le délai « après »).
• Tout lien dont l’expiration est passée amène Hector à supprimer le groupe d’accès correspondant dans VISOR, libérant immédiatement l’emplacement de groupe de l’utilisateur. L’enregistrement de suivi dans Hector est nettoyé en même temps.

⛔ Gestion des prêts annulés ou modifiés

• Prêt clôturé / retourné : Une fois la date de fin (plus le délai « après ») dans le passé, le groupe VISOR est supprimé lors de la prochaine synchronisation et l’emplacement de l’utilisateur est libéré.
• Prêt prolongé : Un prêt dont la date de fin est repoussée dans le futur conservera son groupe VISOR existant — Hector utilise l’expiration actualisée lors de la prochaine exécution pour décider quand révoquer.
• Prêt raccourci ou annulé : Le groupe sera supprimé automatiquement dès que la nouvelle expiration sera dans le passé. Si vous avez besoin que la révocation soit immédiate, vous pouvez déclencher la synchronisation des accès manuellement après avoir enregistré la modification.

🚫 Contraintes de l’intégration

• L’e-mail doit être renseigné sur chaque utilisateur VISOR : Les titulaires de badge sans courriel sur leur profil VISOR ne seront jamais associés à un utilisateur Hector et ne recevront donc jamais d’accès via un prêt.
• 10 groupes simultanés par utilisateur : Un utilisateur VISOR peut détenir au maximum 10 groupes d’accès simultanément. Si un emprunteur atteint ce plafond, les nouvelles attributions sont reportées jusqu’à l’expiration d’un groupe existant libérant un emplacement. Cela inclut tout groupe non-Hector assigné manuellement dans VISOR, donc gardez quelques emplacements libres pour l’usage de Hector.
• Couverture des endroits : Seuls les endroits explicitement listés dans la table d’association des lecteurs déclenchent un accès. Si un prêt contient un mélange d’endroits associés et non associés, seuls les endroits associés sont autorisés côté VISOR — le prêt n’est pas rejeté ni fractionné.
• La synchronisation des utilisateurs doit s’exécuter en premier : La synchronisation des accès suppose que l’emprunteur a déjà été lié à un utilisateur VISOR. Un prêt attribué à un utilisateur Hector sans correspondance VISOR sera ignoré avec un avertissement.
• Pas de modifications manuelles dans VISOR : Les groupes nommés Hector-* sont gérés exclusivement par Hector. Les renommer ou les supprimer manuellement dans VISOR cassera le lien et le groupe pourra être recréé au prochain cycle.

Nous espérons que ce guide vous a été utile et vous souhaitons bonne continuation dans votre utilisation de Hector !