Smoobu dispose d'une API pour qu'un outil ou votre propre code puisse lire et écrire vos données de réservation, ainsi que de webhooks qui préviennent votre système dès que quelque chose change. Vous gérez tout cela sous Paramètres avancés > Clés API. Utilisez-la quand un outil de gestion a besoin d'accéder à vos réservations ou quand vous construisez votre propre intégration. C'est réservé aux utilisateurs avancés : le support client ne peut aider que pour les problèmes d'intégration liés aux partenaires du Marketplace. Notre équipe support ne peut pas aider pour des développements sur mesure.
Avant de commencer
Vous avez besoin de ceci avant de pouvoir utiliser l'API :
- Un compte Smoobu payant. Les clés ne peuvent pas être générées sur un essai gratuit.
- L'identifiant du compte principal. Seul le compte principal dispose de clés API. Un identifiant de membre d'équipe n'a pas de page Clés API. Vous ne pouvez donc pas limiter une intégration à certaines de vos propriétés en lui donnant l'accès d'un membre d'équipe.
- La conscience qu'une clé donne accès à tout votre compte. Traitez une clé comme un mot de passe. La seule chose qu'une clé ne peut pas lire sans votre autorisation, ce sont les données personnelles de vos invités.
Créer une clé API
- Dans Smoobu, ouvrez Paramètres avancés, puis Clés API.
- Cliquez sur Créer en haut à droite.
- Dans la fenêtre Créer un jeton API, saisissez un nom court dans Étiquette (facultatif) pour reconnaître la clé plus tard. Si l'outil a besoin des noms, adresses e-mail ou numéros de téléphone de vos invités, cochez Autoriser l'accès aux données personnelles des invités. S'il n'en a pas besoin, laissez la case décochée. Cliquez sur Soumettre.
- Smoobu affiche Jeton créé avec votre nouvelle clé dans le champ Étiquette et votre Secret en dessous. Copiez les deux avec les boutons de copie et rangez-les aussitôt en lieu sûr, par exemple dans un gestionnaire de mots de passe : Smoobu n'affiche le secret qu'une seule fois. Cochez J'ai copié mon secret et cliquez sur Fermer.
- La nouvelle clé apparaît dans la liste avec son étiquette, et vous pouvez recopier la clé à tout moment depuis la colonne Clé. Le secret, lui, ne peut plus être affiché : si vous le perdez, révoquez la clé et créez-en une nouvelle. Collez la clé et le secret dans l'outil ou le code qui a besoin de l'accès.
Chaque clé donne accès à tout votre compte. La seule partie que vous pouvez exclure, ce sont les données personnelles de vos invités : noms, adresses e-mail, numéros de téléphone, notes et messages. La colonne Données des invités de la liste des clés indique quelles clés peuvent les lire. Si vous utilisez plusieurs intégrations, générez une clé distincte pour chacune, afin de pouvoir en révoquer une sans casser les autres. Pour retirer une clé, cliquez sur Révoquer à côté d'elle : toute requête qui l'utilise encore cesse aussitôt de fonctionner.
Clés créées avant le 26 octobre 2026
Les clés qui existaient avant l'ajout de l'accès aux données des invités peuvent encore lire les données personnelles de vos invités jusqu'au 30 novembre 2026. Après cette date, elles ne renvoient plus aucune information sur les invités, sauf si vous avez autorisé les données des invités pour ces clés. Si un outil a besoin des informations sur les invités, autorisez les données des invités pour sa clé sur la page Clés API avant le 30 novembre, pour que l'outil continue de fonctionner. Si un outil n'en a pas besoin, ne faites rien : à partir du 1er décembre, sa clé ne lit plus les données des invités.
Protéger votre clé
Une clé est un mot de passe donnant accès à tout votre compte : traitez-la comme un mot de passe.
- N'écrivez jamais une clé directement dans votre code. Cela vaut pour les clés API, les mots de passe et les tokens : quiconque peut voir le code peut voir la clé.
-
Stockez plutôt les identifiants dans des variables d'environnement, par exemple dans un fichier
.envque votre code lit au moment de l'exécution. -
Gardez le fichier
.envhors du contrôle de version. Ajoutez.envet tout autre fichier de configuration contenant des secrets à votre.gitignore, pour qu'ils ne soient jamais envoyés sur GitHub. - Rendez vos dépôts privés. Si votre code d'intégration est hébergé sur GitHub, réglez immédiatement la visibilité du dépôt sur Private, surtout quand le code est votre propre travail propriétaire.
Si une clé fuit malgré tout, révoquez-la sur la page Clés API et créez-en une nouvelle ; la clé compromise cesse aussitôt de fonctionner.
Configurer un webhook
Un webhook prévient votre propre système quand quelque chose change dans Smoobu, pour que votre système n'ait pas à demander sans cesse.
- Sur la page Clés API, trouvez le champ Webhook URLs.
- Saisissez l'adresse, sur votre serveur, qui doit recevoir les mises à jour.
- Cliquez sur Sauvegarder. Vous pouvez ajouter plus d'un webhook.
Smoobu envoie chaque mise à jour une seule fois et ne réessaie pas. Si votre serveur ne répond pas dans les 60 secondes, cette mise à jour est perdue. Utilisez l'API pour récupérer les évènements que vous avez pu manquer. Pour voir ce que Smoobu envoie avant de vous y fier, saisissez une adresse temporaire d'un service comme webhook.site et faites une réservation test.
Smoobu envoie un webhook pour ces événements :
- une nouvelle réservation
- une réservation mise à jour
- une réservation annulée
- une réservation supprimée
- une modification des prix, de la durée minimale de séjour ou des disponibilités
- un enregistrement en ligne soumis
- un nouveau message
Cette liste est complète. Il n'y a pas de webhook pour les avis, et il n'y a pas d'événements cachés ou non documentés. Les modifications des lignes de prix d'une réservation (éléments de prix) sont envoyées uniquement aux partenaires d'intégration configurés par Smoobu, jamais aux adresses que vous saisissez ici.
Ce champ ne contient que les webhooks que vous ajoutez vous-même. Certains partenaires du Marketplace enregistrent les leurs via l'API de Smoobu au moment où vous les connectez. Vous n'avez donc jamais à saisir l'adresse d'un partenaire dans ce champ.
Pour connaître les données exactes que Smoobu envoie avec chaque événement, ouvrez la documentation développeur (docs.smoobu.com) : sur la page Clés API, cliquez sur Click here for API documentation. La même documentation contient la référence complète des points de terminaison et des exemples de code.
Connecter plutôt un outil du Marketplace
Si l'outil que vous voulez est déjà un partenaire du Marketplace de Smoobu, par exemple un outil de tarification ou un outil de check-in, vous ne transmettez aucune clé. Suivez simplement les guides dans le Marketplace de Smoobu. Vous pouvez déconnecter les partenaires du Marketplace à tout moment, ce qui coupe aussitôt l'accès du partenaire. Cela ne met toutefois pas forcément fin à votre abonnement pour le service concerné. Empruntez cette voie quand elle existe, et ne générez votre propre clé que pour un outil ou un script qui n'est pas un partenaire listé.
Signer vos requêtes avec HMAC
Smoobu fait passer l'accès direct à l'API à des requêtes signées (HMAC), pour que chaque appel prouve qu'il est authentique et non modifié. Si vous avez construit votre propre intégration, vous devez ajouter la signature avant le 31 octobre 2026 ; après cette date, les requêtes non signées sont rejetées. Pendant la transition, les requêtes signées et non signées fonctionnent toutes les deux, vous pouvez donc basculer et tester sans casser votre configuration en production.
Qui doit agir :
- Partenaires du Marketplace (outils de tarification, outils de check-in et similaires) : rien à faire, le partenaire s'en occupe.
- Connexions de portail (Airbnb, Booking.com et autres portails) : non concernées.
- Votre propre script ou intégration que vous contrôlez : ajoutez la signature avec les étapes ci-dessous.
- Un outil que vous ne contrôlez pas mais dans lequel vous avez collé votre clé : suivez les étapes 1 et 2 ci-dessous pour activer la signature. Contactez ensuite l'entreprise externe et transmettez-lui votre nouvelle clé API et votre secret, pour qu'elle puisse se connecter à Smoobu.
Pour configurer la signature :
- Créez une clé comme décrit plus haut sous Créer une clé API. Chaque clé créée là vient avec un secret, affiché une seule fois dans la fenêtre Jeton créé.
- Rangez le secret en lieu sûr. Si vous le perdez, créez une nouvelle clé et mettez votre intégration à jour avec la nouvelle clé et le nouveau secret avant de révoquer l'ancienne, pour que votre intégration ne s'arrête jamais entre-temps.
- Mettez votre intégration à jour pour qu'elle signe chaque requête. En plus de votre clé, chaque requête envoie quatre en-têtes supplémentaires :
- X-API-Key (votre clé),
-
X-Timestamp (l'heure actuelle au format UTC ISO 8601 (exemple :
2026-04-01T12:00:00Z)), - X-Nonce (une valeur unique que vous ne réutilisez jamais : utilisez UUID v4),
- et X-Signature (la signature HMAC-SHA256). Comment construire la signature et le format exact de chaque en-tête sont dans la documentation développeur : le guide technique complet avec des exemples de code est disponible ici : docs.smoobu.com/#hmac-authentication
Récupérer vos réservations dans votre propre système
Vos données de réservation peuvent être récupérées via l'API dans votre propre site web ou système. La personne qui s'en occupe aura besoin de la documentation API de Smoobu et de l'endpoint des réservations, GET /api/reservations, avec la clé API de votre compte. Les noms et les coordonnées des invités ne sont transmis que si la clé est autorisée à lire les données des invités. Un point à transmettre à votre développeur : parmi les paramètres de date de cet endpoint, seuls from et to fonctionnent pour le moment.
Problèmes fréquents
Créer est absent ou ne fait rien
La génération de clés est désactivée sur les comptes d'essai gratuit.
Ma clé API ne fonctionne plus
Smoobu désactive toute clé qui n'a pas été utilisée depuis plus de 90 jours. Vous n'êtes pas prévenu avant, et une clé désactivée ne peut pas être réactivée. Créez une nouvelle clé comme décrit plus haut et ajoutez-la, avec son secret, à votre outil ou à votre code.
Si vous résiliez votre forfait payant, vos clés sont suspendues. Elles fonctionnent de nouveau si vous vous réabonnez dans les 90 jours.
Les noms et les informations des invités reviennent vides
La clé n'a pas accès aux données personnelles de vos invités. Les noms, adresses e-mail, numéros de téléphone et notes des invités reviennent alors vides. Les requêtes portant sur les informations des invités ou sur les données d'enregistrement en ligne sont refusées avec 403 Forbidden. Autorisez les données des invités pour cette clé sur la page Clés API. Vous pouvez aussi créer une nouvelle clé avec Autoriser l'accès aux données personnelles des invités coché, puis l'utiliser dans votre outil. Les dates, les prix, les propriétés et les paiements ne sont pas concernés.
Un outil partenaire reçoit vos mises à jour de réservation, mais aucun webhook n'apparaît dans Smoobu
Rien n'est cassé et vous n'avez rien à corriger. Lorsqu'un partenaire du Marketplace enregistre un webhook pour vous, Smoobu le stocke séparément des vôtres et il reste invisible dans ce champ. Vos propres webhooks ne changent pas. Si vous déconnectez le partenaire plus tard, Smoobu supprime ses webhooks à votre place.
Mon serveur manque des webhooks
Smoobu envoie chaque webhook une seule fois, sans nouvelle tentative. Une mise à jour n'atteint pas votre système quand :
- votre serveur ne répond pas dans les 60 secondes. Smoobu abandonne la mise à jour.
- votre serveur répond avec HTTP 400. Votre serveur a refusé les données envoyées par Smoobu. Consultez les journaux de votre serveur pour savoir pourquoi.
Utilisez l'API pour récupérer les réservations et les modifications que vous avez pu manquer. Pour vérifier ce qui arrive, saisissez une adresse temporaire d'un service comme webhook.site dans le champ des webhooks, faites une réservation test et regardez ce qui arrive. Si votre adresse répond sans cesse par des erreurs, Smoobu la désactive et vous envoie un e-mail (voir la section suivante).
J'ai reçu un e-mail indiquant que mon URL de webhook a été désactivée
Smoobu désactive une adresse de webhook lorsqu'elle répond sans cesse par des erreurs, et vous envoie cet e-mail. Tant qu'elle est désactivée, cette adresse ne reçoit plus de mises à jour de Smoobu.
- Vérifiez le système derrière l'adresse : votre propre serveur, ou l'outil pour lequel vous l'avez saisie. Il doit être en ligne et accepter les mises à jour sans erreur. Si l'adresse appartient à un outil, contactez l'entreprise qui le propose.
- Sur la page Clés API, saisissez à nouveau la même adresse dans le champ des webhooks et cliquez sur Sauvegarder.
Si l'adresse répond toujours par des erreurs, Smoobu la désactive à nouveau. Si vous n'utilisez plus cette adresse, vous n'avez rien à faire.
Les requêtes sont bloquées avec 429
Vos requêtes échouent avec HTTP 429 et le message « Requests limit exceeded » : votre intégration envoie plus de requêtes que Smoobu n'en autorise. Le blocage dure tant que votre intégration continue d'envoyer des appels. Pour passer :
- Appelez moins souvent. Répartissez vos requêtes dans le temps.
- Faites une pause, puis réessayez. Quand vous recevez une erreur 429, attendez avant d'envoyer la requête suivante, au lieu de réessayer immédiatement.
- Regroupez vos requêtes quand c'est possible, au lieu d'en envoyer beaucoup de petites.
La limite exacte figure dans la documentation développeur (docs.smoobu.com).
Mes requêtes signées échouent avec 401 Unauthorized
La signature ou l'horodatage en est généralement la cause. Autres causes fréquentes :
- Décalage d'horloge : l'heure de votre système s'écarte de plus de 5 minutes. Assurez-vous que votre serveur utilise NTP.
- Nonce réutilisé : chaque requête doit avoir un X-Nonce unique (utilisez UUID v4 ou des octets aléatoires).
- Mauvais hachage du corps : pour les requêtes GET et DELETE, hachez une chaîne vide, pas null ni undefined.
- Ordre de la chaîne de requête : triez les paramètres par ordre alphabétique quand vous construisez la chaîne canonique.
- Encodage différent : signez le corps JSON brut exactement tel qu'il est envoyé, avec le même espacement et le même encodage.
Pendant la transition, vous pouvez revenir temporairement aux requêtes non signées pendant que vous corrigez le problème.
Articles associés
- Regrouper une propriété et ses sous-propriétés pour éviter les doubles réservations
- Smoobu pour les gestionnaires immobiliers
Toujours bloqué ?
Si ces étapes n'ont pas réglé le problème, contactez l'équipe Smoobu : ouvrez le menu Aide pour ouvrir un ticket ou réserver un créneau d'appel, ou utilisez la bulle de chat en bas à droite. Pour obtenir la réponse la plus rapide, indiquez :
- Votre Smoobu User ID (dans le menu de l'icône de profil, en haut à droite).
- Le nom ou l'ID du logement, s'il s'agit d'un logement précis.
- Le Booking ID, s'il s'agit d'une réservation précise (Réservations, puis Afficher plus).
- Le nom du portail, s'il s'agit de synchronisation de portail (Booking.com, Airbnb, Vrbo, etc.).
- Un bref pas à pas : ce que vous avez fait, ce que vous attendiez et ce qui s'est passé.
- Des captures d'écran ou une courte capture vidéo du problème.
- Votre navigateur et votre système d'exploitation, si quelque chose s'affiche mal à l'écran.
Commentaires
0 commentaire
Vous devez vous connecter pour laisser un commentaire.