Utiliser l'API Smoobu : créer une clé API, configurer des webhooks et signer vos requêtes

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. Si vous êtes en essai et avez besoin d'un accès API, contactez le support Smoobu pour le faire activer.
La conscience que chaque clé donne un accès complet à tout votre compte. Traitez une clé comme un mot de passe.

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, puis 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 un accès complet à tout votre compte, et il n'existe aujourd'hui aucun moyen de limiter une clé à une partie seulement de vos données. 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.

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 .env que votre code lit au moment de l'exécution.
Gardez le fichier .env hors du contrôle de version. Ajoutez .env et 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 un webhook pour ces événements :

une nouvelle réservation
une réservation mise à jour
une réservation annulée
un enregistrement en ligne soumis
un élément de prix créé
un élément de prix mis à jour
un élément de prix supprimé
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.

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 :
1. X-API-Key (votre clé),
2. X-Timestamp (l'heure actuelle au format UTC ISO 8601 (exemple : 2026-04-01T12:00:00Z)),
3. X-Nonce (une valeur unique que vous ne réutilisez jamais : utilisez UUID v4),
4. 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. 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. Si vous êtes en essai et avez besoin d'un accès API, contactez le support Smoobu pour le faire activer.

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.

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

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.

Articles dans cette section