Przejdź do treści
Blog

Integracja API rezerwacji lotów: luki w dokumentacji

Redakcja Tekravel
Napisano z pomocą AI

Na tablicy wisi zadanie: „dodać loty”. Masz za sobą integrację płatności, integrację stawek wysyłki, może jeszcze map, i przychodzisz z oczywistym modelem w głowie: wyszukiwanie, lista wyników, obciążenie karty, gotowe. Potem pierwsza prawdziwa rezerwacja wraca z inną ceną niż na stronie wyników, druga kończy się timeoutem i nikt nie potrafi powiedzieć, czy klient ma miejsce, a ktoś z działu operacji pyta, dlaczego jest rezerwacja, a nie ma biletu. Z zewnątrz integracja API rezerwacji lotów wygląda jak checkout w sklepie internetowym. Pod spodem to transakcja rozproszona z systemami zaprojektowanymi na długo przed REST, i właśnie z tej różnicy bierze się większość niespodzianek.

Ten tekst jest dla programisty, który nigdy nie widział PNR. Nie dotyczy endpointów konkretnego dostawcy; nazwy różnią się między dostawcami, kształt pozostaje ten sam.

Sekwencja wywołań, na której stoi integracja API rezerwacji lotów

Prawie każde API lotnicze, niezależnie od tego, jak nazywa swoje metody, przechodzi przez te same cztery kroki. Większość pracy polega na poprawnym wyznaczeniu granic między nimi.

KrokCo dostajeszCo musisz zapisaćCo idzie nie tak
SearchTrasy z ceną i nieprzezroczystym kluczem oferty lub taryfyNic trwałego — wyniki szybko się dezaktualizująTraktujesz cenę jako ostateczną; klucz wygasa przed checkoutem
Price / verifyPotwierdzoną cenę, zasady taryfy, bagaż, czasem wymagane pola pasażeraZweryfikowaną ofertę i jej termin ważnościCena się zmieniła; klasa się wyprzedała; zasady różnią się od tego, co pokazałeś
BookRezerwację — PNR — z kodem rezerwacji (record locator) i terminem wystawienia biletuWłasny numer referencyjny, locator, termin, dokładnie te dane pasażerów, które wysłałeśTimeout bez odpowiedzi; zdublowane PNR; odrzucone nazwiska
TicketNumery wystawionych e-ticketów; dopiero tu pieniądze są naprawdę zaangażowaneKażdy numer biletu, przypisany do pasażera i segmentu, do którego należyCzęściowe wystawienie; rezerwacja anulowana przez linię, bo minął termin

Z trzecim wierszem ludzie się spierają, bo wiele API pozwala zarezerwować i wystawić bilet w jednym wywołaniu. Korzystaj z tego, jeśli chcesz. W świecie linii lotniczej to nadal dwie osobne rzeczy: PNR może istnieć bez biletu, a wystawienie biletu może się nie udać już po utworzeniu PNR. Połączony endpoint tylko ukrywa moment, w którym jedno się powiodło, a drugie nie, więc twój model danych i tak potrzebuje miejsca na ten stan.

Zwróć też uwagę, czego wyszukiwanie nie zwraca: obietnicy. To jest reklama. Krok price to wycena, a sprzedażą jest dopiero bilet.

Dlaczego cena z wyszukiwania nie jest ceną rezerwacji

Programiści webowi spodziewają się katalogu. Zasoby linii lotniczej nim nie są. Lot sprzedaje się w klasach rezerwacyjnych, z których każda to pula miejsc w określonej taryfie, a linia bez przerwy otwiera i zamyka te pule w miarę zapełniania się samolotu. Wyniki wyszukiwania składa się szybko z dostępności, która może już być nieco nieaktualna; zanim użytkownik wpisze dane z dwóch paszportów, najtańsza pula na tym locie mogła się zamknąć. Krok price pyta jeszcze raz, a uczciwa odpowiedź bywa wyższa.

Podatki też się przesuwają. Przy wycenie są przeliczane dla konkretnych pasażerów i trasy, a dziecko czy niemowlę wycenia się inaczej niż dorosłego, którego założyło wyszukiwanie. Przeliczenie walut, jeśli twój serwis pokazuje inną walutę niż ta, w której wycenia dostawca, to kolejne miejsce, w którym kwota się zmienia.

Wniosek projektowy jest prosty i często pomijany: nigdy nie obciążaj karty ceną z wyszukiwania. Uruchom krok price przed płatnością, porównaj, a jeśli kwota się zmieniła, pokaż nową i zapytaj o zgodę. Marżę trzeba przeliczyć od nowej taryfy, a nie przenosić ze strony wyników — to ta sama logika, którą biuro przechodzi, ustalając strategię marży online, i psuje się w ten sam sposób, gdy podstawa przesuwa się pod spodem.

Idempotentność i co oznacza timeout podczas rezerwacji

Tę sekcję warto przeczytać dwa razy.

Gdy wywołanie rezerwacji kończy się timeoutem, nie wiesz, co się stało. Żądanie mogło w ogóle nie dotrzeć. Mogło dotrzeć i się nie powieść. Albo — przypadek, który boli — dotarło, dostawca utworzył PNR w linii lotniczej, a odpowiedź zginęła w drodze powrotnej. Dla twojego kodu wszystkie trzy wyglądają identycznie. Dla linii trzeci to aktywna rezerwacja blokująca miejsca na nazwisko twojego klienta.

Odruch z innych integracji to ponowić próbę. Tutaj ślepe ponowienie może utworzyć drugi PNR dla tych samych pasażerów na tym samym locie. Linie traktują zdublowane rezerwacje jako naruszenie swoich zasad; w zależności od przewoźnika i umów biura konsekwencje sięgają od automatycznego anulowania jednej lub obu rezerwacji po notę obciążeniową — ADM — wysłaną do tego, kto je wystawił. Biuro, które ją dostanie, będzie chciało wiedzieć, dlaczego twój system zarezerwował dwa razy.

Co działa, mniej więcej w tej kolejności:

  • Utwórz własny numer referencyjny rezerwacji przed wywołaniem, zapisz go i wysyłaj z żądaniem wszędzie tam, gdzie API przyjmuje referencję klienta. Jeśli API obsługuje klucz idempotentności (idempotency key), użyj go; jeśli nie, twój numer referencyjny nadal pozwala potem odnaleźć rezerwację.
  • Zamodeluj jawnie stan nieznany. Oczekująca, potwierdzona, nieudana — i nieznana. Timeout przenosi rezerwację do stanu nieznanego, a nie nieudanego.
  • Rozstrzygaj stan nieznany pytaniem, nie powtórzeniem. Pobierz rezerwację po swoim numerze albo wylistuj ostatnie rezerwacje tych pasażerów, zanim zdecydujesz o kolejnej próbie.
  • Uruchom zadanie uzgadniające, które przegląda wszystko, co nadal ma stan nieznany, porównuje z tym, co raportuje dostawca, a czego nie potrafi rozstrzygnąć, kieruje do kolejki dla człowieka zamiast zgadywać.

Timeouty przy wystawianiu biletu to ten sam problem, tyle że z pieniędzmi. Jeśli obciążysz kartę przed wystawieniem, a wystawienie zawiśnie, masz klienta, który zapłacił, i być może brak biletu. Jeśli wystawisz bilet przed obciążeniem, a obciążenie się nie uda, masz dokument, za który ktoś musi zapłacić linii. Najpierw autoryzacja karty, potem wystawienie biletu, a obciążenie dopiero po sukcesie — to typowy schemat. Chodzi o to, żeby wybrać go świadomie, a nie odkryć na produkcji.

Pojęcia z branży lotniczej, które zaskakują programistów webowych

Żadne z nich nie jest trudne. Każde kosztowało kogoś tydzień, bo nie wiedział, że istnieje.

PNR to nie bilet

PNR to rekord rezerwacji: pasażerowie, segmenty, kontakty, termin. Bilet to opłacony dokument uprawniający pasażera do lotu. PNR bez biletu wygasa w terminie wystawienia, a miejsca wracają do sprzedaży — z twojej perspektywy czasem bez żadnego sygnału.

Nazwiska są prawie niezmienne

Po wystawieniu biletu większość taryf nie pozwala zmienić nazwiska poza drobną korektą, a to, co uchodzi za drobne, zależy od linii. Nazwisko musi zgadzać się z dokumentem podróży. Zbieraj nazwisko i imiona osobno, nie pozwól, by wpisany ręcznie tytuł trafił do pola z nazwiskiem, i waliduj przed wywołaniem book, a nie po nim.

Typ pasażera wpływa na cenę, to nie ozdoba

Dorosły, dziecko i niemowlę to typy taryf, a wiek, który decyduje o typie, to zwykle wiek w dniu podróży, nie w dniu rezerwacji. Niemowlę na kolanach zazwyczaj nie zajmuje miejsca i może podróżować tylko z dorosłym. Pomylisz typ, a krok price albo się nie powiedzie, albo poda złą taryfę.

Czasy są lokalne, a segmenty to nie odcinki

Godziny wylotu i przylotu podaje się w czasie lokalnym każdego lotniska. Nie przeliczaj ich na strefę czasową użytkownika przy wyświetlaniu i nie licz czasu podróży, odejmując je bez przesunięć strefowych. Podróż składa się z segmentów; segment z międzylądowaniem technicznym składa się z więcej niż jednego odcinka (leg). Twój UI i twoje dane muszą się zgadzać, które z nich jest „przesiadką”.

Po sprzedaży wciąż coś się dzieje

Linie zmieniają rozkłady po wystawieniu biletów. Rezerwacja, która była poprawna przy wystawieniu, kilka tygodni później może pokazywać nową godzinę, nowy numer lotu albo zerwane połączenie, a w zależności od dostawcy dowiadujesz się o tym z powiadomienia, z kolejki albo pobierając rezerwację ponownie. Zakładaj, że rezerwacja zmieni się, kiedy już przestaniesz na nią patrzeć.

Void to nie zwrot

Krótko po wystawieniu zwykle jest okno, w którym bilet można unieważnić (void) tak, jakby nigdy nie istniał. Po tym oknie możliwy jest już tylko zwrot zgodnie z zasadami taryfy, który może wiązać się z karą albo nie oddać nic. Okno i jego zasady należą do dostawcy i umowy, na podstawie której wystawiono bilet; przeczytaj je, zanim zbudujesz przycisk „anuluj”.

Ile kosztuje pomyłka

Błędy w integracji lotniczej są drogie w szczególny sposób: lądują na ludziach, nie w logach. Zdublowana rezerwacja zamienia się w telefon do linii i być może notę na koncie biura. Klient obciążony bez biletu to zwrot pieniędzy, reklamacja i ryzyko chargebacku. Bilet wystawiony bez udanej płatności to dług wobec linii, który ktoś musi uregulować. Zmiana rozkładu, której nikt nie obsłużył, to podróżny na lotnisku na lot, który odleciał wcześniej.

Nic z tego nie wyjdzie w teście happy path. Najpierw napisz ścieżki negatywne: timeout podczas rezerwacji, cenę, która wzrosła, bilet, który nie wyszedł po utworzeniu PNR, void po udanej płatności. Jeśli te są obsłużone, happy path to łatwa część.

Testowanie z API lotniczym

Środowiska testowe dostawców są przydatne i niekompletne. Zwykle panuje w nich mniejszy ruch niż na produkcji, więc wyprzedane klasy i zmiany cen zdarzają się rzadziej, a niektóre w ogóle nie symulują timeoutów. Używaj ich do sprawdzenia kształtu wywołań i błędów walidacji, a potem zaplanuj kontrolowany przebieg na produkcji z prawdziwymi rezerwacjami, które unieważniasz w oknie void — z działem operacji uprzedzonym, że to robisz.

Czy w ogóle integrować, to osobne pytanie. Jeśli tak naprawdę potrzebujesz serwisu sprzedażowego, a nie surowych zasobów we własnym systemie, kompromis opisuje tekst white label czy własny silnik rezerwacyjny, a to samo rozumowanie dotyczy portalu B2B dla subagentów. Jeśli chcesz mieć zasoby we własnym kodzie, ta platforma udostępnia API lotnicze i hotelowe, a dostęp zaczyna się od rozmowy o twoim przypadku użycia, a nie od klucza w samoobsłudze — i to jest też właściwy moment, żeby zadać każde z powyższych pytań.

Redakcja Tekravel

Dział technologii turystycznych

Dział technologii turystycznych Tekravel pisze dla branży: właścicieli agencji, konsolidatorów i deweloperów, którzy ich integrują. Każdy artykuł jest przed publikacją sprawdzany na platformie, którą opisuje.