Gestion des erreurs d'API de moteur de réservation : trois pannes qui coûtent cher

Le ticket de support tombe un jeudi soir. Un client a payé, la page a tourné, puis une erreur générique s'est affichée. La carte a été débitée. Vos logs montrent un POST vers le fournisseur qui n'a jamais reçu de réponse. La compagnie a-t-elle bloqué un siège ? Personne ne peut le dire, et le client attend. Une bonne gestion des erreurs d'API de moteur de réservation consiste surtout à ne jamais se retrouver dans cette situation, ou au moins à savoir exactement quoi faire quand on y est.
La plupart des guides d'intégration traitent les erreurs comme un catalogue de codes de statut. En réservation, les codes sont la partie facile. Ce qui coûte de l'argent, c'est un petit nombre de situations où la requête semble avoir échoué alors que le monde a changé quand même, ou semble avoir réussi alors que rien n'a changé. Trois d'entre elles comptent plus que les autres.
Première panne : le prix a bougé entre la recherche et la réservation
Un résultat de recherche est un devis, pas un contrat. Les tarifs sont mis en cache, l'inventaire est partagé entre tous les canaux du fournisseur, et le montant affiché il y a quelques minutes peut déjà être périmé. Le fournisseur vous le dit à l'étape de création, parfois par une réponse nette « tarif modifié », parfois en renvoyant discrètement un autre total dans une réponse par ailleurs réussie.
La seconde variante est la dangereuse. Si votre code lit la confirmation, enregistre la réservation et débite le client du montant qu'il a vu, la différence sort de votre marge, ou plus tard d'un ADM. La règle est donc simple : comparez le total confirmé par le fournisseur avec le total accepté par le client, à chaque fois, dans le code, avant de capturer le paiement.
Que faire en cas d'écart dépend de son ampleur et de qui le supporte. Quelques centimes d'arrondi entre devises, c'est une tolérance que l'on fixe une fois. Tout ce qui dépasse retourne au client avec un nouveau prix et un bouton d'acceptation explicite. Ne l'absorbez jamais automatiquement, ne le facturez jamais automatiquement.
Deuxième panne : réservé, mais pas émis
Un PNR existant n'est pas un billet existant. Beaucoup de parcours créent d'abord la réservation, puis émettent l'e-ticket dans une étape distincte, avec un délai limite entre les deux. Si le paiement passe et que l'émission échoue, vous détenez l'argent d'un client et une réservation qui expirera à sa propre heure.
Cet échec est rarement bruyant. L'appel d'émission renvoie une erreur ou un délai dépassé, et la réservation reste dans un état que votre base appelle « payé » alors que le fournisseur dit encore « bloqué ». Pendant ce temps, le délai d'émission court, et contrairement à votre file de support, la compagnie n'attend pas.
Traitez-le comme un état à part entière, pas comme une variante du succès ou de l'échec. Une réservation a besoin au minimum de ceux-ci : créée, bloquée, paiement capturé, en cours d'émission, émise, échouée et remboursable. L'état « paiement capturé, en cours d'émission » demande un minuteur : si une réservation y reste trop longtemps, une tâche doit relire la réservation chez le fournisseur et trancher, sans attendre qu'un humain s'en aperçoive. La décision est peu coûteuse quand vous connaissez le délai du fournisseur, car il vous dit combien de temps réessayer sans risque avant de rembourser.
Troisième panne : le délai dépassé à l'issue inconnue
C'est le ticket du jeudi soir. Votre requête est partie ; aucune réponse n'est revenue ; la connexion est tombée ou la passerelle a abandonné. Le fournisseur a pu la traiter entièrement, en partie, ou pas du tout.
La tentation est de réessayer. Ne rejouez pas un appel de création à l'aveugle : la seconde tentative peut produire une seconde réservation, et un doublon a un vrai coût : deux sièges bloqués, peut-être deux billets émis, un litige de remboursement sur l'un d'eux.
L'ordre sûr : arrêter, lire, décider. Arrêtez le parcours client sur un état honnête du type « nous confirmons votre réservation ». Lisez le côté fournisseur en recherchant la réservation avec la référence que vous avez générée avant l'appel (c'est pourquoi vous créez d'abord votre propre référence client, et la transmettez si le fournisseur l'accepte). Seulement ensuite, décidez : trouvée, on continue depuis l'état réel ; introuvable après la fenêtre de traitement du fournisseur, on peut réessayer une fois sans risque.
Si le fournisseur ne permet pas de chercher par votre référence, cherchez par nom du passager, itinéraire et date dans une fenêtre étroite, et considérez une correspondance comme « trouvée ». Moche, mais bien moins cher qu'un doublon.
Un tableau de décision que vous pouvez contester
| Ce que vous voyez | Ce que vous savez | Ce qu'il faut faire | Ce qu'il ne faut pas faire |
|---|---|---|---|
| Le fournisseur renvoie « tarif modifié » | Rien n'a été réservé | Afficher le nouveau total, demander l'accord, relancer la création | Renvoyer l'ancien prix en espérant que ça passe |
| Succès, mais total différent de celui accepté | Une réservation existe au nouveau prix | Suspendre le paiement, demander au client, annuler s'il refuse | Capturer l'ancien montant et absorber l'écart |
| Paiement capturé, l'émission échoue | Un PNR existe, statut du billet inconnu | Relire la réservation, réessayer l'émission dans le délai, rembourser après | Marquer la réservation en échec et oublier le PNR |
| Délai dépassé à la création | Issue inconnue | Chercher par votre référence, puis poursuivre ou réessayer une fois | Réessayer aussitôt à l'aveugle |
| Délai dépassé à l'annulation | Vous pouvez rester redevable du segment | Relire le statut avant de dire quoi que ce soit au client | Afficher « annulé » parce que le clic a eu lieu |
Une ligne discutable : certaines équipes remboursent dès la première erreur d'émission pour calmer le client. C'est défendable sur un petit billet, une mauvaise habitude sur un cher, car on peut perdre un tarif qu'une minute de plus aurait sauvé.
Ce que ça vous coûte de se tromper
Chaque panne a sa facture. Un changement de prix manqué, c'est de la marge perdue sur chaque réservation touchée, souvent découverte seulement au rapprochement. Un cas réservé-non-émis, c'est un client qui arrive à l'aéroport avec une réservation périmée et un débit sur sa carte : une contestation de paiement et un problème de réputation à la fois. Un réessai aveugle après délai dépassé, c'est un doublon, et les compagnies auditent les doublons ; une série finit en ADM.
Rien de tout cela n'est exotique. C'est la plomberie sans éclat qui sépare une démo d'un système que l'on peut laisser tourner tout un week-end.
Construisez la tâche de rapprochement avant d'en avoir besoin
Les trois pannes finissent pareil : votre base et celle du fournisseur divergent. Écrivez donc la tâche qui les compare avant le premier incident, pas après. Un passage de nuit est le minimum ; toutes les quelques minutes pour tout ce qui est dans un état transitoire, c'est mieux. Elle liste les réservations bloquées en « bloquée », « en émission » ou « inconnue », demande au fournisseur son avis, puis répare l'enregistrement ou ouvre un ticket avec les preuves jointes.
Conservez chaque requête et réponse des appels de réservation, délais dépassés compris, avec la référence envoyée. Quand un client conteste un débit, ce journal est votre argument. Il garde aussi honnête la discussion sur la latence : voyez ce que vous pouvez et ne pouvez pas corriger dans la latence d'une API pour comprendre pourquoi les délais dépassés sont une réalité et non un bug à éliminer.
Si vous hésitez encore sur le câblage de la connexion fournisseur elle-même, le guide intégration d'API de réservation de vols couvre l'ordre des appels que suppose cet article. Et pour discuter de la correspondance de ces états avec nos API vols et hôtels, l'accès commence par une conversation : voir la page des API de voyage.