Flugbuchungs-API-Integration: was die Doku verschweigt

Auf dem Ticket im Board steht nur: „Flüge einbauen". Sie haben schon eine Zahlungsanbindung ausgeliefert, vielleicht Versandkosten oder Karten, und das mentale Modell ist das naheliegende: suchen, Ergebnisse zeigen, Karte belasten, fertig. Dann kommt die erste echte Buchung zu einem anderen Preis zurück als auf der Ergebnisseite, die zweite läuft in einen Timeout und niemand kann sagen, ob der Kunde einen Sitz hat, und aus dem Operations-Team fragt jemand, warum es eine Reservierung gibt, aber kein Ticket. Eine Flugbuchungs-API-Integration sieht von außen aus wie ein E-Commerce-Checkout. Darunter ist sie eine verteilte Transaktion gegen Systeme, die lange vor REST entworfen wurden, und die meisten Überraschungen entstehen genau in dieser Lücke.
Dieser Text richtet sich an Entwickler, die noch nie einen PNR gesehen haben. Er beschreibt nicht die Endpunkte eines bestimmten Anbieters; die Namen ändern sich von Anbieter zu Anbieter, die Form nicht.
Die Aufrufkette einer Flugbuchungs-API-Integration
Fast jede Flug-API folgt, wie auch immer sie ihre Methoden nennt, denselben vier Schritten. Die Grenzen zwischen ihnen richtig zu ziehen, ist der größte Teil der Arbeit.
| Schritt | Was er liefert | Was Sie speichern müssen | Was schiefgeht |
|---|---|---|---|
| Suche | Reiseverläufe mit Preis und einem undurchsichtigen Angebots- oder Tarifschlüssel | Nichts Dauerhaftes — Ergebnisse veralten schnell | Sie behandeln den Preis als endgültig; der Schlüssel verfällt vor dem Checkout |
| Preisprüfung | Den bestätigten Preis, Tarifbestimmungen, Gepäck, manchmal Pflichtfelder für Reisende | Das geprüfte Angebot und sein Ablaufzeitpunkt | Preis geändert; Klasse ausgebucht; Bestimmungen weichen von der Anzeige ab |
| Buchung | Eine Reservierung — den PNR — mit Buchungscode und Ticketing-Frist | Ihre eigene Referenz, den Code, die Frist, die Reisendendaten exakt wie gesendet | Timeout ohne Antwort; doppelte PNRs; abgelehnte Namen |
| Ticketing | Ausgestellte E-Ticket-Nummern; erst hier wird tatsächlich Geld gebunden | Jede Ticketnummer, zugeordnet zu Reisendem und Segment | Teilausstellung; Reservierung von der Airline storniert, weil die Frist verstrichen ist |
Über die dritte Zeile wird gestritten, weil viele APIs Buchung und Ticketing in einem Aufruf erlauben. Nutzen Sie das ruhig. In der Welt der Airlines bleiben beide trotzdem getrennt: Ein PNR kann ohne Ticket existieren, und das Ticketing kann scheitern, nachdem der PNR angelegt wurde. Ein kombinierter Endpunkt versteckt nur den Moment, in dem das eine gelang und das andere nicht — Ihr Datenmodell braucht für diesen Zustand trotzdem einen Platz.
Beachten Sie auch, was die Suche nicht liefert: ein Versprechen. Sie ist eine Anzeige. Die Preisprüfung ist das Angebot, und erst das Ticket ist der Verkauf.
Warum der gesuchte Preis nicht der gebuchte ist
Webentwickler erwarten einen Katalog. Airline-Inventar ist keiner. Ein Flug wird in Buchungsklassen verkauft, jede ein Kontingent an Sitzen zu einem Tarif, und die Airline öffnet und schließt diese Kontingente laufend, während sich die Maschine füllt. Suchergebnisse werden schnell aus Verfügbarkeiten zusammengesetzt, die schon leicht hinterherhinken können; bis ein Nutzer zwei Reisepässe eingetippt hat, kann das günstigste Kontingent auf diesem Flug geschlossen sein. Die Preisprüfung fragt neu, und die ehrliche Antwort ist manchmal höher.
Steuern haben ihre eigene Drift. Sie werden bei der Preisprüfung für genau diese Reisenden und diese Strecke neu berechnet, und ein Kind oder Kleinkind wird anders bepreist als der Erwachsene, den die Suche angenommen hat. Zeigt Ihr Shop eine andere Währung als die, in der der Anbieter quotiert — etwa EUR auf der Seite, USD beim Anbieter —, ist die Umrechnung eine weitere Stelle, an der sich die Zahl bewegt.
Die Designfolge ist einfach und wird oft übersprungen: Belasten Sie nie auf Basis des Suchpreises. Führen Sie die Preisprüfung vor der Zahlung aus, vergleichen Sie, und wenn sich der Betrag geändert hat, zeigen Sie die neue Zahl und fragen nach. Ihr Aufschlag muss auf den neu bepreisten Tarif berechnet werden, nicht von der Ergebnisseite übernommen — es ist dieselbe Logik, die ein Reisebüro bei seiner Aufschlagsstrategie für den Online-Verkauf durchgeht, und sie bricht auf dieselbe Weise, wenn sich die Basis darunter verschiebt.
Idempotenz — und was ein Timeout bei der Buchung bedeutet
Diesen Abschnitt sollten Sie zweimal lesen.
Wenn ein Buchungsaufruf in den Timeout läuft, wissen Sie nicht, was passiert ist. Vielleicht kam die Anfrage nie an. Vielleicht kam sie an und schlug fehl. Oder — der schmerzhafte Fall — sie kam an, der Anbieter legte den PNR bei der Airline an, und die Antwort ging auf dem Rückweg verloren. Für Ihren Code sehen alle drei Fälle gleich aus. Für die Airline ist der dritte eine aktive Reservierung, die Sitze auf den Namen Ihres Kunden blockiert.
Der Reflex aus anderen Integrationen ist der Retry. Hier kann ein blinder Retry einen zweiten PNR für dieselben Reisenden auf demselben Flug erzeugen. Airlines werten Doppelbuchungen als Regelverstoß; je nach Carrier und Vereinbarungen des Reisebüros reicht die Folge von der automatischen Stornierung einer oder beider Reservierungen bis zu einer Belastungsanzeige — einem ADM — an den Aussteller. Das Reisebüro, das sie erhält, wird wissen wollen, warum Ihr System zweimal gebucht hat.
Was funktioniert, ungefähr in dieser Reihenfolge:
- Erzeugen Sie Ihre eigene Buchungsreferenz, bevor Sie nach außen rufen, speichern Sie sie und senden Sie sie mit, wo immer die API eine Client-Referenz akzeptiert. Unterstützt die API einen Idempotenzschlüssel, nutzen Sie ihn; wenn nicht, ist Ihre Referenz trotzdem das, womit Sie die Buchung später wiederfinden.
- Modellieren Sie den unbekannten Zustand explizit. Ausstehend, bestätigt, fehlgeschlagen — und unbekannt. Ein Timeout setzt die Buchung auf „unbekannt", nicht auf „fehlgeschlagen".
- Klären Sie Unbekanntes durch Nachfragen, nicht durch Wiederholen. Rufen Sie die Buchung über Ihre Referenz ab oder listen Sie die jüngsten Buchungen dieser Reisenden, bevor Sie über einen neuen Versuch entscheiden.
- Lassen Sie einen Abgleichjob laufen, der alles noch Unbekannte durchgeht, mit den Meldungen des Anbieters vergleicht und das, was er nicht klären kann, an eine menschliche Warteschlange gibt, statt zu raten.
Timeouts beim Ticketing sind dasselbe Problem, nur mit Geld. Belasten Sie die Karte vor dem Ticketing und das Ticketing hängt, haben Sie einen zahlenden Kunden und womöglich kein Ticket. Stellen Sie das Ticket vor der Belastung aus und die Belastung scheitert, haben Sie ein Dokument ausgestellt, das jemand der Airline bezahlen muss. Üblich ist: Karte autorisieren, ausstellen, bei Erfolg einziehen — entscheidend ist, das bewusst festzulegen und nicht erst in der Produktion zu entdecken.
Reisebegriffe, die Webentwickler überraschen
Keiner davon ist schwer. Jeder hat jemanden eine Woche gekostet, der nicht wusste, dass es ihn gibt.
Ein PNR ist kein Ticket
Der PNR ist der Reservierungsdatensatz: Reisende, Segmente, Kontaktdaten, eine Frist. Das Ticket ist das bezahlte Dokument, das zum Fliegen berechtigt. Ein PNR ohne Ticket verfällt mit seiner Ticketing-Frist, und die Sitze gehen zurück in den Verkauf — manchmal, ohne dass Sie es auf Ihrer Seite bemerken.
Namen sind nahezu unveränderlich
Nach dem Ticketing erlauben die meisten Tarife keine Namensänderung über eine kleine Korrektur hinaus, und was als klein gilt, variiert je nach Airline. Der Name muss zum Reisedokument passen. Erfassen Sie Nachname und Vornamen getrennt, lassen Sie keine frei getippte Anrede ins Namensfeld rutschen und validieren Sie vor dem Buchungsaufruf, nicht danach.
Reisendentypen sind Preise, keine Dekoration
Erwachsener, Kind und Kleinkind sind Tariftypen, und maßgeblich ist meist das Alter am Reisetag, nicht am Buchungstag. Ein Kleinkind auf dem Schoß belegt in der Regel keinen Sitz und reist nur mit einem Erwachsenen. Ein falscher Typ, und die Preisprüfung scheitert oder nennt den falschen Tarif.
Zeiten sind lokal, und ein Segment ist kein Leg
Abflug- und Ankunftszeiten werden in der Ortszeit des jeweiligen Flughafens angegeben. Rechnen Sie sie für die Anzeige nicht in die Zeitzone des Nutzers um, und berechnen Sie Dauern nicht durch Subtraktion ohne die Zeitversätze. Eine Reise besteht aus Segmenten; ein Segment mit technischem Zwischenstopp besteht aus mehreren Legs. Oberfläche und Daten müssen sich einig sein, was ein „Stopp" ist.
Nach dem Verkauf passiert noch etwas
Airlines ändern Flugpläne, nachdem Tickets ausgestellt wurden. Eine Buchung, die beim Ticketing korrekt war, kann Wochen später eine neue Uhrzeit, eine neue Flugnummer oder einen geplatzten Anschluss zeigen; je nach Anbieter erfahren Sie das über eine Benachrichtigung, eine Queue oder indem Sie die Buchung erneut abrufen. Planen Sie ein, dass sich die Buchung ändert, nachdem Sie aufgehört haben, sie anzusehen.
Void ist keine Erstattung
Kurz nach der Ausstellung gibt es meist ein Fenster, in dem ein Ticket gevoidet werden kann, als hätte es nie existiert. Danach bleibt nur eine Erstattung nach Tarifbestimmungen, die eine Gebühr kosten oder gar nichts zurückbringen kann. Fenster und Regeln gehören dem Anbieter und der Ausstellungsvereinbarung; lesen Sie sie, bevor Sie einen „Stornieren"-Button bauen.
Was ein Fehler kostet
Fehler in einer Fluganbindung sind auf eine bestimmte Art teuer: Sie landen bei Menschen, nicht in Logs. Eine Doppelbuchung wird zu einem Anruf bei der Airline und womöglich zu einer Belastung auf dem Konto des Reisebüros. Ein belasteter Kunde ohne Ticket wird zu Erstattung, Beschwerde und Rückbuchungsrisiko. Ein ohne erfolgreiche Zahlung ausgestelltes Ticket wird zu einer Schuld bei der Airline, die jemand begleichen muss. Eine Flugplanänderung, die niemand bearbeitet hat, wird zu einem Reisenden am Flughafen für einen Flug, der früher gestartet ist.
Nichts davon zeigt sich im Happy-Path-Test. Schreiben Sie zuerst die Fehlerpfade: Timeout bei der Buchung, gestiegener Preis, Ticket scheitert nach dem PNR, Void nach erfolgreicher Zahlung. Sind die abgedeckt, ist der Happy Path der leichte Teil.
Testen gegen eine Flug-API
Testumgebungen der Anbieter sind nützlich und unvollständig. Sie sind meist ruhiger als die Produktion, ausgebuchte Klassen und Preisänderungen sind dort seltener, und manche simulieren Timeouts gar nicht. Nutzen Sie sie für die Form der Aufrufe und die Validierungsfehler, und planen Sie dann einen kontrollierten Lauf in Produktion mit echten Buchungen, die Sie im Void-Fenster stornieren — mit Wissen des Operations-Teams.
Ob Sie überhaupt integrieren sollten, ist eine andere Frage. Brauchen Sie eigentlich einen Shop statt rohen Inventars im eigenen System, ist die Abwägung in White Label oder eigene Buchungsmaschine beschrieben, und dieselbe Überlegung gilt für ein B2B-Portal für Subagenturen. Wollen Sie das Inventar in Ihrem eigenen Code, bietet diese Plattform Flug- und Hotel-APIs an; der Zugang beginnt mit einem Gespräch über Ihren Anwendungsfall statt mit einem Self-Service-Schlüssel — und genau das ist auch der richtige Moment, jede der Fragen oben zu stellen.