API de disponibilité hôtelière : concevoir pour la lenteur

Le ticket arrive généralement sous un air innocent : « Ajouter la recherche d'hôtels à la page de réservation — le fournisseur nous a donné une API de disponibilité hôtelière, il y a un sandbox, ça tient en un sprint. » Vous lisez la documentation, vous envoyez une requête pour deux adultes à Lisbonne pendant trois nuits, et une réponse revient. Puis vous envoyez la même requête pour une ville qui compte beaucoup plus d'établissements, et rien ne revient pendant un long moment gênant. Quand la réponse arrive enfin, c'est un document assez volumineux pour que votre parseur JSON s'interroge sur ses choix de carrière.
C'est à ce moment-là que le travail change de nature. La disponibilité hôtelière n'est pas une simple lecture. C'est un fan-out : une seule question de l'utilisateur devient de nombreuses questions posées à de nombreux fournisseurs, chacun répondant à sa propre vitesse, avec son propre vocabulaire et sa propre idée de ce qu'est une « chambre ». Le client que vous construisez doit rester utile pendant que cette dispersion n'est pas encore résolue. Cet article porte sur la conception de ce client, et il s'adresse à un développeur qui maîtrise REST et JSON mais qui n'a jamais eu à expliquer à un hôtel pourquoi un tarif non remboursable a été affiché comme annulable gratuitement.
Pourquoi une API de disponibilité hôtelière est plus lente que les endpoints habituels
Une recherche de vols et une recherche d'hôtels se ressemblent vues de l'extérieur : une requête part, des options tarifées reviennent. À l'intérieur, ce n'est pas le même problème. Si vous avez lu nos notes sur ce qu'implique réellement l'intégration d'une API de réservation de vols, vous savez déjà que le prix recherché n'est pas toujours le prix réservé. L'hôtellerie ajoute une seconde difficulté par-dessus : le volume.
Une seule ville peut compter des centaines d'établissements. Chaque établissement vend plusieurs types de chambres. Chaque type de chambre est vendu sous plusieurs plans tarifaires — petit-déjeuner inclus ou non, remboursable ou non, tarif membre, tarif package. Chaque plan tarifaire peut provenir de plusieurs fournisseurs : une bedbank, un channel manager, un contrat direct, un grossiste avec qui vous avez signé parce que son allotment dans tel hôtel était meilleur que celui des autres. Multipliez le tout, et une recherche « simple » devient un grand arbre assemblé à partir de sources qui ne s'accordent ni sur les noms ni sur les identifiants.
La partie lente est donc rarement votre code. C'est le fournisseur le plus lent que vous avez choisi d'attendre.
Résultats progressifs ou réponse complète : choisissez délibérément
Il existe deux façons honnêtes de renvoyer des résultats de recherche hôtelière, et la plupart des intégrations finissent dans un entre-deux inconfortable.
Tout attendre. Votre backend distribue la requête, attend que chaque fournisseur réponde ou expire, fusionne, déduplique, trie et renvoie une liste complète unique. Le résultat est propre : une requête, une réponse, des prix comparables puisqu'ils sont tous sur la table. Le prix à payer : l'utilisateur fixe un indicateur de chargement aussi longtemps que met votre fournisseur le plus lent, à chaque fois.
Diffuser ce qui arrive. Votre backend lance la distribution et renvoie immédiatement un identifiant de recherche. Le client interroge cet identifiant, ou garde un flux ouvert, et reçoit les résultats par lots au fil des réponses. Les premiers hôtels apparaissent vite. Le prix à payer, c'est la complexité partout ailleurs : la liste se réordonne pendant que l'utilisateur la lit, un badge « le moins cher » peut se déplacer, et un hôtel apparu via un fournisseur peut recevoir plus tard un tarif inférieur d'un autre.
Si votre interface est une page de recherche devant un humain, le progressif est presque toujours le bon choix — la personne navigue, elle ne lance pas un traitement par lots, et une page qui travaille visiblement vaut mieux qu'une page qui réfléchit en silence. Si votre consommateur est une autre machine — un job de comparaison tarifaire, un outil de réservation d'entreprise qui a besoin d'une réponse unique et définitive — attendre est souvent plus simple et correct.
Quel que soit votre choix, trois règles gardent un client progressif sain d'esprit :
- Chaque lot porte un état d'achèvement de la recherche dans son ensemble, pour que le client distingue « pas d'autres résultats pour l'instant » de « plus aucun résultat ».
- Les résultats sont fusionnés côté serveur sur une clé hôtel stable, et non simplement ajoutés. Le client ne devrait jamais avoir à deviner que deux cartes désignent le même bâtiment.
- Le tri par prix est provisoire tant que la recherche n'est pas terminée, et l'interface le dit. Les utilisateurs pardonnent une liste qui se stabilise ; ils ne pardonnent pas une étiquette « prix le plus bas » qui s'avère fausse.
Modéliser chambres et plans tarifaires sans que tout s'effondre
C'est ici que la plupart des intégrations hôtelières échouent en silence, et l'échec se manifeste des mois plus tard sous forme de ticket de support plutôt que de rapport de bug.
Le modèle tentant est plat : un hôtel possède une liste d'offres, chaque offre a un nom de chambre et un prix. Le rendu est joli. Puis un fournisseur renvoie « Deluxe King » et « Deluxe Room, 1 King Bed » pour ce qui est manifestement la même chambre, un autre renvoie le même nom pour deux chambres réellement différentes (l'une avec vue sur la ville, l'autre non), et un troisième renvoie un prix par nuit alors que tous les autres donnent un prix par séjour. Une liste plate ne peut pas vous dire laquelle de ces situations vous avez sous les yeux. Elle se contente de les afficher.
Un modèle qui résiste aux vrais fournisseurs compte au moins quatre niveaux, et il les garde séparés :
| Niveau | Ce qu'il contient | L'erreur à éviter |
|---|---|---|
| Hôtel | Votre propre identifiant stable, associé au code de chaque fournisseur | Utiliser l'identifiant hôtel d'un fournisseur comme clé primaire |
| Chambre | Occupation, configuration des lits, texte de chambre du fournisseur conservé tel quel | « Nettoyer » les noms de chambres jusqu'à ce que deux chambres différentes fusionnent |
| Plan tarifaire | Formule de repas, remboursabilité, mode de paiement, fournisseur d'origine | Traiter le petit-déjeuner ou la remboursabilité comme une partie du nom de chambre |
| Prix | Total du séjour, devise, taxes et frais inclus, et ceux payables sur place | Afficher un prix par nuit à côté de prix par séjour, ou masquer les frais payés à l'arrivée |
Vous pouvez contester l'emplacement des frontières — certaines équipes isolent l'occupation dans son propre niveau, ce qui se défend dès que vous vendez des réservations multi-chambres. Ce que vous ne pouvez pas faire, c'est fusionner des niveaux parce que l'interface n'en montre que deux. L'interface peut aplatir au moment du rendu. Les données, non.
Un détail mérite sa propre phrase : conservez la description brute de la chambre envoyée par le fournisseur à côté de tout ce que vous normalisez. Quand un client arrive et reçoit une autre chambre que celle de son voucher, la première question de tout le monde sera : qu'a réellement envoyé le fournisseur ?
Les conditions d'annulation sont des données, pas un paragraphe
Beaucoup de fournisseurs renvoient les conditions d'annulation en texte libre : « Annulation gratuite jusqu'à 3 jours avant l'arrivée, ensuite pénalité d'1 nuit. » La tentation est forte d'afficher cette chaîne et de passer à autre chose.
N'en faites rien. Un texte ne se compare pas, ne se trie pas, ne se filtre pas et ne s'applique pas. Votre utilisateur veut filtrer sur les tarifs remboursables. Votre service financier veut savoir quelles réservations deviennent non remboursables demain, pour que l'agence relance le client avant l'échéance. Votre parcours après réservation doit indiquer au client, au moment précis où il clique sur annuler, ce qui lui sera facturé. Rien de tout cela ne fonctionne sur une phrase.
Modélisez chaque condition comme une liste ordonnée de fenêtres de pénalité : de tel instant à tel instant, la pénalité est de ce montant (ou de cette part du séjour, ou de tant de nuits). Les bornes sont des horodatages avec fuseau horaire — celui de l'hôtel, pas celui de votre serveur ni celui de l'utilisateur — car « 3 jours avant l'arrivée » désigne un moment différent selon le minuit à partir duquel on compte. Stockez le texte original du fournisseur à côté de la version structurée, affichez la version structurée, et traitez tout écart entre les deux comme un sujet d'enquête plutôt que comme quelque chose à cacher.
Et revérifiez la condition au moment de la réservation, pas seulement à la recherche. Les conditions changent entre les deux appels plus souvent qu'on ne le croit.
Ce que coûte réellement une erreur
Une recherche lente vous coûte des conversions : c'est mauvais mais visible, quelqu'un finira par se plaindre. Les échecs coûteux sont les silencieux.
Un tarif affiché comme remboursable que le fournisseur traite comme non remboursable, c'est un litige avec un client muni d'une capture d'écran, et c'est généralement l'agence qui paie la pénalité. Un prix par nuit affiché comme total du séjour vend des chambres à perte jusqu'à ce que la comptabilité s'en aperçoive. Une chambre fusionnée avec une autre envoie une famille de quatre dans une chambre prévue pour deux. Des frais payables à l'hôtel jamais affichés transforment un avis cinq étoiles en rétrofacturation. Chacune de ces erreurs est une décision de modélisation prise au premier sprint, souvent sous l'étiquette « on nettoiera plus tard ».
Cache : ce que vous pouvez garder et ce que vous ne devez pas garder
Toute équipe qui intègre une API hôtelière finit par se demander si elle peut mettre les résultats en cache pour rendre la recherche plus rapide et moins chère. La réponse est oui, pour certaines choses, et la frontière entre elles compte plus que n'importe quel chiffre de performance.
Le contenu statique — noms d'hôtels, adresses, coordonnées, photos, listes d'équipements, descriptions de chambres — change rarement et c'est exactement ce que vous devez mettre en cache, généreusement, dans votre propre stockage. Vérifiez les conditions du fournisseur sur la manière de le stocker et de l'afficher ; certaines licences le restreignent. Le récupérer en direct à chaque recherche est lent sans aucun bénéfice.
Les tarifs et disponibilités en direct sont une autre affaire. Un prix en cache est une supposition sur ce que le fournisseur facturera, et les fournisseurs n'honorent pas vos suppositions. Un cache de courte durée des résultats peut être acceptable pour afficher une page — à condition que chaque parcours de réservation revérifie le prix auprès du fournisseur avant d'encaisser, et que l'interface traite un prix modifié comme un résultat normal et non comme une erreur. Certains fournisseurs limitent aussi le rapport entre recherches et réservations ; un cache agressif qui leur masque votre trafic réel n'est pas une faille sur laquelle compter.
Ce que vous ne devez jamais mettre en cache, c'est tout ce qui représente un engagement : un jeton de prix bloqué, une référence de réservation, un devis d'annulation. Ils appartiennent à un utilisateur et à un instant.
Avant de dire que c'est fini
Une courte vérification à passer sur votre propre intégration avant qu'elle ne porte de vraies réservations :
- La recherche renvoie un état d'achèvement, et le client se comporte différemment avant et après.
- Les hôtels sont indexés par votre propre identifiant, auquel le code de chaque fournisseur est associé.
- Chambre, plan tarifaire et prix sont des objets distincts dans vos données, quoi que montre l'écran.
- Chaque prix indique s'il est par nuit ou par séjour, et ce qui est payable à l'arrivée.
- Les conditions d'annulation sont stockées comme fenêtres de pénalité datées dans le fuseau de l'hôtel, avec le texte original conservé.
- Le parcours de réservation revérifie le prix et relit la condition avant de débiter qui que ce soit.
- Rien de ce qui représente un engagement n'est jamais servi depuis un cache.
Si vous hésitez entre construire tout cela fournisseur par fournisseur et partir d'une plateforme qui a déjà rencontré ces problèmes, le volet contractuel compte autant que le code — notre article sur les contrats de consolidateur hôtelier et les tarifs bedbank détaille ce qu'il faut demander. Nos propres API vols et hôtels s'ouvrent par une conversation plutôt que par une clé en libre-service ; si c'est la voie que vous voulez explorer, engagez cette conversation depuis la page des API voyage.
Le fan-out ne disparaît jamais. Un bon client cesse simplement de faire comme s'il n'existait pas.