API-integratie voor vluchtboekingen: wat de docs weglaten

Op het bord staat een ticket met twee woorden: "vluchten toevoegen". Je hebt al een betaalkoppeling gebouwd, een integratie voor verzendtarieven, misschien een met kaarten, en je neemt het voor de hand liggende model mee: zoeken, resultaten tonen, kaart afschrijven, klaar. Dan komt de eerste echte boeking terug met een andere prijs dan op de resultatenpagina, de tweede loopt in een time-out en niemand kan zeggen of de klant een stoel heeft, en iemand van operations vraagt waarom er wel een reservering is maar geen ticket. Van buitenaf lijkt een API-integratie voor vluchtboekingen op een webshop-checkout. Daaronder zit een gedistribueerde transactie met systemen die ontworpen zijn lang voordat REST bestond, en de meeste verrassingen komen uit dat verschil.
Dit stuk is geschreven voor de developer die nog nooit een PNR heeft gezien. Het gaat niet over de endpoints van één leverancier; de namen verschillen per provider, de vorm blijft hetzelfde.
De volgorde van calls achter een API-integratie voor vluchtboekingen
Bijna elke vlucht-API doorloopt, hoe de methodes ook heten, dezelfde vier stappen. Het meeste werk zit in het juist trekken van de grenzen ertussen.
| Stap | Wat je terugkrijgt | Wat je moet opslaan | Wat er misgaat |
|---|---|---|---|
| Search | Reisroutes met een prijs en een ondoorzichtige offer- of fare-key | Niets blijvends — resultaten verouderen snel | Je behandelt de prijs als definitief; de key verloopt vóór de checkout |
| Price / verify | De bevestigde prijs, tariefregels, bagage, soms verplichte passagiersvelden | Het geverifieerde aanbod en de vervaltijd ervan | Prijs gewijzigd; de klasse is uitverkocht; de regels wijken af van wat je toonde |
| Book | Een reservering — de PNR — met een record locator en een ticketing-deadline | Je eigen referentie, de locator, de deadline, de exacte passagiersgegevens die je stuurde | Time-out zonder antwoord; dubbele PNR's; namen afgewezen |
| Ticket | Uitgegeven e-ticketnummers; hier wordt het geld werkelijk vastgelegd | Elk ticketnummer, gekoppeld aan de passagier en het segment waar het bij hoort | Gedeeltelijke uitgifte; reservering door de airline geannuleerd omdat de deadline verstreken is |
Over de derde rij ontstaat altijd discussie, omdat veel API's boeken en ticketen in één call toestaan. Gebruik dat gerust. In de wereld van de airline blijven het twee aparte dingen: een PNR kan bestaan zonder ticket, en een ticket kan mislukken nadat de PNR al is aangemaakt. Een gecombineerd endpoint verbergt alleen het moment waarop het ene lukte en het andere niet, dus je datamodel heeft nog steeds een plek voor die toestand nodig.
Let ook op wat search níet teruggeeft: een belofte. Het is een advertentie. De price-stap is de offerte, en pas het ticket is de verkoop.
Waarom de gezochte prijs niet de geboekte prijs is
Webdevelopers verwachten een catalogus. Airline-inventaris is dat niet. Een vlucht wordt verkocht in boekingsklassen, elk een bak stoelen tegen een bepaald tarief, en de airline opent en sluit die bakken voortdurend naarmate de vlucht volloopt. Zoekresultaten worden snel samengesteld uit beschikbaarheid die al wat achter kan lopen; tegen de tijd dat een gebruiker twee paspoorten heeft ingetikt, kan de goedkoopste bak op die vlucht dicht zijn. Bij de price-stap wordt opnieuw gevraagd, en het eerlijke antwoord is soms hoger.
Belastingen schuiven ook. Ze worden bij het prijzen opnieuw berekend voor de exacte passagiers en route, en een kind of baby wordt anders geprijsd dan de volwassene waar de zoekopdracht van uitging. Valutaomrekening, als je storefront een andere valuta toont dan die waarin de leverancier offreert, is nog een plek waar het bedrag verschuift.
De gevolgtrekking voor het ontwerp is simpel en wordt vaak overgeslagen: schrijf nooit af op de zoekprijs. Draai de price-stap vóór de betaling, vergelijk, en als het bedrag veranderd is, toon je het nieuwe bedrag en vraag je om akkoord. Je opslag moet opnieuw berekend worden op het herprijsde tarief en niet worden overgenomen van de resultatenpagina — het is dezelfde logica die een reisbureau doorloopt bij het bepalen van een opslagstrategie online, en ze gaat op dezelfde manier stuk als de basis eronder verschuift.
Idempotentie, en wat een time-out tijdens het boeken betekent
Dit is de sectie om twee keer te lezen.
Als een boekingscall in een time-out loopt, weet je niet wat er gebeurd is. Het verzoek is misschien nooit aangekomen. Het kan zijn aangekomen en mislukt. Of — het pijnlijke geval — het is aangekomen, de leverancier heeft de PNR bij de airline aangemaakt, en het antwoord is onderweg terug naar jou verloren gegaan. Voor je code zien alle drie er hetzelfde uit. Voor de airline is de derde een actieve reservering die stoelen vasthoudt op naam van je klant.
De reflex uit andere integraties is opnieuw proberen. Hier kan een blinde retry een tweede PNR opleveren voor dezelfde passagiers op dezelfde vlucht. Airlines zien dubbele boekingen als een overtreding van hun beleid; afhankelijk van de maatschappij en de afspraken van het reisbureau varieert het gevolg van automatische annulering van een of beide reserveringen tot een debit memo — een ADM — aan wie ze heeft uitgegeven. Het reisbureau dat die ontvangt, wil weten waarom jouw systeem twee keer boekte.
Wat werkt, ongeveer in deze volgorde:
- Maak je eigen boekingsreferentie aan voordat je de call doet, sla die op en stuur haar mee overal waar de API een client-referentie accepteert. Ondersteunt de API een idempotentiesleutel (idempotency key), gebruik die dan; doet hij dat niet, dan is je referentie nog steeds waarmee je de boeking achteraf kunt terugvinden.
- Modelleer de onbekende toestand expliciet. Pending, bevestigd, mislukt — en onbekend. Een time-out zet een boeking op onbekend, niet op mislukt.
- Los onbekend op door te vragen, niet door te herhalen. Haal de boeking op via je referentie, of vraag de recente boekingen voor die passagiers op, voordat je besluit het opnieuw te proberen.
- Draai een reconciliatiejob die alles wat nog onbekend is langsloopt en vergelijkt met wat de leverancier rapporteert, en stuur wat hij niet kan afhandelen naar een wachtrij voor een mens in plaats van te gokken.
Time-outs bij het ticketen zijn hetzelfde probleem, maar dan met geld eraan vast. Schrijf je de kaart af vóór het ticketen en blijft het ticketen hangen, dan heb je een betalende klant en mogelijk geen ticket. Ticket je vóór de afschrijving en mislukt de afschrijving, dan heb je een document uitgegeven waarvoor iemand de airline moet betalen. Eerst de kaart autoriseren, dan ticketen, en bij succes afschrijven is de gangbare vorm — het gaat erom dat je dit bewust kiest, en het niet in productie ontdekt.
De reisbegrippen die webdevelopers verrassen
Geen ervan is moeilijk. Elk ervan heeft iemand een week gekost omdat hij niet wist dat het bestond.
Een PNR is geen ticket
De PNR is het reserveringsrecord: passagiers, segmenten, contactgegevens, een deadline. Het ticket is het betaalde document dat de passagier recht geeft om te vliegen. Een PNR zonder ticket vervalt op de ticketing-deadline en de stoelen gaan terug in de verkoop, vanuit jouw kant gezien soms zonder enig signaal.
Namen zijn bijna onveranderlijk
Na het ticketen staan de meeste tarieven geen naamswijziging toe buiten een kleine correctie, en wat als klein telt, verschilt per airline. De naam moet overeenkomen met het reisdocument. Vraag achternaam en voornamen apart uit, laat geen vrij ingevulde aanhef in een naamveld lekken, en valideer vóór de book-call, niet erna.
Passagierstypen bepalen de prijs, ze zijn geen decoratie
Volwassene, kind en baby zijn tarieftypen, en de leeftijd die bepaalt welke geldt, is meestal de leeftijd op de reisdatum, niet op de boekingsdatum. Een baby op schoot neemt doorgaans geen stoel in en mag alleen met een volwassene reizen. Zit het type fout, dan mislukt de price-stap of krijg je het verkeerde tarief terug.
Tijden zijn lokaal, en segmenten zijn geen legs
Vertrek- en aankomsttijden staan in de lokale tijd van elke luchthaven. Reken ze voor weergave niet om naar de tijdzone van de gebruiker, en bereken geen reisduur door ze van elkaar af te trekken zonder de offsets. Een reis bestaat uit segmenten; een segment met een technische tussenstop bestaat uit meer dan één leg. Je UI en je data moeten het eens zijn over welke van die twee een "stop" is.
Na de verkoop gebeurt er nog van alles
Airlines wijzigen dienstregelingen nadat tickets zijn uitgegeven. Een boeking die bij het ticketen klopte, kan weken later een nieuwe tijd, een nieuw vluchtnummer of een gebroken aansluiting tonen, en afhankelijk van de leverancier hoor je dat via een notificatie, een queue of door de boeking opnieuw op te halen. Reken erop dat de boeking verandert nadat je er niet meer naar kijkt.
Voiden is geen refund
Kort na uitgifte is er meestal een venster waarin een ticket gevoid kan worden alsof het nooit heeft bestaan. Daarna is alleen nog een refund volgens de tariefregels mogelijk, en die kan een boete kosten of helemaal niets opleveren. Het venster en de regels horen bij de leverancier en de uitgifteovereenkomst; lees ze voordat je een knop "annuleren" bouwt.
Wat het kost als het misgaat
De fouten in een vluchtintegratie zijn op een specifieke manier duur: ze komen terecht bij mensen, niet in logs. Een dubbele boeking wordt een telefoontje naar de airline en mogelijk een memo op de rekening van het reisbureau. Een klant die betaald heeft zonder ticket wordt een terugbetaling, een klacht en een chargebackrisico. Een ticket dat is uitgegeven zonder geslaagde betaling wordt een schuld aan de airline die iemand moet vereffenen. Een dienstregelingswijziging die niemand verwerkte, wordt een reiziger op de luchthaven voor een vlucht die al eerder vertrok.
Niets daarvan komt naar boven in een happy-path-test. Schrijf eerst de ongelukkige paden: de time-out tijdens het boeken, de prijs die steeg, het ticket dat mislukte na de PNR, de void na een geslaagde betaling. Als die afgehandeld zijn, is het happy path het makkelijke deel.
Testen tegen een vlucht-API
Testomgevingen van leveranciers zijn nuttig en onvolledig. Ze zijn meestal rustiger dan productie, dus uitverkochte klassen en prijswijzigingen komen minder voor, en sommige simuleren helemaal geen time-outs. Gebruik ze voor de vorm van de calls en de validatiefouten, en plan daarna een gecontroleerde run in productie met echte boekingen die je binnen het venster voidt — met operations op de hoogte dat je dat doet.
Of je überhaupt moet integreren, is een andere vraag. Als je eigenlijk een storefront nodig hebt in plaats van ruwe inventaris in je eigen systeem, staat de afweging in white label of zelf een boekingsengine bouwen, en dezelfde redenering geldt voor een B2B-portaal voor subagenten. Wil je de inventaris wel in je eigen code, dan biedt dit platform API's voor vluchten en hotels, en toegang begint met een gesprek over je use case in plaats van een self-service key — en dat is meteen het juiste moment om elk van de vragen hierboven te stellen.