API et intégrations avec des logiciels tiers

Le schéma technique est simple et robuste : vous pouvez connecter vos logiciels à la couche API de votre installation et la piloter en toute autonomie.

La structure API permet d’effectuer des opérations qui simulent presque la totalité des fonctions du panneau de gestion fourni avec le KIT. Tous les appels doivent être activés et provenir d’une IP autorisée.

Vous trouverez ci-dessous le guide complet de tous les appels disponibles, organisés par domaine fonctionnel. La même documentation est également consultable en format interactif sur Postman : cliquez ici !.

Remarque : une version renforcée du service API est également disponible (API PRO), qui permet d’obtenir les journaux des appels API et d’effectuer la commande d’ouverture à distance — voir la section Api Pro ou contactez-nous pour en savoir plus.

Pour des exemples pratiques d’intégration avec des logiciels de gestion, PMS, plateformes de réservation et de paiement, consultez Intégrations les plus courantes : comment faire.

Authentification

Tous les appels (à l’exception du test de statut) nécessitent un jeton Bearer, obtenu via l’appel authorize et transmis comme en-tête dans les requêtes suivantes.

• Le jeton est valide 1 heure : il doit être renouvelé périodiquement en répétant l’appel authorize.
• Il n’y a aucune limite au nombre d’appels que l’on peut effectuer.
• Erreurs possibles sur l’appel authorize : IP non autorisée ou secret_key incorrecte (invalid_access), identifiants incorrects (invalid_credentials), erreur générique (could not create token).
• Erreurs possibles sur les autres appels : jeton expiré, invalide ou absent (invalid_token). Les erreurs spécifiques éventuelles sont indiquées dans le champ messages de la réponse JSON.

POST /api/v2/authorize — Obtenir le jeton

Renvoie le jeton Bearer à utiliser pour tous les appels suivants.

• Paramètres obligatoires : email (email de l’opérateur), password (mot de passe de l’opérateur), secret_key (associée à l’IP autorisée, se trouve dans le panneau, section API / Setup)
• Réponse 200 : token
• Réponse 401 : invalid_credentials (email ou mot de passe incorrects), invalid_credentials2 (IP non autorisée ou secret_key incorrecte), invalid_access1 (secret_key manquante)

GET /api/v2/ — Test de statut

Vérifie que le panneau est actif et fonctionnel (affiche Test). Ne nécessite ni authentification ni paramètres.

Utilisateurs

PUT /api/v2/adduser — Créer un nouvel utilisateur

Crée un nouvel utilisateur sur le panneau.

• Paramètres obligatoires : name (prénom), surname (nom)
• Paramètres optionnels : email, phone, prefix (préfixe national urlencodé, ex. +39 → %2b39), tags (tableau ; chaque virgule est remplacée par un underscore), status (1 = activé, 0 = désactivé), fields (tableau de champs personnalisés supplémentaires au format fields[id_champ]=valeur)

PUT /api/v2/updateuser — Modifier un utilisateur

Met à jour les données d’un utilisateur existant.

• Paramètres obligatoires : user_id, name, surname
• Paramètres optionnels : email, phone, prefix, tags, status (1 = activé, 0 = désactivé), fields (tableau de champs supplémentaires, même format que AddUser)

DELETE /api/v2/deleteuser — Supprimer un utilisateur

Supprime un utilisateur du panneau.

• Paramètres obligatoires : user_id
• Réponse 200 : utilisateur supprimé avec succès
• Réponse 400 : utilisateur non trouvé

GET /api/v2/getusers — Liste des utilisateurs

Renvoie les données de tous les utilisateurs présents sur le panneau, ou d’un utilisateur spécifique si le paramètre optionnel est transmis.

• Paramètres optionnels : user_id, tags (filtre les utilisateurs par tag), getGrantInfo (si 1, inclut également les détails des accès associés)
• Réponse 404 : aucun utilisateur trouvé

GET /api/v2/users/getStatus — Statut utilisateur

Renvoie si un utilisateur est activé ou désactivé.

• Paramètres : user_id

POST /api/v2/users/changeStatus — Changer le statut utilisateur (pas encore disponible)

Si status = 1, l’utilisateur est autorisé à accéder, si status = 0 il est désactivé.

• Paramètres : user_id, status (1 = activé, 0 = désactivé)

Groupes

GET /api/v2/getGroup — Liste des groupes

Renvoie les données de tous les groupes présents sur le panneau, ou d’un ou plusieurs groupes spécifiques si le paramètre optionnel est transmis.

• Paramètres optionnels : group_id (peut être un tableau)
• Réponse 404 : aucun groupe trouvé

POST /api/v2/grantAccessGroup — Autoriser l’accès à un groupe

Autorise l’accès d’un ou plusieurs utilisateurs à un ou plusieurs groupes indiqués, en créant l’association utilisateur-groupe.

• Paramètres obligatoires : user_id (peut être un tableau), group_id (peut être un tableau)
• Réponse 200 : associations créées avec succès
• Réponse 400 : utilisateur non trouvé, groupe non trouvé, association déjà existante

POST /api/v2/dropAccessGroup — Révoquer l’accès à un groupe

Révoque les permissions d’accès d’un utilisateur appartenant à un groupe, en supprimant l’association utilisateur-groupe.

• Paramètres obligatoires : user_id (peut être un tableau), group_id (peut être un tableau)
• Réponse 200 : associations supprimées avec succès
• Réponse 400 : association inexistante, groupe non trouvé, utilisateur non trouvé

Crédits

GET /api/v2/getcredits — Solde des crédits

Renvoie le solde de crédits disponible.

GET /api/v2/getprices — Grille tarifaire

Renvoie la grille tarifaire pour la recharge de crédits.

POST /api/v2/recharge — Recharger des crédits

Effectue une recharge de crédit.

• Paramètres : user_id, amount (ex. 10.50)

Clés

GET /api/v2/getunusednfc — Clés NFC libres

Renvoie la liste des clés NFC non associées à aucun utilisateur. Aucun paramètre requis.

• Réponse 404 : aucune clé NFC libre trouvée

GET /api/v2/getallnfc — Liste des clés NFC

Renvoie les données relatives à toutes les clés NFC présentes sur le panneau, associées ou non.

• Paramètres optionnels (pagination) : limit, offset
• Réponse 400 : aucune clé trouvée, ou offset utilisé sans limit

PUT /api/v2/addkey — Insérer une clé NFC

Insère une nouvelle clé NFC.

• Paramètres obligatoires : nfc_key_code (code RFID lu avec un lecteur standard : il sera converti selon le standard LabKey — ne pas utiliser un code issu d’un journal d’accès), nfc_key_name (nom à associer à la clé)
• Paramètres optionnels : force_hex (force la conversion du code depuis une chaîne hexadécimale ; si omis, la conversion s’effectue automatiquement uniquement si le code contient au moins une lettre)

PUT /api/v2/addkey2user — Associer une clé NFC à un utilisateur

Associe une clé NFC à un utilisateur spécifique.

• Paramètres obligatoires : user_id, nfc_key_id
• Réponse 400 : clé déjà attribuée
• Réponse 404 : clé non trouvée, utilisateur non trouvé

DELETE /api/v2/deletekey — Supprimer une clé NFC

Supprime une clé NFC.

• Paramètres obligatoires : nfc_key_code (code RFID converti selon le standard LabKey, ex. 1234567890 → 210215073)
• Réponse 404 : clé inexistante
• Réponse 400 : nfc_key_code manquant

GET /api/v2/getnfcdetails — Détails d’une clé NFC

Renvoie les détails relatifs à une clé NFC.

• Paramètres obligatoires : nfc_key_code (code converti selon le standard LabKey)
• Réponse 404 : aucun utilisateur relié à la clé, clé NFC non trouvée
• Réponse 400 : paramètres manquants

POST /api/v2/editnfc — Modifier une clé NFC

Modifie les détails d’une clé NFC.

• Paramètres obligatoires : nfc_key_code, name
• Réponse 404 : nfc_key_code non trouvé ou manquant, name manquant

POST /api/v2/edittastierino — Modifier le code du clavier

Change le code d’un clavier (pinpad).

• Paramètres obligatoires : old_pinpad_key_code (ancien code à remplacer), new_pinpad_key_code (nouveau code)
• Réponse 200 : code mis à jour correctement
• Réponse 404 : l’ancien code n’existe pas
• Réponse 400 : le code doit être numérique

POST /api/v2/updatepinpad — Mettre à jour le code du clavier pour un utilisateur

Met à jour le code du clavier en sélectionnant l’utilisateur.

• Paramètres obligatoires : user_id, new_pinpad_key_code
• Réponse 404 : utilisateur inexistant
• Réponse 400 : le code doit être numérique, clé déjà existante

POST /api/v2/getqrcode — Générer un QR Code

Génère un QR Code pour l’utilisateur sélectionné, utilisable à partir de la « message string ».

• Paramètres obligatoires : user_id
• Paramètres optionnels : image (si 1, renvoie l’image du QR Code encodée en base64), with_background (nécessite image=1 ; si 1, ajoute un fond décoratif à l’image)
• Réponse 404 : utilisateur non trouvé

POST /api/v2/getfasturl — Générer une Fast URL

Génère la Fast URL pour l’utilisateur sélectionné, utilisable à partir du champ « fast_url ».

• Paramètres obligatoires : user_id
• Réponse 404 : utilisateur non trouvé

GET /api/v2/getallpinpad — Liste des codes clavier

Renvoie tous les codes clavier et leurs détails.

• Paramètres optionnels (pagination) : limit, offset
• Réponse 400 : définir à la fois limit et offset, ou les laisser tous les deux vides ; limit/offset doivent être des entiers

Accès et permissions

POST /api/v2/getGrantInfo — Détails d’un accès

Renvoie les données relatives à l’accès spécifié.

• Paramètres obligatoires : involved_associations (un ou plusieurs ID renvoyés par l’appel grantaccess)
• Réponse 200 : informations sur l’utilisateur et, pour chaque LabKey associée, les détails de l’accès
• Réponse 400 : il faut envoyer au moins un involved_associations valide
• Réponse 404 : ligne avec cet involved_associations non trouvée

POST /api/v2/automategetGrantInfo — Détails d’accès simplifiés

Appel de commodité pour simplifier l’utilisation de getGrantInfo.

• Paramètres optionnels : user_id (peut être un tableau), unique_name (peut être un tableau — nom de la LabKey sélectionnée)

GET /api/v2/getuservarcodetails — Détails des points d’accès utilisateur

Renvoie tous les détails sur les points d’accès associés à l’utilisateur sélectionné.

• Paramètres obligatoires : user_id

POST /api/v2/grantaccess — Autoriser l’accès

Autorise l’accès d’un utilisateur. Pour configurer une combinaison de plusieurs technologies (NFC, clavier, code-barres), il est possible d’appeler cette API plusieurs fois en changeant la key_id.

• Paramètres obligatoires : user_id, key_id (ID de la clé d’accès associée à l’utilisateur : utiliser nfc_key_id pour NFC/Pocket, pinpad_key_id pour clavier/code-barres), data (chaîne JSON avec les paramètres de chaque point d’accès : plage de dates datei/datef, horaires houri/hourf, jours de la semaine mo,tu,we,th,fr,sa,su, jours fériés tv, command_device_id, id_rele, technology)
• Paramètres optionnels : check_overalapping, force_same_idrele_commanddeviceid

POST /api/v2/editaccess — Modifier un accès

Appel de commodité qui exécute en séquence dropaccess et grantaccess, en renvoyant un nouvel involved_associations pour l’utilisateur. Ce n’est pas une opération atomique : si dropaccess se termine correctement mais que grantaccess échoue, les associations sont malgré tout supprimées.

• Paramètres obligatoires : involved_associations (peut être un tableau), user_id, key_id, data (chaîne JSON, même format que GrantAccess)

DELETE /api/v2/dropaccess — Révoquer un accès

Révoque les permissions d’accès.

• Paramètres obligatoires : involved_associations (code obtenu depuis la réponse de grantaccess)

POST /api/v2/isAccessible — Vérifier l’accessibilité d’un point d’accès

Vérifie si un point d’accès est accessible dans un intervalle de temps donné.

• Paramètres obligatoires : unique_name, from_date (timestamp), to_date (timestamp), id_rele

Gestion des compteurs (antipassback)

GET /api/v2/antipassback/ — Détails du compteur

Renvoie les détails sur la gestion des compteurs pour l’utilisateur et le point d’accès indiqués. La réponse est un tableau avec le détail pour chaque relais.

• Paramètres : user_id, unique_name
• Champs de la réponse : is_active (1/0, compteur actif ou non), has_total/number_total (limite totale d’accès), has_day/number_day (limite journalière), has_week/number_week (limite hebdomadaire), has_month/number_month (limite mensuelle)

POST /api/v2/antipassback/update_or_create — Configurer le compteur

Crée ou met à jour la configuration du compteur pour un ou plusieurs relais.

• Paramètres : user_id, data (chaîne JSON avec, pour chaque LabKey et relais, les champs is_active, has_total/number_total, has_day/number_day, has_week/number_week, has_month/number_month)
• Remarque : si is_active est défini, on ne peut activer qu’un seul paramètre parmi has_total, has_day, has_week ou has_month — il n’est pas possible de les activer simultanément.

Général

GET /api/v2/getlabkeys — Liste des LabKey

Renvoie les détails des unités de contrôle/LabKey.

• Paramètres optionnels : unique_name, labkey_id, key_tipe
• Réponse 400 : aucune LabKey trouvée

GET /api/v2/getbuildings — Liste des structures

Renvoie les informations sur les structures associées au panneau.

• Paramètres optionnels : structure_id, structure_name, referent

GET /api/v2/getlogs — Journal des accès

Renvoie les journaux des accès.

• Paramètres optionnels : from (date de début), to (date de fin), unique_name (nom de la LabKey), labkey_id, user_id, limit (pagination), offset (pagination)

POST /api/v2/sendemail — Envoyer un email

Envoie un email à un client, par exemple avec les détails d’accès.

• Paramètres obligatoires : user_id (destinataire), operator_email (expéditeur)
• Paramètres optionnels : message (message personnalisé ; si omis, un message par défaut est envoyé), cc_emails (tableau d’adresses en copie), show_sender_name, send_permissions_list, send_fast_url, send_qr_code

WebHooks

Alerts — Notifications en temps réel

Permet de recevoir des notifications automatiques vers votre propre endpoint chaque fois qu’un événement se produit (ex. un accès). Le webhook se configure depuis le panneau de Manage, dans la section Alert → Alert Standard.

• Paramètres envoyés en query string vers votre endpoint : user_id, full_name, id_log, key_code, result_boolean (accès autorisé ou non), timestamp, is_log_offline, unique_name, labkey_id, tags, event_type

Champs supplémentaires

Gestion des champs personnalisés que l’on peut associer à la fiche utilisateur (voir aussi Ajout d’un nouvel utilisateur).

GET /api/v2/customfields — Liste des champs

Renvoie la liste des champs supplémentaires avec leurs attributs.

• Paramètres optionnels (pagination) : limit, offset

GET /api/v2/customfields/{id_field} — Détail du champ

Renvoie les détails d’un champ supplémentaire spécifique.

GET /api/v2/customfields/count — Nombre de champs

Renvoie le nombre de champs supplémentaires enregistrés.

POST /api/v2/customfields/create — Créer un champ

Crée un nouveau champ supplémentaire.

• Paramètres obligatoires : type_field (text ou date), name_field (max 255 caractères)
• Paramètres optionnels : order (numérique), is_required (1 = obligatoire lors de la saisie utilisateur), can_disable_user (1 = oui ; utilisable uniquement avec type_field=date — le système désactive automatiquement l’utilisateur à minuit si la date saisie est passée)

POST /api/v2/customfields/{id_field}/update — Modifier un champ

Met à jour un champ supplémentaire existant. Mêmes paramètres que create.

Champs supplémentaires utilisateur

GET /api/v2/customfieldsuser/{id_user}/ — Liste des champs par utilisateur

Renvoie tous les champs supplémentaires renseignés pour un utilisateur.

• Paramètres optionnels (pagination) : limit, offset

GET /api/v2/customfieldsuser/{id_user}/{id_field} — Valeur d’un champ pour un utilisateur

Renvoie la valeur d’un champ supplémentaire spécifique pour l’utilisateur indiqué.

POST /api/v2/customfieldsuser/{id_user}/{id_field}/create — Définir la valeur d’un champ

Crée la valeur d’un champ supplémentaire pour l’utilisateur.

• Paramètres obligatoires : value (max 255 caractères)
• Paramètres optionnels : can_disable_user (0 = non, 1 = oui)

POST /api/v2/customfieldsuser/{id_user}/{id_field}/update — Mettre à jour la valeur d’un champ

Met à jour la valeur d’un champ supplémentaire pour l’utilisateur. Mêmes paramètres que create.

Modèles (Template)

Gestion des modèles prédéfinis pour les accès récurrents (voir aussi Template).

GET /api/v2/templates/count — Nombre de modèles

Renvoie le nombre de modèles enregistrés.

GET /api/v2/templates/ — Liste des modèles

Renvoie la liste des modèles.

• Paramètres optionnels (pagination) : limit, offset

GET /api/v2/templates/detail — Détail d’un modèle

Renvoie le détail d’un modèle spécifique.

• Paramètres : template_id

POST /api/v2/templates/addAccessUser — Appliquer un modèle à un utilisateur

Applique un modèle d’accès à un utilisateur. Cela peut se faire de deux façons : en indiquant à la fois timestamp_start et timestamp_end (le système règle le début et la fin de l’accès sur ces valeurs), ou en indiquant seulement timestamp_start et en laissant le système calculer automatiquement la fin selon les paramètres du modèle.

• Paramètres obligatoires : user_id, template_id
• Paramètres optionnels : timestamp_start (par défaut : maintenant), timestamp_end

Jours fériés

Gestion des jours fériés (voir aussi Jours fériés) : pendant les intervalles configurés, les points d’accès sélectionnés ne s’ouvrent qu’aux utilisateurs autorisés.

GET /api/v2/festivita — Liste des jours fériés

Renvoie tous les jours fériés, ou un jour spécifique si l’ID est transmis.

• Paramètres optionnels : id
• Réponse 404 : jour férié non trouvé

GET /api/v2/festivita/count — Nombre de jours fériés

Renvoie le nombre de jours fériés configurés.

• Paramètres optionnels : id
• Réponse 400 : paramètres invalides ou manquants

GET /api/v2/festivita/is_holiday — Vérifier un jour férié

Vérifie si une date/heure spécifique tombe dans une période de jour férié.

• Paramètres obligatoires : datetime (format YYYY-MM-DD HH:MM:SS)
• Paramètres optionnels : unique_name, labkey_id, rele (tableau), user_id
• Réponse 200 : is_holiday (booléen)
• Réponse 400 : paramètres invalides ou manquants

POST /api/v2/festivita/create — Créer un jour férié

Crée un nouveau jour férié.

• Paramètres obligatoires : title, start_datetime (format YYYY-MM-DD HH:MM:SS), end_datetime (format YYYY-MM-DD HH:MM:SS)
• Paramètres optionnels : description, recurring (1 = récurrent chaque année), notification_email, monday…sunday (1 = actif ce jour), varcos (tableau JSON de labkey_id/rele concernés), user_ids (tableau d’utilisateurs concernés)

POST /api/v2/festivita/update — Modifier un jour férié

Met à jour un jour férié existant. Mêmes paramètres optionnels que create.

• Paramètres obligatoires : id
• Paramètres optionnels : title, start_datetime, end_datetime, recurring, active (1 = activé, 0 = désactivé), notification_email, monday…sunday, varcos, user_ids

DELETE /api/v2/festivita/delete — Supprimer un jour férié

Supprime un jour férié.

• Paramètres obligatoires : id
• Réponse 200 : jour férié supprimé avec succès
• Réponse 400 : paramètres invalides ou manquants
• Réponse 404 : jour férié non trouvé