Aller au contenu
Blog

Intégration d'API de réservation de vols : ce que la doc tait

Rédaction Tekravel
Rédigé avec l’aide de l’IA

Le ticket sur votre tableau dit simplement « ajouter les vols ». Vous avez déjà livré une intégration de paiement, un calcul de frais de port, peut-être une carte, et le modèle mental que vous apportez est l'évident : rechercher, afficher les résultats, encaisser la carte, terminé. Puis la première vraie réservation revient à un prix différent de celui de la page de résultats, la deuxième expire en timeout sans que personne puisse dire si le client a un siège, et quelqu'un des opérations demande pourquoi il existe une réservation mais pas de billet. Une intégration d'API de réservation de vols ressemble, vue de l'extérieur, à un tunnel de paiement e-commerce. En dessous, c'est une transaction distribuée contre des systèmes conçus bien avant REST, et la plupart des surprises viennent de cet écart.

Ce texte s'adresse au développeur qui n'a jamais vu de PNR. Il ne décrit pas les endpoints d'un fournisseur en particulier : les noms changent d'un fournisseur à l'autre, la forme ne change pas.

La séquence d'appels d'une intégration d'API de réservation de vols

Presque toutes les API aériennes, quel que soit le nom de leurs méthodes, suivent les mêmes quatre étapes. Placer correctement les frontières entre elles représente l'essentiel du travail.

ÉtapeCe qu'elle renvoieCe que vous devez stockerCe qui casse
RechercheDes itinéraires avec un prix et une clé d'offre ou de tarif opaqueRien de durable — les résultats périment viteVous traitez le prix comme définitif ; la clé expire avant le paiement
Cotation / vérificationLe prix confirmé, les règles tarifaires, les bagages, parfois des champs passager obligatoiresL'offre vérifiée et son expirationLe prix a changé ; la classe est complète ; les règles diffèrent de ce que vous avez affiché
RéservationUne réservation — le PNR — avec un code de réservation et une date limite d'émissionVotre propre référence, le code, la date limite, les données passagers exactement telles qu'envoyéesTimeout sans réponse ; PNR en double ; noms rejetés
ÉmissionLes numéros de billets électroniques ; c'est ici que l'argent est réellement engagéChaque numéro de billet, rattaché au passager et au segment concernésÉmission partielle ; réservation annulée par la compagnie parce que la date limite est passée

La ligne que l'on conteste, c'est la troisième, parce que beaucoup d'API permettent de réserver et d'émettre en un seul appel. Utilisez-le si vous voulez. Les deux restent pourtant distincts dans le monde des compagnies : un PNR peut exister sans billet, et l'émission peut échouer après la création du PNR. Un endpoint combiné cache seulement le moment où l'un a réussi et l'autre non ; votre modèle de données doit quand même prévoir cet état.

Notez aussi ce que la recherche ne renvoie pas : une promesse. C'est une annonce. La cotation est le devis, et seul le billet est la vente.

Pourquoi le prix recherché n'est pas le prix réservé

Un développeur web s'attend à un catalogue. L'inventaire aérien n'en est pas un. Un vol se vend par classes de réservation, chacune étant un panier de sièges à un tarif donné, et la compagnie ouvre et ferme ces paniers en continu à mesure que l'avion se remplit. Les résultats de recherche sont assemblés rapidement à partir de disponibilités qui peuvent déjà avoir un peu de retard ; le temps que l'utilisateur saisisse deux passeports, le panier le moins cher de ce vol peut avoir fermé. Quand la cotation s'exécute, elle redemande, et la réponse honnête est parfois plus élevée.

Les taxes ont leur propre dérive. Elles sont recalculées à la cotation pour les passagers et l'itinéraire exacts, et un enfant ou un bébé se tarife autrement que l'adulte supposé par la recherche. Si votre vitrine affiche une devise différente de celle du fournisseur — un fournisseur en USD pour un site en EUR, par exemple —, la conversion est un endroit de plus où le chiffre bouge.

La conséquence de conception est simple et souvent oubliée : ne débitez jamais sur le prix de recherche. Lancez la cotation avant le paiement, comparez, et si le montant a changé, affichez le nouveau chiffre et demandez. La marge que vous appliquez doit être recalculée sur le tarif recoté, pas reprise de la page de résultats — c'est la même logique que suit une agence pour définir sa stratégie de marge en ligne, et elle casse de la même façon quand la base bouge sous elle.

Idempotence, et ce que signifie un timeout pendant la réservation

C'est la section à lire deux fois.

Quand un appel de réservation expire, vous ne savez pas ce qui s'est passé. La requête n'est peut-être jamais arrivée. Elle est peut-être arrivée et a échoué. Ou — le cas qui fait mal — elle est arrivée, le fournisseur a créé le PNR auprès de la compagnie, et la réponse s'est perdue en revenant vers vous. Pour votre code, les trois cas sont identiques. Pour la compagnie, le troisième est une réservation active qui bloque des sièges au nom de votre client.

Le réflexe hérité des autres intégrations, c'est de réessayer. Ici, un nouvel essai à l'aveugle peut produire un second PNR pour les mêmes passagers sur le même vol. Les compagnies considèrent les réservations en double comme une infraction à leurs règles ; selon le transporteur et les accords de l'agence, la conséquence va de l'annulation automatique de l'une ou des deux réservations à une note de débit — une ADM — adressée à l'émetteur. L'agence qui la reçoit voudra savoir pourquoi votre système a réservé deux fois.

Ce qui fonctionne, à peu près dans cet ordre :

  • Créez votre propre référence de réservation avant l'appel sortant, persistez-la et envoyez-la avec la requête partout où l'API accepte une référence client. Si l'API gère une clé d'idempotence, utilisez-la ; sinon, votre référence reste ce qui vous permet de retrouver la réservation ensuite.
  • Modélisez explicitement l'état inconnu. En attente, confirmée, échouée — et inconnue. Un timeout fait passer la réservation à « inconnue », pas à « échouée ».
  • Levez l'inconnu en interrogeant, pas en répétant. Récupérez la réservation par votre référence, ou listez les réservations récentes de ces passagers, avant de décider de réessayer.
  • Faites tourner un job de rapprochement qui balaie tout ce qui reste inconnu, le compare avec ce que rapporte le fournisseur, et envoie ce qu'il ne peut pas trancher dans une file humaine plutôt que de deviner.

Les timeouts d'émission sont le même problème, avec de l'argent en plus. Si vous capturez la carte avant l'émission et que l'émission bloque, vous avez un client qui a payé et peut-être pas de billet. Si vous émettez avant la capture et que la capture échoue, vous avez émis un document que quelqu'un devra payer à la compagnie. La forme courante consiste à autoriser la carte, émettre, puis capturer en cas de succès — l'essentiel est de le décider délibérément, pas de le découvrir en production.

Les notions du voyage qui surprennent les développeurs web

Aucune n'est difficile. Chacune a coûté une semaine à quelqu'un qui ignorait son existence.

Un PNR n'est pas un billet

Le PNR est le dossier de réservation : passagers, segments, contacts, une date limite. Le billet est le document payé qui donne au passager le droit de voler. Un PNR non émis expire à sa date limite d'émission et les sièges sont remis en vente, parfois sans que vous le voyiez de votre côté.

Les noms sont presque immuables

Après l'émission, la plupart des tarifs n'autorisent pas de changement de nom au-delà d'une correction mineure, et ce qui compte comme mineur varie selon la compagnie. Le nom doit correspondre au document de voyage. Recueillez nom et prénoms séparément, ne laissez pas une civilité saisie librement se glisser dans un champ nom, et validez avant l'appel de réservation, pas après.

Les types de passagers sont tarifés, pas décoratifs

Adulte, enfant et bébé sont des types tarifaires, et l'âge qui décide lequel s'applique est généralement l'âge à la date du voyage, pas à la date de réservation. Un bébé sur les genoux n'occupe en général pas de siège et ne voyage qu'avec un adulte. Trompez-vous de type et la cotation échoue ou annonce le mauvais tarif.

Les heures sont locales, et un segment n'est pas un tronçon

Les heures de départ et d'arrivée sont données en heure locale de chaque aéroport. Ne les convertissez pas dans le fuseau de l'utilisateur pour l'affichage, et ne calculez pas une durée en les soustrayant sans les décalages. Un voyage contient des segments ; un segment avec escale technique contient plusieurs tronçons. Votre interface et vos données doivent s'accorder sur ce qu'est une « escale ».

Des choses arrivent après la vente

Les compagnies modifient leurs horaires après l'émission des billets. Une réservation correcte à l'émission peut afficher des semaines plus tard un nouvel horaire, un nouveau numéro de vol ou une correspondance rompue, et selon le fournisseur vous l'apprenez par une notification, une file d'attente ou en relisant la réservation. Prévoyez que la réservation change après que vous avez cessé de la regarder.

Un void n'est pas un remboursement

Peu après l'émission, il existe généralement une fenêtre pendant laquelle un billet peut être annulé (void) comme s'il n'avait jamais existé. Après cette fenêtre, seul un remboursement selon les règles tarifaires est possible, avec parfois une pénalité, ou rien du tout en retour. La fenêtre et ses règles appartiennent au fournisseur et à l'accord d'émission ; lisez-les avant de construire un bouton « annuler ».

Ce que coûte une erreur

Les défaillances d'une intégration aérienne coûtent cher d'une manière précise : elles retombent sur des personnes, pas dans des logs. Une réservation en double devient un appel à la compagnie et peut-être une note de débit sur le compte de l'agence. Un client débité sans billet devient un remboursement, une réclamation et un risque d'impayé. Un billet émis sans paiement abouti devient une dette envers la compagnie que quelqu'un doit régler. Un changement d'horaire que personne n'a traité devient un voyageur à l'aéroport pour un vol parti plus tôt.

Rien de tout cela n'apparaît dans un test du chemin nominal. Écrivez d'abord les chemins d'échec : le timeout pendant la réservation, le prix qui a monté, le billet qui échoue après le PNR, le void après un paiement réussi. Si ceux-là sont traités, le chemin nominal est la partie facile.

Tester contre une API aérienne

Les environnements de test des fournisseurs sont utiles et incomplets. Ils sont souvent plus calmes que la production, si bien que classes complètes et changements de prix y sont plus rares, et certains ne simulent pas du tout les timeouts. Servez-vous-en pour la forme des appels et les erreurs de validation, puis planifiez un essai contrôlé en production avec de vraies réservations que vous annulez dans la fenêtre de void — en prévenant les opérations.

Intégrer ou non est une autre question. Si ce dont vous avez réellement besoin est une vitrine plutôt qu'un inventaire brut dans votre propre système, l'arbitrage est détaillé dans marque blanche ou moteur de réservation maison, et le même raisonnement vaut pour un portail B2B pour sous-agents. Si vous voulez l'inventaire dans votre propre code, cette plateforme expose des API vols et hôtels, et l'accès commence par une conversation sur votre cas d'usage plutôt que par une clé en libre-service — c'est aussi le bon moment pour poser chacune des questions ci-dessus.

Rédaction Tekravel

Desk technologies du voyage

Le desk technologies du voyage de Tekravel écrit pour les professionnels : dirigeants d'agences, consolidateurs et développeurs qui les intègrent. Chaque article est vérifié sur la plateforme qu'il décrit avant publication.