Connecter le check-in et le check-out à vos systèmes via l'API
L'Open API Yoffix permet à d'autres systèmes de confirmer des check-ins et d'effectuer des check-outs dans Yoffix. Un lecteur de badges à l'entrée du bureau peut par exemple confirmer une réservation de bureau dès que la personne arrive, sans check-in séparé dans l'application.
Ce que vous pouvez enregistrer
L'API fonctionne avec les réservations de bureaux et de zones, les réservations de salles, les visiteurs et le parking. Une place de parking réservée avec un bureau suit le bureau : quand le bureau est confirmé ou fait l'objet d'un check-out, la place de parking aussi.
Créer une clé API
Les administrateurs créent la clé API dans Paramètres → Intégrations → Open API. Une seule clé couvre toute votre entreprise. Envoyez-la dans l'en-tête X-Api-Key à chaque requête, et conservez-la comme un mot de passe dans le coffre de secrets de votre intégration.
URL de base et endpoints
Toutes les requêtes passent par https://api.app.yoffix.com/open-api.
POST /v1/check-ins/confirmconfirme un check-in.POST /v1/check-ins/check-outeffectue le check-out d'un check-in confirmé.POST /v1/check-ins/lookuptrouve les check-ins correspondant à une lecture de badge.GET /v1/check-ins/{id}renvoie un check-in précis.
Deux façons d'identifier une réservation
Si votre système connaît l'identifiant Yoffix, envoyez-le directement : l'identifiant de réservation pour un bureau, l'identifiant d'événement de calendrier pour une salle, l'identifiant d'invité pour un visiteur ou l'identifiant de réservation de parking. Si votre système sait seulement qui a badgé et où, envoyez plutôt l'événement d'accès, avec l'identifiant du badge, le lecteur, la porte ou le portique, et le sens de passage (entrée ou sortie). Yoffix retrouve alors lui-même la réservation correspondante.
Indiquez l'heure du passage dans occurredAt. Yoffix la compare à la fenêtre de check-in. Sans elle, c'est l'heure de réception de la requête qui compte.
Check-in par lecteur de badges
Votre système d'accès envoie l'identifiant du badge, le lecteur et le point d'accès à l'endpoint de lookup.
Yoffix renvoie les check-ins correspondants et une action recommandée : confirmer, effectuer le check-out, ou aucune.
Votre système envoie cette commande avec la même clé d'idempotence et les mêmes données d'accès.
Éviter les doublons
Envoyez une Idempotency-Key avec chaque confirmation et chaque check-out, dans l'en-tête ou dans le corps de la requête. Les systèmes d'accès utilisent de préférence l'identifiant d'événement de l'appareil. Si la même clé arrive deux fois pour la même commande, Yoffix renvoie la réponse d'origine sans rien modifier. Si une clé est réutilisée pour une autre commande, la requête échoue avec DUPLICATE. Confirmer un check-in déjà confirmé compte aussi comme un succès.
Erreurs
Chaque erreur renvoie success: false, un message lisible et un code d'erreur que votre intégration peut traiter. Une clé absente ou incorrecte renvoie INVALID_API_KEY. Un badge que Yoffix ne peut associer à personne dans votre entreprise renvoie UNKNOWN_MEDIA, et une réservation inconnue SUBJECT_NOT_FOUND. Un passage en dehors de la fenêtre de check-in renvoie OUTSIDE_WINDOW. Un check-in déjà clôturé, expiré ou annulé renvoie ALREADY_CHECKED_OUT, EXPIRED ou CANCELLED.
Référence de l'API
La référence complète, avec des exemples de requêtes et de réponses pour chaque endpoint, se trouve sur openapi-docs.yoffix.com. Pour toute question, écrivez à support@yoffix.com.
Articles associés : Check-in