Guide technique de l'API Misterbooking
Destiné aux administrateurs et utilisateurs techniques qui connectent des modules tiers à Misterbooking.
Présentation
L'API Misterbooking est une interface REST qui permet aux applications tierces autorisées de lire et d'écrire des données dans un compte d'établissement Misterbooking. Toutes les requêtes doivent être authentifiées à l'aide d'une clé d'API générée depuis le panneau d'administration Misterbooking. Les requêtes sont effectuées en HTTPS et les réponses sont renvoyées au format JSON.
Authentification
Incluez votre clé d'API Misterbooking dans l'en-tête X-Api-Key de chaque requête. Exemple : X-Api-Key: <votre-cle-api-misterbooking>. Les clés doivent être conservées confidentielles. En cas de compromission, révoquez-la depuis le panneau d'administration Misterbooking et générez-en une nouvelle immédiatement.
Catégories d'endpoints principales
- Réservations : opérations GET/POST/PATCH sur les fiches de réservation. Comprend l'arrivée/le départ, le type de chambre, le plan tarifaire, les coordonnées du client, le canal d'origine, l'état du paiement.
- Tarifs : GET pour récupérer les tarifs en cours ; POST pour envoyer des mises à jour sur des plages de dates et des types de chambres spécifiques. Requis pour les modules Revenue Optimizer et Smart Pricing.
- Profils clients : GET du profil par réservation ou par identifiant client ; POST pour la mise à jour des profils. Requis pour les modules Guest Portal et CRM Link.
- Canaux : GET pour lister les canaux connectés et leur statut. Lecture seule ; les connexions aux canaux se gèrent dans l'interface du channel manager Misterbooking.
- Rapports : GET des données de night audit, du rapport pick-up, du récapitulatif d'occupation. Requis pour les modules Accounting Sync et Reporting Plus.
- Webhooks : enregistrement d'une URL de webhook pour recevoir les notifications d'événements (nouvelle réservation, départ, annulation). Requis pour le module Email Automation.
Limitation de débit
Misterbooking applique une limite de débit par clé d'API. Le dépassement renvoie un HTTP 429. Mettez en place un back-off exponentiel : attendez 1 s au premier 429, 2 s au deuxième, 4 s au troisième, etc. Regroupez les requêtes par plage de dates dans la mesure du possible plutôt que d'appeler l'API par nuitée, afin de minimiser le volume d'appels.
Gestion des erreurs
| Statut HTTP | Signification | Action |
|---|---|---|
| 200/201 | Succès | Traiter la réponse normalement |
| 400 | Requête invalide — payload mal formé | Vérifier la structure de la requête dans la doc de l'API |
| 401 | Non autorisé — clé d'API invalide | Vérifier que la clé d'API est correcte et non révoquée |
| 403 | Interdit — permissions insuffisantes | Vérifier les portées de la clé d'API dans Misterbooking |
| 404 | Ressource introuvable | Vérifier l'identifiant de la réservation / du plan tarifaire |
| 429 | Limite de débit dépassée | Mettre en place un back-off exponentiel |
| 500/503 | Erreur serveur Misterbooking | Réessayer après 60 s ; contacter le support Misterbooking en cas de persistance |
Environnement de tests et sandbox
Misterbooking fournit un environnement sandbox pour les tests d'API sur certains paliers d'abonnement. Renseignez-vous auprès de votre gestionnaire de compte Misterbooking pour y accéder. Bookingmister exécute des tests d'intégration sur la sandbox Misterbooking avant chaque publication de module et après chaque notification de mise à jour de l'API Misterbooking.