Fiabilité des intégrations
Observabilité des API voyage : retrouver chaque réservation de bout en bout
Une API peut répondre rapidement tout en laissant un dossier incomplet. La bonne mesure relie la recherche, le prix, le paiement, la commande fournisseur, la confirmation et les corrections ultérieures.
Réponse directe
Définir d’abord ce qu’est une réservation aboutie
Une réservation n’est pas terminée parce que l’écran affiche « merci ». Selon le produit, elle doit posséder un prix accepté, une transaction de paiement cohérente, une référence chez le fournisseur, un état exploitable par l’équipe après-vente et un message remis au voyageur. Écrivez ces critères avant de choisir vos tableaux de bord. Ils permettent de distinguer panne technique, refus normal et commande dont le résultat reste inconnu.
Attribuez un identifiant de corrélation à chaque tentative et rattachez-lui les références de recherche, devis, paiement, commande et fournisseur. La traduction entre identifiants doit survivre aux changements de système. Masquez les données personnelles inutiles dans les journaux et prévoyez un accès limité aux personnes chargées du diagnostic.
Relier traces, métriques et journaux
Une trace aide à suivre un appel entre composants ; une métrique montre la fréquence ou la durée d’un phénomène ; un journal décrit un événement précis. Ces trois signaux répondent à des questions différentes. La documentation OpenTelemetry sur les signaux donne un vocabulaire commun pour les instrumenter sans confondre un détail de requête et un indicateur de service.
| Étape | Mesure à suivre | Preuve à retrouver |
|---|---|---|
| Recherche et prix | Latence, réponse vide, écart au prix final | Offre, devise, conditions et heure de validité |
| Commande | Succès, refus, délai, résultat inconnu | Identifiant interne et référence fournisseur |
| Paiement | Autorisation, capture, rejet, remboursement | Lien univoque avec la commande concernée |
| Confirmation | Temps jusqu’au document voyageur | Statut final et message effectivement envoyé |
| Après-vente | Modification, annulation, incident ouvert | Historique des versions et responsable du traitement |
Alerter sur une conséquence métier
Une hausse des erreurs HTTP doit être visible, mais l’alerte prioritaire porte sur les dossiers affectés : paiement accepté sans confirmation, réservation fournisseur sans paiement rapproché, prix expiré après engagement client ou modification non répercutée. Définissez pour chaque signal le seuil, la fenêtre de mesure, l’équipe destinataire et l’action possible. Une alerte qui ne mène à aucune action finit par être ignorée.
Segmentez au moins par fournisseur, produit, pays et version d’intégration. Un taux global rassurant peut masquer une panne limitée à un transporteur ou à une devise. Présentez toujours le dénominateur : trois échecs sur quatre ventes et trois sur dix mille n’appellent pas la même réponse.
Traiter avec prudence les tentatives répétées
La sémantique HTTP distingue les méthodes idempotentes des actions qui ne peuvent pas être répétées aveuglément. Dans la réservation, la question pratique est plus large : le fournisseur reconnaît-il une clé de dédoublonnage et sait-on interroger l’état d’une création dont la réponse s’est perdue ? Si ce n’est pas établi, une relance automatique peut doubler une commande.
- Conserver la tentative et sa référence avant l’appel externe.
- En cas de réponse incertaine, rechercher le dossier côté fournisseur et côté paiement.
- Ne relancer que selon une règle documentée et testée avec le partenaire.
- Envoyer les cas ambigus dans une file de traitement humain avec le contexte complet.
Une recette qui révèle les angles morts
Rejouez une vente normale, un tarif expiré, une réponse lente du fournisseur, une coupure après paiement et une annulation partielle. Pour chaque scénario, notez ce que voit le voyageur, ce que reçoit le conseiller et ce que les équipes retrouvent dans les outils. Testez aussi la désactivation d’un fournisseur et le retour à un mode de vente assisté.
Une personne qui n’a pas participé au développement doit pouvoir retrouver l’état et le responsable d’un dossier à partir d’une seule référence, sans interroger plusieurs équipes au hasard.
Complétez ce guide par la procédure d’incident et par les questions de réversibilité d’un fournisseur.
Relier les alertes aux limites et à l’intention de l’appel
Un pic d’erreurs doit être lu avec les opérations qui l’ont produit. Une recherche répétée par plusieurs clients et une création de commande sans réponse n’appellent pas la même décision. Le tableau de suivi associe source, opération, quota connu, référence de tentative et résultat retrouvé, avec un circuit de traitement des demandes incertaines.
Ajoutez aux alertes un plafond de reprise et une règle d’arrêt. Le volume global de réponses 429 ne permet pas de conclure à une rupture complète du fournisseur : le périmètre peut dépendre de l’opération ou du compte. Le guide des reprises détaille les branches de traitement et leur recette. Consultez le Erreurs HTTP et limites API : organiser la reprise du voyage.
Attribuer une question métier à chaque signal observé
OpenTelemetry distingue notamment traces, mesures et journaux. Dans une recette voyage, reliez une trace au passage entre composants, une mesure au volume ou au délai, et un journal à un événement précis. Un taux de réponses réussies ne confirme pas que les voyageurs ont reçu leurs documents. Définissez une question et une preuve attendue pour chaque signal avant de déclarer le parcours suivi.
OpenTelemetry : signaux de télémétrie — référence consultée le 10/10/2026 ; portée précisée dans les sources du guide.
Relier le délai au segment observé
Scénario fictif : Le tableau présente un délai fournisseur alors que sa mesure englobe une file d’attente locale. Faites rapprocher les bornes de mesure et les composants couverts.
| Point | Preuve | Contrôle proposé |
|---|---|---|
| Contrat à conserver | Début, fin et segment | Faire préciser ce qui est fourni et ce que le traitement peut conclure. |
| Résultat à rapprocher | Délai interprété avec ses limites | Comparer le résultat effectivement observé à celui attendu pour ce cas. |
| Décision de reprise | Le diagnostic ne transfère pas sans preuve toute la lenteur au partenaire. | Attribuer la suite et garder l’inconnue visible tant que la preuve manque. |
Le diagnostic ne transfère pas sans preuve toute la lenteur au partenaire.
Cadre documentaire : W3C : Trace Context, recommandation — référence consultée le . Contexte de traçage distribué ; ne remplace ni référence de réservation, ni état métier, ni preuve complète de traitement.
Approfondir le parcours : Dépendances du parcours : service observé, responsable et effet métier
L’observabilité doit garder le parcours qu’elle permet réellement de voir. Une carte de composants issue de la recherche ne couvre pas nécessairement confirmation et reprise. Les dépendances non observées restent à rapprocher avec le besoin métier et la documentation.
Dépendances du parcours : service observé, responsable et effet métier · Rapprocher les preuves du parcours
Lecture de métriques · trafic fictif
125 réponses HTTP 200 ne représentent pas 125 réservations.
Une cohorte fictive contient cent intentions de réservation distinctes. Les créations, vérifications de statut et reprises produisent cent trente appels. Cinq appels ne reçoivent pas de réponse exploitable à l’échéance de mesure ; les cent vingt-cinq autres reçoivent HTTP 200. L’état de chaque dossier est ensuite rapproché séparément.
- 100 intentions distinctesLe dénominateur métier conserve chaque demande une seule fois.
- 130 appelsLes consultations de statut et tentatives supplémentaires restent des appels.
- 95 dossiers confirmésTrois restent incertains et deux sont refusés à l’échéance retenue.
| Mesure | Calcul dans l’exercice | Lecture |
|---|---|---|
| Appels ayant reçu HTTP 200 | 125 ÷ 130 ≈ 96,15 % | Une mesure au niveau des appels, incluant les consultations d’état. |
| Intentions avec confirmation retrouvée | 95 ÷ 100 = 95 % | Une mesure au niveau des intentions distinctes, à l’échéance convenue. |
| Dossiers encore incertains | 3 ÷ 100 = 3 % | Des dossiers à rapprocher avant de conclure à un succès ou à un échec. |
| Dossiers refusés | 2 ÷ 100 = 2 % | Une issue métier à expliquer, distincte d’un défaut de réponse HTTP. |
Lire l’état renvoyé et retrouver la référence fournisseur.
Dans l’interface fictive de cet exemple, une consultation d’état peut réussir en HTTP tout en indiquant un dossier en attente ou refusé. La réussite de la requête ne remplace donc pas la vérification du résultat de la réservation. Compter chaque réponse 200 comme une vente compterait aussi plusieurs fois certains dossiers.
Quelles références relier dans les traces ?
L’identifiant d’intention, les identifiants des appels, l’opération exécutée, la référence fournisseur lorsqu’elle existe et les transitions d’état. Conservez la chronologie et l’échéance de mesure. Un même dossier peut produire plusieurs traces sans représenter plusieurs ventes.
Que faire d’un dossier sans réponse exploitable ?
Rechercher son état par le circuit prévu et attribuer la prochaine action. Vérifiez les règles de reprise de l’opération avant une nouvelle tentative de création. Une réponse perdue peut laisser l’état métier incertain ; une nouvelle création ne doit pas être utilisée comme une simple vérification de statut.
Référence technique : RFC 9110, section 15.3.1, HTTP 200, consultée le 15 octobre 2026. Le code décrit le succès de la requête ; le modèle de réservation, les états et les chiffres présentés ici sont fictifs.
Définir les indicateurs métier · Suivre les dossiers encore ouverts.
Duffel : identifier et vérifier les notifications aériennes
Le guide distingue configuration, contrôle cryptographique et unicité du traitement. Ces trois points ne se remplacent pas mutuellement.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Changement compagnie | order.airline_initiated_change_detected signale un changement initié par la compagnie. | Relire la commande et qualifier les conséquences pour les voyageurs ; la notification ne vaut pas accord du client. |
| Signature | Le contrôle emploie X-Duffel-Signature et un secret ; ce secret n’est montré qu’à la création du webhook. | Prévoir stockage protégé et rotation sans écrire le secret dans les journaux. |
| Doublons | Duffel indique d’utiliser idempotency_key pour l’unicité des événements rejoués. | Ne pas inventer une clé de dédoublonnage à partir de la date de réception. |
| Environnements | Webhooks test et production sont séparés ; live_mode permet de les distinguer. | Ne pas compter un ping de connectivité comme une réservation réelle traitée. |
Comportement décrit par Duffel, à ne pas généraliser aux webhooks de tous les fournisseurs.
Duffel — Receiving webhooks · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Trace Context : formats des identifiants et portée du suivi
La version 00 de traceparent distingue l’identité de la trace complète et celle du segment parent. Le format permet le rapprochement technique sans remplacer l’identifiant métier du dossier.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| trace-id | 32 caractères hexadécimaux minuscules, correspondant à 16 octets ; la valeur entièrement nulle est interdite. | Rejeter un contexte invalide sans le traiter comme une preuve de continuité. |
| parent-id | 16 caractères hexadécimaux minuscules, soit 8 octets ; la valeur entièrement nulle est également interdite. | Suivre les changements de segment sans créer artificiellement un nouveau dossier commercial. |
| Confidentialité | Les en-têtes de contexte ne doivent pas transporter d’informations permettant d’identifier une personne. | Garder coordonnées client, jetons et contenu sensible hors du contexte propagé. |
Une trace retrouvée atteste un chemin technique observé, sans démontrer à elle seule l’acceptation ou l’émission d’une réservation.
W3C — Trace Context, recommandation du 23 novembre 2021 · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Postmark : un code d’erreur peut arrêter les notifications
La réponse du point de réception détermine si Postmark retentera de transmettre un événement sortant.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Nouvelle tentative | Les erreurs 5xx, 408, 429 et les échecs réseau donnent lieu à des reprises. | Conserver l’événement et surveiller la récupération du service. |
| Arrêt de l’événement | Les autres erreurs 4xx, dont 401, 403, 404 et 422, ne sont pas retentées. | Ne pas compter sur une nouvelle tentative automatique après une erreur d’authentification ou une URL incorrecte. |
| Accusé de réception | Postmark demande une réponse 200 après traitement ou remise à une file durable. | Distinguer réception technique, sauvegarde durable et traitement métier. |
| Vérification | Une défaillance persistante peut suspendre un type d’événement jusqu’à correction et nouvelle vérification. | Contrôler les statuts Delivery et Bounce séparément ; une catégorie qui fonctionne ne prouve pas que l’autre fonctionne. |
| Authentification | Postmark ne fournit pas de signature HMAC ; sa documentation recommande HTTP Basic Authentication en HTTPS et un filtrage des adresses IP. | Contrôler le mécanisme du fournisseur, puis la structure du message, au lieu d’attendre un en-tête de signature inexistant. |
Comportement des webhooks sortants Postmark ; les messages entrants utilisent une infrastructure distincte.
Postmark — Webhooks overview, retry attempts · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Historique Expedia Rapid : une correction de nom ne crée pas forcément un nouvel événement
L’historique de l’itinéraire aide à relire les changements, mais il ne constitue pas une copie immuable de chaque état intermédiaire.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Demande d’historique | Retrieve avec include=history ajoute les historiques par chambre ; itinerary_history décrit aussi les ajustements d’itinéraire des agents Expedia Group. | Rattachez chaque événement à son niveau et à la chambre concernée. |
| Changements avec effet financier | Plusieurs changements appliqués dans un même parcours produisent un seul événement modified ; des parcours successifs en produisent plusieurs. | Ne comptez pas les champs modifiés en comptant seulement les événements. |
| Corrections sans effet financier | Une correction de nom, de préférence fumeur ou de demande spéciale est intégrée au dernier événement, sans nouveau modified. | L’absence de nouvel événement ne démontre pas que la correction a échoué. |
| Valeur relue dans un ancien événement | Après une modification de demande spéciale, l’événement created existant peut présenter la nouvelle valeur. | Pour comparer deux états reçus, conservez les réponses utiles avec leur date dans un suivi adapté. |
Deux historiques qui demandent une lecture par champ
Événements et modifications fictifs.
La demande spéciale a changé sans nouvel événement
Un dossier fictif passe d’une demande de chambre calme à une demande de rez-de-chaussée ; seul created reste présent dans l’historique.
Événement présent : created
special_request relu : rez-de-chaussée
Nouvel événement modified : absentLecture du cas. Vérifiez la valeur actuelle et la réponse de modification. Le nombre d’événements ne démontre pas l’échec ; la demande spéciale ne prouve pas non plus son acceptation par l’hôtel.
Deux changements sont comptés comme une seule modification de champ
Un parcours fictif modifie les dates et l’occupation ensemble ; l’historique ajoute un modified.
Changements demandés : dates et occupation
Parcours d’application : 1
Événement modified ajouté : 1Lecture du cas. Relisez les deux champs dans l’état retourné. Un événement peut regrouper plusieurs changements ; son nombre ne décrit pas la liste complète des valeurs touchées.
Documentation Expedia Rapid consultée le 31 octobre 2026. Distinguez l’historique métier du fournisseur, l’état courant et les traces conservées par votre intégration. Ne stockez pas plus de données de voyageurs que nécessaire au suivi.
Expedia Group Rapid — Itinerary history · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Disponibilité : comparer une durée et un volume de requêtes
Avant de comparer deux engagements, nommez le service rendu : rechercher une offre, créer une commande ou retrouver un billet. Une sonde qui répond ne décrit pas toutes ces opérations.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Indicateur et cible | Le SLI décrit une mesure ; le SLO en fixe l’objectif. Le SLA ajoute un cadre contractuel. | Conserver séparément résultat observé, objectif interne et clause applicable au fournisseur. |
| Budget d’erreur | Le budget est la part complémentaire de la cible : 100 % moins le SLO. | Appliquer cette part au même dénominateur : minutes ou requêtes éligibles, sans convertir directement les unes en autres. |
| Fenêtre de mesure | Une fenêtre glissante et une période calendaire ne regroupent pas les mêmes événements. | Dater le début et la fin, préciser le fuseau et conserver la définition des exclusions. |
Du service rendu à la décision
Les quatre éléments se documentent ensemble avant de comparer un pourcentage.
- Tâche
Définir le résultat attendu : confirmation et référence retrouvables.
- Population
Compter les opérations éligibles, sur la même période.
- Mesure
Identifier les échecs observés et les données manquantes.
- Décision
Attribuer la correction et le suivi des dossiers affectés.
Un même incident, deux lectures
Exemple fictif sans mesure de fournisseur : un mois conventionnel de 30 jours, une interruption de 30 minutes et 250 requêtes échouées sur 100 000.
La cible de 99,9 % est-elle tenue ?
Le temps et les requêtes constituent ici deux mesures indépendantes du même scénario.
Temps : 43 200 minutes, dont 30 indisponibles
Disponibilité temporelle : environ 99,930556 %
Requêtes : 99 750 réussites sur 100 000
Réussite des requêtes : 99,75 %Lecture du cas. La cible temporelle est tenue (budget de 43,2 minutes), celle des requêtes est dépassée (budget de 100 échecs). La concentration du trafic pendant la panne explique cette différence ; une mesure ne remplace pas l’autre.
Le cas utilise un mois de 30 × 24 heures, sans exclusion. Il ne calcule aucun avoir contractuel et ne suppose aucune indépendance entre fournisseurs. Les dossiers affectés restent à traiter même si la cible globale est tenue.
Google SRE Workbook — Implementing SLOs · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Sources et périmètre des faits documentés
La date de consultation figure avec chaque référence. Les méthodes d’essai et recommandations de ce guide sont éditoriales ; les conditions d’accès et d’usage se vérifient dans la documentation actuelle.
- OpenTelemetry : signaux de télémétrie : Rôle des traces, mesures et journaux ; aucune garantie de disponibilité d’une API fournisseur. (consultée le )
- W3C : Trace Context, recommandation : Contexte de traçage distribué ; ne remplace ni référence de réservation, ni état métier, ni preuve complète de traitement. (consultée le )
- RFC 9110 — HTTP Semantics, 200 OK : Sémantique du statut HTTP 200 ; les états et chiffres de réservation de l’exercice sont fictifs. (consultée le )
- Duffel — Receiving webhooks : Comportement décrit par Duffel, à ne pas généraliser aux webhooks de tous les fournisseurs. (consultée le )
- W3C — Trace Context, recommandation du 23 novembre 2021 : Une trace retrouvée atteste un chemin technique observé, sans démontrer à elle seule l’acceptation ou l’émission d’une réservation. (consultée le )
- Postmark — Webhooks overview, retry attempts : Comportement des webhooks sortants Postmark ; les messages entrants utilisent une infrastructure distincte. (consultée le )
- Expedia Group Rapid — Itinerary history : Documentation Expedia Rapid consultée le 31 octobre 2026. Distinguez l’historique métier du fournisseur, l’état courant et les traces conservées par votre intégration. Ne stockez pas plus de données de voyageurs que nécessaire au suivi. (consultée le )
- Google SRE Workbook — Implementing SLOs : Le cas utilise un mois de 30 × 24 heures, sans exclusion. Il ne calcule aucun avoir contractuel et ne suppose aucune indépendance entre fournisseurs. Les dossiers affectés restent à traiter même si la cible globale est tenue. (consultée le )
Questions fréquentes
Questions utiles avant de décider
Un taux de disponibilité de l’API suffit-il ?
Non. Il faut aussi mesurer le parcours complet : prix confirmé, paiement rapproché, référence fournisseur obtenue et document remis au voyageur. Une réponse HTTP réussie peut précéder un échec métier.
Peut-on relancer automatiquement une création de réservation ?
Seulement si le contrat d’API et votre mécanisme de dédoublonnage garantissent le résultat attendu. Une création répétée peut produire deux dossiers ou deux encaissements. Commencez par rechercher l’état de la première tentative.
Quelles données conserver dans les journaux ?
Conservez les références, étapes, horodatages et codes utiles au diagnostic, avec un contrôle d’accès et une durée adaptés. Évitez d’y recopier cartes de paiement, documents voyageurs et autres données non nécessaires.
Pourquoi distinguer recherche et création dans le suivi d’erreurs ?
Une recherche limitée ne produit pas le même risque qu’une commande dont le résultat manque. Le suivi doit permettre de décider attente, correction, lecture du dossier ou intervention avant toute répétition.
Relier le délai au segment observé : quelle preuve conserver ?
Conservez début, fin et segment, délai interprété avec ses limites et la décision attribuée. Le diagnostic ne transfère pas sans preuve toute la lenteur au partenaire.
L’absence d’un nouvel événement modified dans Expedia Rapid prouve-t-elle qu’une correction de nom a échoué ?
Non. Les changements sans effet financier, comme le nom ou la demande spéciale, sont intégrés au dernier événement existant. Vérifiez la valeur relue et la réponse de l’opération, plutôt que le seul nombre d’événements.
