Hoppa till innehållet
Blogg

API-integration för flygbokning: det dokumentationen hoppar över

Tekravel Redaktion
Skriven med hjälp av AI

Lappen på tavlan säger ”lägg till flyg”. Ni har redan levererat en betalningsintegration, en för fraktpriser, kanske en för kartor, och den mentala modellen ni tar med er är den uppenbara: sök, visa resultat, ta kortet, klart. Sedan kommer den första riktiga bokningen tillbaka till ett annat pris än det på resultatsidan, den andra får timeout och ingen kan säga om kunden har en plats, och någon på operations frågar varför det finns en reservation men ingen biljett. En API-integration för flygbokning ser utifrån ut som en e-handelskassa. Under ytan är den en distribuerad transaktion mot system som designades långt före REST, och de flesta överraskningarna kommer ur just det glappet.

Det här är skrivet för utvecklaren som aldrig har sett en PNR. Det handlar inte om någon enskild leverantörs endpoints; namnen skiljer sig mellan leverantörer, formen gör det inte.

Anropssekvensen bakom en API-integration för flygbokning

Nästan varje flyg-API, oavsett vad det kallar sina metoder, går igenom samma fyra steg. Att dra gränserna mellan dem rätt är merparten av jobbet.

StegVad det ger erVad ni måste lagraVad som går fel
SökResvägar med ett pris och en ogenomskinlig erbjudande- eller tariffnyckelInget beständigt — resultaten blir snabbt inaktuellaNi behandlar priset som slutgiltigt; nyckeln löper ut före kassan
Prissätt / verifieraDet bekräftade priset, tariffreglerna, bagaget, ibland obligatoriska passagerarfältDet verifierade erbjudandet och när det löper utPriset ändrades; klassen tog slut; reglerna skiljer sig från det ni visade
BokaEn reservation — PNR:n — med record locator och biljetteringsfristEr egen referens, locatorn, fristen, exakt de passageraruppgifter ni skickadeTimeout utan svar; dubbla PNR; namn som avvisas
BiljetteraUtfärdade e-biljettnummer; här binds pengarna på riktigtVarje biljettnummer, kopplat till passageraren och segmentet det tillhörDelvis utfärdande; reservationen avbokad av flygbolaget för att fristen passerade

Raden folk bråkar om är den tredje, eftersom många API:er låter er boka och biljettera i ett enda anrop. Använd det om ni vill. De två sakerna är fortfarande åtskilda i flygbolagets värld: en PNR kan finnas utan biljett, och en biljett kan misslyckas efter att PNR:n skapats. En kombinerad endpoint döljer bara ögonblicket då det ena lyckades och det andra inte, så er datamodell behöver ändå ha plats för det tillståndet.

Lägg också märke till vad sökningen inte returnerar: ett löfte. Den är en annons. Prissteget är offerten, och först biljetten är försäljningen.

Varför priset ni sökte inte är priset ni bokar

Webbutvecklare förväntar sig en katalog. Flygbolagens inventarie är ingen katalog. Ett flyg säljs i bokningsklasser, var och en en hink med platser till en tariff, och flygbolaget öppnar och stänger de hinkarna löpande allteftersom flyget fylls. Sökresultat sätts snabbt ihop från tillgänglighet som redan kan ligga lite efter; när användaren har knappat in två pass kan den billigaste hinken på det flyget ha stängt. När prissteget körs frågar det igen, och det ärliga svaret är ibland högre.

Skatterna bidrar med egen drift. De räknas om vid prissättningen för de exakta passagerarna och rutten, och ett barn eller ett spädbarn prissätts annorlunda än den vuxna som sökningen antog. Valutaomräkning, om er butik visar kronor medan leverantören prissätter i euro eller dollar, är ytterligare ett ställe där siffran rör sig.

Designkonsekvensen är enkel och hoppas ofta över: debitera aldrig på sökpriset. Kör prissteget före betalning, jämför, och om beloppet ändrats, visa den nya siffran och fråga. Vilket påslag ni än lägger på måste räknas om på den omprissatta tariffen, inte föras över från resultatsidan — logiken är densamma som en resebyrå arbetar igenom när den sätter en påläggsstrategi online, och den brister på samma sätt när basen flyttar sig under den.

Idempotens, och vad en timeout under bokning betyder

Det här är avsnittet att läsa två gånger.

När ett bokningsanrop får timeout vet ni inte vad som hände. Begäran kanske aldrig kom fram. Den kan ha kommit fram och misslyckats. Eller — fallet som gör ont — den kom fram, leverantören skapade PNR:n hos flygbolaget, och svaret försvann på vägen tillbaka till er. För er kod ser alla tre identiska ut. För flygbolaget är det tredje en levande reservation som håller platser i er kunds namn.

Reflexen från andra integrationer är att försöka igen. Här kan ett blint nytt försök skapa en andra PNR för samma passagerare på samma flyg. Flygbolag betraktar dubbelbokningar som ett regelbrott; beroende på bolag och byråns avtal sträcker sig konsekvensen från automatisk avbokning av den ena eller båda reservationerna till en debetnota — en ADM — skickad till den som utfärdade dem. Byrån som får den vill veta varför ert system bokade två gånger.

Det som fungerar, ungefär i den här ordningen:

  • Skapa er egen bokningsreferens innan ni anropar utåt, spara den och skicka den med begäran överallt där API:et tar emot en klientreferens. Om API:et stöder en idempotency key, använd den; om inte är er referens ändå det som låter er söka upp bokningen efteråt.
  • Modellera det okända tillståndet uttryckligen. Väntande, bekräftad, misslyckad — och okänd. En timeout flyttar en bokning till okänd, inte till misslyckad.
  • Lös okänd genom att fråga, inte genom att upprepa. Hämta via er referens, eller lista de senaste bokningarna för de passagerarna, innan ni avgör om ni ska försöka igen.
  • Kör ett avstämningsjobb som sveper allt som fortfarande är okänt, jämför med vad leverantören rapporterar och skickar det som inte går att avgöra till en kö för en människa i stället för att gissa.

Timeouts vid biljettering är samma problem med pengar inblandade. Om ni drar kortet före biljetteringen och biljetteringen hänger sig har ni en betalande kund och möjligen ingen biljett. Om ni biljetterar före dragningen och dragningen misslyckas har ni utfärdat ett dokument som någon måste betala flygbolaget för. Auktorisera kortet först, biljettera, sedan dra vid lyckat resultat är den vanliga formen — poängen är att besluta det medvetet, inte upptäcka det i produktion.

Resebranschens begrepp som överraskar webbutvecklare

Inget av dem är svårt. Vart och ett har kostat någon en vecka för att de inte visste att det fanns.

En PNR är inte en biljett

PNR:n är reservationsposten: passagerare, segment, kontakter, en frist. Biljetten är det betalda dokumentet som ger passageraren rätt att flyga. En obiljetterad PNR löper ut vid sin biljetteringsfrist och platserna går tillbaka till försäljning, ibland utan att ni märker något.

Namn är nära nog oföränderliga

Efter biljettering tillåter de flesta tariffer ingen namnändring utöver en mindre rättelse, och vad som räknas som mindre varierar mellan flygbolag. Namnet måste matcha resehandlingen. Samla in efternamn och förnamn separat, låt inte en fritextstitel läcka in i ett namnfält, och validera före bokningsanropet, inte efter.

Passagerartyper prissätts, de är inte dekoration

Vuxen, barn och spädbarn är tarifftyper, och åldern som avgör vilken som gäller är vanligtvis åldern på resdagen, inte på bokningsdagen. Ett spädbarn i knät tar normalt ingen plats och får ofta bara resa med en vuxen. Fel typ gör att prissteget antingen misslyckas eller offererar fel tariff.

Tider är lokala, och segment är inte ben

Avgångs- och ankomsttider anges i varje flygplats lokala tid. Konvertera dem inte till användarens tidszon för visning, och beräkna inte restider genom att subtrahera dem utan offsetarna. En resa innehåller segment; ett segment med en teknisk mellanlandning innehåller mer än ett ben. Ert UI och era data måste vara överens om vilket av dessa ett ”stopp” är.

Saker händer efter försäljningen

Flygbolag ändrar tidtabeller efter att biljetter utfärdats. En bokning som var korrekt vid biljetteringen kan veckor senare visa en ny tid, ett nytt flightnummer eller en bruten anslutning, och beroende på leverantör får ni veta det via en notifiering, en kö eller genom att hämta bokningen igen. Planera för att bokningen ändras efter att ni slutat titta på den.

Void är inte återbetalning

Strax efter utfärdandet finns vanligtvis ett fönster där en biljett kan makuleras (void) som om den aldrig funnits. Efter det fönstret är bara återbetalning enligt tariffreglerna möjlig, och den kan kosta en avgift eller ge ingenting alls tillbaka. Fönstret och dess regler tillhör leverantören och utfärdandeavtalet; läs dem innan ni bygger en ”avboka”-knapp.

Vad det kostar att göra fel

Felen i en flygintegration är dyra på ett specifikt sätt: de landar på människor, inte i loggar. En dubbelbokning blir ett telefonsamtal till flygbolaget och möjligen en nota mot byråns konto. En debiterad kund utan biljett blir en återbetalning, ett klagomål och en chargeback-risk. En biljett utfärdad utan lyckad betalning blir en skuld till flygbolaget som någon måste reglera. En tidtabellsändring ingen hanterade blir en resenär på flygplatsen inför ett flyg som gick tidigare.

Inget av det syns i ett happy path-test. Skriv de olyckliga vägarna först: timeouten under bokning, priset som steg, biljetten som misslyckades efter PNR:n, voiden efter en lyckad betalning. Hanteras de är den lyckliga vägen den enkla delen.

Att testa mot ett flyg-API

Leverantörernas testmiljöer är användbara och ofullständiga. De brukar vara lugnare än produktion, så slutsålda klasser och prisändringar är ovanligare, och några simulerar inte timeouts alls. Använd dem för anropens form och valideringsfelen, planera sedan en kontrollerad körning i produktion med riktiga bokningar som ni makulerar inom fönstret — med operations medvetna om att ni gör det.

Huruvida ni alls ska integrera är en separat fråga. Om det ni egentligen behöver är en butik snarare än rå inventarie i ert eget system beskrivs avvägningen i white label eller egen bokningsmotor, och samma resonemang gäller en B2B-portal för underagenter. Vill ni ha inventariet i er egen kod exponerar plattformen API:er för flyg och hotell, och åtkomsten börjar med ett samtal om ert användningsfall snarare än en självbetjäningsnyckel — vilket också är rätt tillfälle att ställa var och en av frågorna ovan.

Tekravel Redaktion

Desk för resetechnologi

Tekravels desk för resetechnologi skriver för branschen: byråägare, konsolidatorer och utvecklarna som integrerar dem. Varje artikel kontrolleras mot plattformen den beskriver innan den publiceras.