Utiliser l'API Misterbooking pour les intégrations tierces

L'API Misterbooking donne aux applications tierces autorisées un accès en lecture et en écriture aux données de réservation, aux plans tarifaires, aux profils clients et à la configuration des canaux d'un compte Misterbooking. Cet article présente les principes généraux de la connectivité à l'API Misterbooking et la façon dont les modules proposés par Bookingmister établissent et maintiennent une connexion.

Authentification à l'API Misterbooking

L'API Misterbooking utilise une authentification par clé d'API. Chaque compte Misterbooking peut générer une ou plusieurs clés d'API depuis la section d'administration de l'interface Misterbooking (généralement dans Administration → Intégrations → Accès API). La clé d'API est une longue chaîne alphanumérique transmise dans l'en-tête de chaque requête afin d'identifier l'application appelante et le compte d'établissement auquel elle est autorisée à accéder.

Les clés d'API Misterbooking peuvent généralement être limitées à des permissions spécifiques. Les portées les plus courantes incluent : lecture des réservations, écriture des réservations, lecture des tarifs, écriture des tarifs, lecture des profils clients, écriture des profils clients, lecture de la configuration des canaux et lecture des données de reporting. Les applications tierces ne doivent demander que le minimum de permissions nécessaires à leur fonction — un principe de moindre privilège qui réduit l'exposition au risque en cas de compromission d'une clé.

Les clés d'API doivent être traitées comme des identifiants sensibles. Elles accordent un accès complet à l'établissement Misterbooking connecté, dans la limite de leur portée. Elles doivent être stockées chiffrées, transmises uniquement en HTTPS et renouvelées régulièrement. Lorsque vous connectez un module via Bookingmister, votre clé d'API Misterbooking est stockée chiffrée en AES-256 et n'est jamais accessible en clair.

Lecture des données de réservation depuis Misterbooking

L'API Misterbooking fournit des endpoints pour interroger les réservations sur une plage de dates. Une réponse type comprend : l'identifiant de la réservation, le nom du client, les dates d'arrivée et de départ, le type de chambre, le plan tarifaire, le montant total, l'état du paiement, le canal d'origine et les coordonnées du client. Ces données constituent la base de la plupart des intégrations tierces.

Pour des modules comme Guest Portal et CRM Link, le processus est le suivant : (1) interroger Misterbooking pour obtenir les réservations arrivant dans les 14 prochains jours ; (2) pour chaque réservation, récupérer le profil client associé ; (3) traiter les données du client dans la fonction du module (par exemple envoyer un lien de portail pré-arrivée) ; (4) réécrire les données recueillies dans la fiche de réservation Misterbooking. Les étapes 1 et 2 sont des opérations de lecture ; l'étape 4 est une opération d'écriture qui requiert la permission « écriture des réservations » ou « écriture des profils clients ».

Gestion tarifaire via l'API Misterbooking

L'API Misterbooking prend en charge les opérations de lecture et d'écriture sur les plans tarifaires. Un appel d'écriture typique précise : l'identifiant du plan tarifaire (tel que défini dans votre compte Misterbooking), la ou les dates d'arrivée ou plage de dates, le(s) type(s) de chambre et le nouveau tarif. Les mises à jour tarifaires envoyées via l'API sont répercutées dans le channel manager Misterbooking puis diffusées vers les OTA connectées selon le cycle de mise à jour standard de Misterbooking.

La diffusion tarifaire via l'API est la fonction principale utilisée par les modules Revenue Optimizer et Smart Pricing. Le déroulé est le suivant : (1) lire les tarifs et l'occupation actuels dans Misterbooking ; (2) calculer un tarif recommandé ou déclenché par une règle ; (3) envoyer le nouveau tarif à Misterbooking via l'API ; (4) Misterbooking distribue la mise à jour aux canaux connectés. Les étapes 1 et 3 nécessitent respectivement les permissions de lecture et d'écriture des tarifs.

Intégrations par webhook et pilotées par événements

En complément des appels par interrogation, Misterbooking prend en charge la livraison par webhook pour certains événements de réservation. Une fois configurés dans votre compte Misterbooking (généralement dans Administration → Intégrations → Webhooks), Misterbooking envoie une requête HTTP POST vers une URL prédéfinie lorsque des événements précis se produisent — création d'une nouvelle réservation, modification d'une réservation ou finalisation d'un départ.

Les intégrations basées sur les webhooks sont utilisées par le module Email Automation. Lorsque Misterbooking déclenche un webhook « départ effectué », le module lance immédiatement la séquence d'e-mails post-séjour appropriée, sans avoir à interroger Misterbooking toutes les quelques minutes. Cette architecture événementielle réduit le volume d'appels API et améliore le temps de réponse pour les communications sensibles au délai.

Limitation de débit et gestion des appels API

Misterbooking impose des limites de débit sur les appels API afin d'éviter la surcharge du système. Le dépassement de la limite entraîne des réponses HTTP 429 (Too Many Requests). Les modules tiers bien conçus mettent en œuvre un back-off exponentiel lorsqu'ils rencontrent des erreurs de limitation et regroupent les requêtes dans la mesure du possible plutôt que d'effectuer des appels individuels par nuitée.

Les modules Bookingmister sont conçus pour respecter les limites de débit de Misterbooking. Les mises à jour tarifaires sont regroupées dès que possible. Les intervalles d'interrogation sont configurés de manière prudente. Lorsque plusieurs modules sont actifs sur un même compte Misterbooking, les appels sont coordonnés pour éviter tout volume d'appels inutilement élevé.

Rester compatible avec les évolutions de l'API Misterbooking

Misterbooking publie régulièrement des mises à jour de son API. Certaines ajoutent de nouveaux endpoints ou champs (changements non cassants), d'autres peuvent déprécier ou modifier des endpoints existants (changements potentiellement cassants pour les applications dépendantes). Bookingmister surveille le journal des évolutions de l'API Misterbooking et teste chaque module contre chaque version. Lorsqu'un changement cassant est détecté, les modules concernés sont mis à jour et un correctif de compatibilité est publié généralement sous 48 heures.