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 Generate API Key.
Copiez la clé et rangez-la aussitôt en lieu sûr, par exemple dans un gestionnaire de mots de passe. Smoobu n'affiche la clé qu'une seule fois ; si vous quittez la page sans l'enregistrer, vous devrez en générer une nouvelle.
Collez la clé 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é, supprimez-la sur cette page : l'outil qui l'utilise perd aussitôt l'accè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 .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, supprimez-la sur la page Clés API et générez-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.

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 25 septembre 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é : ne supprimez pas votre clé et ne la migrez pas vous-même, cela casserait l'outil. Contactez l'équipe Smoobu, indiquez l'outil que vous utilisez, et Smoobu configure le partenaire. Votre clé continue de fonctionner pendant la transition.

Pour configurer la signature :

Allez à Paramètres avancés, puis Clés API.
Cliquez sur Créer, donnez à la clé un libellé clair et cliquez sur Soumettre.
Copiez le secret aussitôt et rangez-le en lieu sûr. Smoobu ne l'affiche qu'une seule fois. Si vous le perdez, utilisez Regenerate Secret sur cette page ; mais la régénération annule aussitôt l'ancien secret, alors mettez d'abord votre intégration à jour.
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

Problèmes fréquents

Generate API Key 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.

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