Hopp til innholdet
Blogg

API-integrasjon for flybestilling: det dokumentasjonen utelater

Tekravel Redaksjon
Skrevet med hjelp av AI

Lappen på tavlen sier «legg til fly». Dere har allerede levert en betalingsintegrasjon, en for fraktpriser, kanskje en for kart, og den mentale modellen dere tar med dere er den opplagte: søk, vis resultater, trekk kortet, ferdig. Så kommer den første ekte bestillingen tilbake til en annen pris enn den på resultatsiden, den andre får timeout og ingen kan fortelle dere om kunden har et sete, og noen i drift spør hvorfor det finnes en reservasjon, men ingen billett. En API-integrasjon for flybestilling ser utenfra ut som en kasse i en nettbutikk. Under ligger en distribuert transaksjon mot systemer som ble designet lenge før REST, og de fleste overraskelsene kommer fra nettopp det gapet.

Dette er skrevet for utvikleren som aldri har sett en PNR. Det handler ikke om én bestemt leverandørs endepunkter; navnene skifter mellom leverandører, formen gjør det ikke.

Kallsekvensen bak en API-integrasjon for flybestilling

Nesten alle fly-API-er, uansett hva de kaller metodene sine, går gjennom de samme fire stegene. Å trekke grensene mellom dem riktig er mesteparten av jobben.

StegHva det gir dereHva dere må lagreHva som går galt
SøkReiseruter med en pris og en ugjennomsiktig tilbuds- eller tariffnøkkelIngenting varig — resultatene blir fort utdaterteDere behandler prisen som endelig; nøkkelen utløper før kassen
Pris / verifiserDen bekreftede prisen, tariffreglene, bagasjen, noen ganger obligatoriske passasjerfeltDet verifiserte tilbudet og når det utløperPrisen endret seg; klassen ble utsolgt; reglene avviker fra det dere viste
BestillEn reservasjon — PNR-en — med record locator og utstedelsesfristDeres egen referanse, locatoren, fristen, nøyaktig de passasjerdataene dere sendteTimeout uten svar; doble PNR-er; navn som avvises
UtstedUtstedte e-billettnumre; her bindes pengene for alvorHvert billettnummer, knyttet til passasjeren og segmentet det tilhørerDelvis utstedelse; reservasjon kansellert av flyselskapet fordi fristen gikk ut

Raden folk krangler om er den tredje, fordi mange API-er lar dere bestille og utstede i ett kall. Bruk det om dere vil. De to tingene er fortsatt adskilt i flyselskapets verden: en PNR kan finnes uten billett, og en billett kan feile etter at PNR-en ble opprettet. Et kombinert endepunkt skjuler bare øyeblikket der det ene lyktes og det andre ikke, så datamodellen deres må fortsatt ha plass til den tilstanden.

Legg også merke til hva søket ikke returnerer: et løfte. Det er en annonse. Prissteget er tilbudet, og først billetten er salget.

Hvorfor prisen dere søkte ikke er prisen dere bestiller

Webutviklere forventer en katalog. Flyselskapenes lager er ikke en. Et fly selges i bestillingsklasser, hver en bøtte med seter til en tariff, og flyselskapet åpner og lukker bøttene fortløpende etter hvert som flyet fylles. Søkeresultater settes raskt sammen fra tilgjengelighet som allerede kan ligge litt bak; innen brukeren har tastet inn to pass, kan den billigste bøtten på det flyet ha lukket. Når prissteget kjører, spør det på nytt, og det ærlige svaret er noen ganger høyere.

Avgiftene bidrar med sin egen drift. De beregnes på nytt ved prissetting for de eksakte passasjerene og ruten, og et barn eller et spedbarn prises annerledes enn den voksne søket antok. Valutaomregning, hvis butikken deres viser kroner mens leverandøren priser i euro eller dollar, er enda et sted tallet flytter seg.

Designkonsekvensen er enkel og hoppes ofte over: belast aldri søkeprisen. Kjør prissteget før betaling, sammenlign, og hvis beløpet endret seg, vis det nye tallet og spør. Uansett hvilket påslag dere legger på, må det beregnes på nytt på den omprisede tariffen, ikke tas med fra resultatsiden — logikken er den samme som et reisebyrå jobber seg gjennom når det setter en påslagsstrategi på nett, og den ryker på samme måte når grunnlaget flytter seg under den.

Idempotens, og hva en timeout under bestilling betyr

Dette er avsnittet å lese to ganger.

Når et bestillingskall får timeout, vet dere ikke hva som skjedde. Forespørselen kom kanskje aldri fram. Den kan ha kommet fram og feilet. Eller — tilfellet som gjør vondt — den kom fram, leverandøren opprettet PNR-en hos flyselskapet, og svaret gikk tapt på vei tilbake til dere. For koden deres ser alle tre identiske ut. For flyselskapet er det tredje en levende reservasjon som holder seter i kundens navn.

Refleksen fra andre integrasjoner er å prøve igjen. Her kan et blindt nytt forsøk gi en PNR nummer to for de samme passasjerene på det samme flyet. Flyselskaper behandler dobbeltbestillinger som et regelbrudd; avhengig av selskapet og byråets avtaler spenner konsekvensen fra automatisk kansellering av den ene eller begge reservasjonene til en debetnota — en ADM — sendt til den som utstedte dem. Byrået som mottar den vil vite hvorfor systemet deres bestilte to ganger.

Det som fungerer, omtrent i denne rekkefølgen:

  • Opprett deres egen bestillingsreferanse før dere kaller ut, lagre den og send den med forespørselen overalt der API-et tar imot en klientreferanse. Hvis API-et støtter en idempotency key, bruk den; hvis ikke, er referansen deres fortsatt det som lar dere finne bestillingen etterpå.
  • Modeller den ukjente tilstanden eksplisitt. Venter, bekreftet, feilet — og ukjent. En timeout flytter en bestilling til ukjent, ikke til feilet.
  • Løs ukjent ved å spørre, ikke ved å gjenta. Hent via referansen deres, eller list de siste bestillingene for de passasjerene, før dere avgjør om dere skal prøve igjen.
  • Kjør en avstemmingsjobb som går gjennom alt som fortsatt er ukjent, sammenligner med det leverandøren rapporterer, og sender det den ikke kan avgjøre til en kø for et menneske i stedet for å gjette.

Timeouts ved utstedelse er det samme problemet med penger på. Hvis dere trekker kortet før utstedelse og utstedelsen henger, har dere en betalende kunde og muligens ingen billett. Hvis dere utsteder før trekket og trekket feiler, har dere utstedt et dokument noen må betale flyselskapet for. Autoriser kortet først, utsted, og trekk ved suksess er den vanlige formen — poenget er å bestemme det bevisst, ikke oppdage det i produksjon.

Reisebransjens begreper som overrasker webutviklere

Ingen av dem er vanskelige. Hvert av dem har kostet noen en uke fordi de ikke visste at det fantes.

En PNR er ikke en billett

PNR-en er reservasjonsposten: passasjerer, segmenter, kontakter, en frist. Billetten er det betalte dokumentet som gir passasjeren rett til å fly. En uutstedt PNR utløper ved utstedelsesfristen og setene går tilbake i salg, noen ganger helt stille sett fra deres side.

Navn er nesten uforanderlige

Etter utstedelse tillater de fleste tariffer ingen navneendring utover en mindre rettelse, og hva som regnes som mindre varierer fra flyselskap til flyselskap. Navnet må samsvare med reisedokumentet. Samle inn etternavn og fornavn separat, ikke la en fritekst-tittel lekke inn i et navnefelt, og valider før bestillingskallet, ikke etter.

Passasjertyper prises, de er ikke pynt

Voksen, barn og spedbarn er tarifftyper, og alderen som avgjør hvilken som gjelder er vanligvis alderen på reisedagen, ikke på bestillingsdagen. Et spedbarn på fanget opptar normalt ikke et sete og får ofte bare reise sammen med en voksen. Feil type gjør at prissteget enten feiler eller gir feil tariff.

Tider er lokale, og segmenter er ikke etapper

Avgangs- og ankomsttider oppgis i hver flyplass sin lokale tid. Ikke konverter dem til brukerens tidssone for visning, og ikke beregn varigheter ved å trekke dem fra hverandre uten offsetene. En reise inneholder segmenter; et segment med en teknisk mellomlanding inneholder mer enn én etappe. UI-et og dataene deres må være enige om hvilken av disse et «stopp» er.

Ting skjer etter salget

Flyselskaper endrer rutetider etter at billetter er utstedt. En bestilling som var riktig ved utstedelse kan uker senere vise en ny tid, et nytt flightnummer eller en brutt forbindelse, og avhengig av leverandøren får dere vite det gjennom et varsel, en kø eller ved å hente bestillingen på nytt. Planlegg for at bestillingen endrer seg etter at dere har sluttet å se på den.

Void er ikke refusjon

Kort etter utstedelse finnes det vanligvis et vindu der en billett kan annulleres (void) som om den aldri eksisterte. Etter det vinduet er bare refusjon etter tariffreglene mulig, og den kan koste et gebyr eller gi ingenting tilbake. Vinduet og reglene tilhører leverandøren og utstedelsesavtalen; les dem før dere bygger en «avbestill»-knapp.

Hva det koster å gjøre feil

Feilene i en flyintegrasjon er dyre på en bestemt måte: de lander på mennesker, ikke i logger. En dobbeltbestilling blir en telefon til flyselskapet og muligens en nota mot byråets konto. En belastet kunde uten billett blir en refusjon, en klage og en chargeback-risiko. En billett utstedt uten gjennomført betaling blir en gjeld til flyselskapet som noen må gjøre opp. En ruteendring ingen behandlet blir en reisende på flyplassen til et fly som gikk tidligere.

Ingenting av dette dukker opp i en happy path-test. Skriv de ulykkelige stiene først: timeouten under bestilling, prisen som steg, billetten som feilet etter PNR-en, voiden etter en gjennomført betaling. Er de håndtert, er den lykkelige stien den enkle delen.

Testing mot et fly-API

Leverandørenes testmiljøer er nyttige og ufullstendige. De pleier å være roligere enn produksjon, så utsolgte klasser og prisendringer er sjeldnere, og noen simulerer ikke timeouts i det hele tatt. Bruk dem til kallenes form og valideringsfeilene, og planlegg deretter en kontrollert kjøring i produksjon med ekte bestillinger dere annullerer innenfor vinduet — med drift informert om at dere gjør det.

Om dere skal integrere i det hele tatt er et separat spørsmål. Hvis det dere egentlig trenger er en butikk framfor rått lager i deres eget system, er avveiningen beskrevet i white label eller egen bestillingsmotor, og det samme resonnementet gjelder en B2B-portal for underagenter. Vil dere ha lageret i deres egen kode, eksponerer plattformen API-er for fly og hotell, og tilgangen starter med en samtale om bruksområdet deres framfor en selvbetjeningsnøkkel — som også er rett tidspunkt å stille hvert av spørsmålene ovenfor.

Tekravel Redaksjon

Desk for reiseteknologi

Tekravels desk for reiseteknologi skriver for bransjen: byråeiere, konsolidatorer og utviklerne som integrerer dem. Hver artikkel kontrolleres mot plattformen den beskriver før den publiseres.