API-integration til flybooking: det dokumentationen udelader

Kortet på tavlen siger ”tilføj fly”. I har allerede leveret en betalingsintegration, en til fragtpriser, måske en til kort, og den mentale model, I tager med, er den oplagte: søg, vis resultater, træk kortet, færdig. Så kommer den første rigtige booking tilbage til en anden pris end den på resultatsiden, den næste får timeout, og ingen kan fortælle jer, om kunden har et sæde, og nogen fra driften spørger, hvorfor der findes en reservation, men ingen billet. En API-integration til flybooking ligner udefra en e-handelscheckout. Nedenunder er den en distribueret transaktion mod systemer, der blev designet længe før REST, og de fleste overraskelser kommer af netop det hul.
Dette er skrevet til udvikleren, der aldrig har set en PNR. Det handler ikke om en bestemt leverandørs endpoints; navnene skifter mellem udbydere, formen gør ikke.
Kaldesekvensen bag en API-integration til flybooking
Næsten ethvert fly-API, uanset hvad det kalder sine metoder, går igennem de samme fire trin. At trække grænserne mellem dem rigtigt er det meste af arbejdet.
| Trin | Hvad det giver jer | Hvad I skal gemme | Hvad der går galt |
|---|---|---|---|
| Søg | Rejseruter med en pris og en uigennemsigtig tilbuds- eller tarifnøgle | Intet varigt — resultaterne bliver hurtigt forældede | I behandler prisen som endelig; nøglen udløber før checkout |
| Prissæt / verificer | Den bekræftede pris, tarifreglerne, bagagen, nogle gange obligatoriske passagerfelter | Det verificerede tilbud og dets udløb | Prisen ændrede sig; klassen blev udsolgt; reglerne afviger fra det, I viste |
| Book | En reservation — PNR'en — med record locator og udstedelsesfrist | Jeres egen reference, locatoren, fristen, præcis de passagerdata I sendte | Timeout uden svar; dobbelte PNR'er; afviste navne |
| Udsted | Udstedte e-billetnumre; her bliver pengene reelt bundet | Hvert billetnummer, knyttet til den passager og det segment det hører til | Delvis udstedelse; reservation annulleret af flyselskabet, fordi fristen udløb |
Rækken, folk diskuterer, er den tredje, fordi mange API'er lader jer booke og udstede i ét kald. Brug det, hvis I vil. De to ting er stadig adskilte i flyselskabets verden: en PNR kan findes uden billet, og en billet kan fejle, efter PNR'en er oprettet. Et kombineret endpoint skjuler blot øjeblikket, hvor det ene lykkedes og det andet ikke gjorde, så jeres datamodel skal stadig have plads til den tilstand.
Bemærk også, hvad søgningen ikke returnerer: et løfte. Den er en annonce. Pristrinnet er tilbuddet, og først billetten er salget.
Hvorfor den pris, I søgte, ikke er den pris, I booker
Webudviklere forventer et katalog. Flyselskabernes lager er ikke et. Et fly sælges i bookingklasser, hver en spand af sæder til en tarif, og flyselskabet åbner og lukker de spande løbende, efterhånden som flyet fyldes. Søgeresultater samles hurtigt ud fra en tilgængelighed, der måske allerede halter lidt; når brugeren har tastet to pas ind, kan den billigste spand på det fly være lukket. Når pristrinnet kører, spørger det igen, og det ærlige svar er nogle gange højere.
Skatterne tilføjer deres egen drift. De genberegnes ved prissætningen for de præcise passagerer og den præcise rute, og et barn eller et spædbarn prissættes anderledes end den voksne, søgningen antog. Valutaomregning, hvis jeres butik viser kroner, mens leverandøren prissætter i euro eller dollar, er endnu et sted, hvor tallet flytter sig.
Designkonsekvensen er enkel og springes ofte over: opkræv aldrig på søgeprisen. Kør pristrinnet før betaling, sammenlign, og hvis beløbet ændrede sig, så vis det nye tal og spørg. Uanset hvilken avance I lægger på, skal den genberegnes på den genprissatte tarif, ikke føres videre fra resultatsiden — logikken er den samme, som et rejsebureau arbejder igennem, når det fastlægger en avancestrategi online, og den knækker på samme måde, når grundlaget flytter sig under den.
Idempotens, og hvad et timeout under booking betyder
Det her er afsnittet, der skal læses to gange.
Når et bookingkald får timeout, ved I ikke, hvad der skete. Forespørgslen er måske aldrig nået frem. Den kan være nået frem og have fejlet. Eller — det tilfælde, der gør ondt — den nåede frem, leverandøren oprettede PNR'en hos flyselskabet, og svaret gik tabt på vej tilbage til jer. For jeres kode ser alle tre ens ud. For flyselskabet er det tredje en levende reservation, der holder sæder i jeres kundes navn.
Refleksen fra andre integrationer er at prøve igen. Her kan et blindt nyt forsøg skabe en PNR nummer to for de samme passagerer på det samme fly. Flyselskaber behandler dobbeltbookinger som en overtrædelse af reglerne; afhængigt af selskabet og bureauets aftaler spænder konsekvensen fra automatisk annullering af den ene eller begge reservationer til en debetnota — en ADM — sendt til den, der udstedte dem. Bureauet, der modtager den, vil vide, hvorfor jeres system bookede to gange.
Det, der virker, nogenlunde i denne rækkefølge:
- Opret jeres egen bookingreference, før I kalder ud, gem den og send den med forespørgslen, hvor API'et accepterer en klientreference. Hvis API'et understøtter en idempotency key, så brug den; hvis ikke, er jeres reference stadig det, der lader jer finde bookingen bagefter.
- Modellér den ukendte tilstand eksplicit. Afventer, bekræftet, fejlet — og ukendt. Et timeout flytter en booking til ukendt, ikke til fejlet.
- Afklar ukendt ved at spørge, ikke ved at gentage. Hent via jeres reference, eller list de seneste bookinger for de passagerer, før I beslutter, om I skal prøve igen.
- Kør et afstemningsjob, der fejer alt, hvad der stadig er ukendt, sammenligner det med det, leverandøren rapporterer, og sender det, det ikke kan afgøre, til en kø for et menneske frem for at gætte.
Timeouts ved udstedelse er det samme problem med penge på. Hvis I trækker kortet før udstedelsen, og udstedelsen hænger, har I en betalende kunde og muligvis ingen billet. Hvis I udsteder før trækket, og trækket fejler, har I udstedt et dokument, som nogen skal betale flyselskabet for. Autoriser kortet først, udsted, og træk så ved succes er den gængse form — pointen er at beslutte det bevidst, ikke opdage det i produktion.
Rejsebranchens begreber, der overrasker webudviklere
Ingen af dem er svære. Hvert af dem har kostet nogen en uge, fordi de ikke vidste, det fandtes.
En PNR er ikke en billet
PNR'en er reservationsposten: passagerer, segmenter, kontakter, en frist. Billetten er det betalte dokument, der giver passageren ret til at flyve. En uudstedt PNR udløber ved sin udstedelsesfrist, og sæderne kommer tilbage i salg, nogle gange helt stille set fra jeres side.
Navne er tæt på uforanderlige
Efter udstedelse tillader de fleste tariffer ikke en navneændring ud over en mindre rettelse, og hvad der tæller som mindre, varierer fra flyselskab til flyselskab. Navnet skal matche rejsedokumentet. Indsaml efternavn og fornavne separat, lad ikke en fritekst-titel sive ind i et navnefelt, og validér før bookingkaldet, ikke efter.
Passagertyper prissættes, de er ikke pynt
Voksen, barn og spædbarn er tariftyper, og den alder, der afgør hvilken der gælder, er normalt alderen på rejsedagen, ikke på bookingdagen. Et spædbarn på skødet optager typisk intet sæde og må ofte kun rejse sammen med en voksen. Forkert type betyder, at pristrinnet enten fejler eller giver den forkerte tarif.
Tider er lokale, og segmenter er ikke ben
Afgangs- og ankomsttider angives i hver lufthavns lokale tid. Konvertér dem ikke til brugerens tidszone til visning, og beregn ikke varigheder ved at trække dem fra hinanden uden offsets. En rejse indeholder segmenter; et segment med et teknisk stop indeholder mere end ét ben. Jeres UI og jeres data skal være enige om, hvilken af dem et ”stop” er.
Der sker ting efter salget
Flyselskaber ændrer fartplaner, efter billetterne er udstedt. En booking, der var korrekt ved udstedelsen, kan uger senere vise et nyt tidspunkt, et nyt flynummer eller en brudt forbindelse, og afhængigt af leverandøren får I det at vide gennem en notifikation, en kø eller ved at hente bookingen igen. Planlæg efter, at bookingen ændrer sig, efter I er holdt op med at kigge på den.
Void er ikke refusion
Kort efter udstedelsen er der normalt et vindue, hvor en billet kan annulleres (void), som om den aldrig havde eksisteret. Efter det vindue er kun refusion efter tarifreglerne mulig, og den kan koste et gebyr eller give ingenting tilbage. Vinduet og dets regler tilhører leverandøren og udstedelsesaftalen; læs dem, før I bygger en ”annullér”-knap.
Hvad det koster at gøre det forkert
Fejlene i en flyintegration er dyre på en bestemt måde: de lander på mennesker, ikke i logs. En dobbeltbooking bliver til et telefonopkald til flyselskabet og muligvis en nota mod bureauets konto. En opkrævet kunde uden billet bliver til en refusion, en klage og en chargeback-risiko. En billet udstedt uden en gennemført betaling bliver til en gæld til flyselskabet, som nogen skal afregne. En fartplansændring, ingen behandlede, bliver til en rejsende i lufthavnen til et fly, der afgik tidligere.
Intet af det dukker op i en happy path-test. Skriv de ulykkelige stier først: timeoutet under booking, prisen der steg, billetten der fejlede efter PNR'en, voiden efter en gennemført betaling. Er de håndteret, er den lykkelige sti den nemme del.
Test mod et fly-API
Leverandørernes testmiljøer er nyttige og ufuldstændige. De er som regel roligere end produktion, så udsolgte klasser og prisændringer er sjældnere, og nogle af dem simulerer slet ikke timeouts. Brug dem til kaldenes form og valideringsfejlene, og planlæg derefter en kontrolleret kørsel i produktion med rigtige bookinger, som I annullerer inden for vinduet — med driften orienteret om, at I gør det.
Om I overhovedet skal integrere, er et separat spørgsmål. Hvis det, I reelt har brug for, er en butik frem for råt lager i jeres eget system, er afvejningen beskrevet i white label eller egen bookingmotor, og det samme ræsonnement gælder for en B2B-portal til underagenter. Vil I have lageret i jeres egen kode, udstiller platformen API'er til fly og hoteller, og adgangen begynder med en samtale om jeres use case frem for en selvbetjeningsnøgle — hvilket også er det rette tidspunkt at stille hvert af spørgsmålene ovenfor.