API Beds24 V2 : accès, appels principaux, limites et pièges

L’API Beds24 en termes simples

Une API est une porte d’entrée pour les logiciels. Au lieu que quelqu’un tape dans votre espace Beds24, une application envoie des demandes comme « quelles chambres sont libres le 12 novembre ? » ou « crée cette réservation ». Les outils de canaux, de prix, de messagerie et les moteurs de réservation comme Bookpage24 fonctionnent tous ainsi.

Vous ne donnez jamais votre mot de passe Beds24 à une application. Vous créez un code d’accès avec seulement les permissions dont elle a besoin, et vous pourrez retirer cet accès dans Beds24 plus tard. En pratique :

1. Demandez à l’application de quelles permissions (scopes) elle a besoin : lecture seule, ou lecture et écriture, pour les réservations, l’inventaire, les établissements, etc.
2. Créez un code d’invitation avec ces permissions sous (SETTINGS) MARKETPLACE > API, comme le décrit la documentation de l’API Beds24. Si le menu n’apparaît pas, le support Beds24 peut l’activer.
3. Envoyez le code à l’application dans les 24 heures : il ne sert qu’une fois.
4. Retirez l’accès dans Beds24 quand vous n’utilisez plus l’application.

On vous demande votre clé API Beds24 ? L’API V2 n’en a pas : créez un code d’invitation avec seulement les permissions nécessaires (valable 24 heures, utilisable une seule fois), et ne communiquez jamais votre mot de passe Beds24.

API V1 ou V2, et où est la clé API ?

L’API V1 est dépréciée et ne sera plus développée (wiki Beds24). Ses fonctions JSON utilisaient une clé API et une clé d’établissement (property key) que vous définissiez vous-même dans l’espace de gestion : c’est ce qu’une application ou un vieux tutoriel appelle une « clé API Beds24 ».

L’API V2 n’a pas de clé : Beds24 indique que l’accès à l’API V2 existe sur chaque compte, sans clé API séparée. Vous créez un code d’invitation, ou un jeton longue durée en lecture seule, et l’application échange le code contre des jetons. Beds24 présente la V2 comme la version actuelle, celle qu’il recommande pour toute nouvelle intégration (documentation API V2). Cette documentation est en anglais ; pour l’interface de Beds24 elle-même, voyez Beds24 en français.

Comment fonctionne l’accès : code d’invitation, jeton de rafraîchissement, jeton

Tout part du code d’invitation : un code que le titulaire du compte crée dans Beds24 en choisissant les permissions, valable 24 heures et utilisable une seule fois. S’il a expiré ou déjà servi, il suffit d’en créer un nouveau. Côté développeur, la suite se déroule ainsi :

1. L’établissement crée un code d’invitation et choisit ses permissions.
2. L’application l’échange par GET /authentication/setup (en-tête code) et reçoit un token (le jeton) et un refreshToken (le jeton de rafraîchissement).
3. Chaque appel envoie le jeton dans un en-tête token. Un jeton dure 24 heures : réutilisez-le, car Beds24 prévient qu’obtenir un nouveau jeton coûte des crédits.
4. Quand il expire, GET /authentication/token avec l’en-tête refreshToken en renvoie un nouveau.

# Échanger le code d'invitation (une fois, dans les 24 heures)
curl -H "code: <CODE_INVITATION>" https://api.beds24.com/v2/authentication/setup

# Appeler l'API avec le jeton reçu
curl -H "token: <JETON>" https://api.beds24.com/v2/properties

Les jetons de rafraîchissement n’expirent pas tant qu’ils ont servi dans les 30 derniers jours : conservez-les chiffrés sur votre serveur et renouvelez le jeton chaque jour. Les traitements en lecture seule peuvent utiliser un jeton longue durée, qui expire après 90 jours sans utilisation. Les éditeurs qui ont beaucoup de clients Beds24 peuvent demander un accès partenaire Marketplace : Beds24 leur délivre alors des jetons d’organisation, et les établissements activent l’intégration dans la Marketplace Beds24 au lieu d’envoyer un code d’invitation.

Les permissions accordées par un code d’invitation

Les permissions (scopes) se choisissent à la création du code d’invitation et ne peuvent plus être modifiées ensuite : pour les changer, créez un nouveau code. Chaque permission se combine avec une méthode : read:bookings, write:bookings ou all:bookings.

Le formulaire demande aussi si l’application peut accéder aux établissements liés (désactivé par défaut) et permet d’ajouter une liste blanche d’adresses IP, pour que seul le serveur de l’application puisse utiliser le code. N’accordez que ce dont l’application a besoin : Bookpage24 demande les réservations, l’inventaire et les établissements, en lecture et écriture.

Les principaux appels et la documentation officielle

Tout se trouve sous https://api.beds24.com/v2. Les appels marqués alpha sont utilisables mais encore en développement ; les beta sont pour l’essentiel terminés et en cours de test.

La documentation interactive Swagger liste tous les appels et permet de les essayer avec votre jeton ; la FAQ et le journal des changements sont sur le wiki Beds24.

Les pièges que nous avons rencontrés

Nous avons construit Bookpage24, un moteur de réservation Beds24, sur cette API. Voici les pièges qui nous ont coûté le plus de temps, chacun vérifié sur l’API réelle :

• numAdults, au pluriel, dans la recherche d’offres. numAdult renvoie une erreur trompeuse, 2002 Occupancy not defined. Les réservations, elles, utilisent numAdult et numChild.
• Les prix des offres excluent la taxe de séjour : ajoutez-la vous-même si les voyageurs doivent voir le montant total.
• Beds24 ne calcule pas le prix des réservations créées par l’API. Sans lignes de facture, une réservation arrive à 0, et le total n’est pas calculé à partir des lignes : envoyez price et les lignes, ou utilisez l’action autoInvoiceItemCharge pour transformer le prix en ligne de débit.
• Envoyez checkAvailability: true dans les actions, pour que Beds24 n’enregistre pas une réservation sur une chambre prise une seconde plus tôt.
• Marquez vos réservations avec apiReference (jusqu’à 100 caractères) : Beds24 réécrit referer en « API », et GET /bookings?apiReference=… retrouve les vôtres.
• Il n’y a pas de bac à sable (sandbox), et l’environnement de test (staging) ne reflète pas entièrement la production : testez sur une chambre dont vous pouvez vous passer.
• Les en-têtes de crédits diffèrent du fichier OpenAPI : fiez-vous aux trois en-têtes décrits dans la section suivante.

Un type de chambre sans offre, c’est ce qui s’affiche « No price found » sur la page de réservation Beds24 : voyez comment corriger « No price found ».

Limites, crédits et coût de l’API

Chaque compte dispose par défaut de 100 crédits par tranche de 5 minutes, partagés entre tous ses jetons ; les sous-comptes ont leur propre limite. Le coût d’une requête est calculé dynamiquement et dépend de sa complexité : les nôtres coûtent en général un à deux crédits. Trois en-têtes de réponse indiquent où vous en êtes : x-five-min-limit-remaining, x-five-min-limit-resets-in (secondes avant la remise à zéro) et x-request-cost.

L’accès à l’API est compris dans le compte Beds24 ; le reste de la facture est détaillé dans notre guide des prix de Beds24. Sur demande au support, Beds24 relève la limite à 200 crédits par 5 minutes pour 10 € par mois, et plus si nécessaire. Avant de payer : réutilisez les jetons, regroupez les écritures (environ 1 Mo ou 10 000 éléments par POST), demandez plusieurs identifiants par GET et préférez les webhooks à l’interrogation régulière.

Les webhooks plutôt que l’interrogation régulière

Plutôt que d’interroger Beds24 à intervalles réguliers pour savoir si quelque chose a changé, laissez Beds24 vous prévenir. Il envoie trois types de webhooks (wiki Beds24) :

• Webhooks de réservation, réglés par établissement sous (SETTINGS) PROPERTIES > ACCESS : ils partent à chaque nouvelle réservation et lors de changements importants, comme de nouvelles dates ou une annulation, mais pas à chaque modification des coordonnées du voyageur. La version 2 envoie la réservation en JSON.
• Webhooks d’inventaire, réglés sous (SETTINGS) MARKETPLACE > WEBHOOKS, quand les disponibilités ou les prix changent.
• Webhooks d’actions automatiques, déclenchés par vos auto actions Beds24.

Comptez un délai moyen d’une minute. Les réservations que vous écrivez par l’API ne déclenchent de webhook qu’avec l’action allowWebhooks, et seulement pour les changements qui touchent la disponibilité : dates, chambre ou statut. Les adresses de webhook se règlent par établissement : si une autre application utilise déjà le webhook de réservation, ne l’écrasez pas ; interrogez plutôt GET /bookings avec modifiedFrom, comme nous le faisons.

Vous développez pour un client ou plusieurs établissements ?

Les agences reconstruisent souvent le même parcours de réservation pour chaque client : offres, taxe de séjour, paiement et écriture de la réservation dans Beds24. Bookpage24 le fait déjà au-dessus de Beds24, sous forme de page hébergée, de widget de deux lignes de code ou de plugin WordPress, facturé par établissement. Vous gérez plusieurs établissements ? Réservez un appel de 20 minutes.

Vous êtes hôtelier et voulez simplement une page de réservation à votre image, sans développement ? Bookpage24 n’a pas d’essai gratuit : vous créez un compte, connectez Beds24 avec un code d’invitation et voyez le diagnostic de vos types de chambre avant de payer quoi que ce soit ; la page est mise en ligne quand votre abonnement démarre. Connecter Beds24 – diagnostic offert.

Questions fréquentes