Przejdź do treści
Blog

Obsługa błędów API silnika rezerwacji: trzy awarie, które kosztują pieniądze

Redakcja Tekravel
Napisano z pomocą AI

Zgłoszenie do supportu przychodzi w czwartek wieczorem. Klient zapłacił, strona się kręciła, a potem pokazała ogólny błąd. Karta została obciążona. W logach widać POST do dostawcy, na który nigdy nie przyszła odpowiedź. Czy linia lotnicza zablokowała miejsce? Nikt nie umie tego powiedzieć, a klient czeka. Dobra obsługa błędów API silnika rezerwacji to w dużej mierze praca nad tym, żeby nigdy nie znaleźć się w takiej sytuacji, albo przynajmniej wiedzieć dokładnie, co robić, gdy już się w niej znajdziesz.

Większość przewodników po integracji traktuje błędy jak katalog kodów statusu. W rezerwacjach kody to łatwa część. Pieniądze kosztuje niewielki zestaw sytuacji, w których żądanie wygląda na nieudane, a świat i tak się zmienił, albo wygląda na udane, a świat się nie zmienił. Trzy z nich ważą więcej niż reszta.

Awaria pierwsza: cena zmieniła się między wyszukiwaniem a rezerwacją

Wyniki wyszukiwania to wycena, nie umowa. Taryfy są buforowane, pula miejsc jest wspólna dla wszystkich kanałów, którymi sprzedaje dostawca, a kwota pokazana o 14:02 po kilku minutach może być nieaktualna. Dostawca informuje o tym na etapie tworzenia rezerwacji: czasem czystą odpowiedzią «taryfa zmieniona», czasem po cichu zwracając inną sumę w skądinąd udanej odpowiedzi.

Niebezpieczny jest drugi wariant. Jeśli kod odczyta potwierdzenie, zapisze rezerwację i obciąży klienta kwotą, którą widział, różnica wychodzi z Twojej marży, a później z ADM. Reguła jest prosta: porównuj sumę potwierdzoną przez dostawcę z sumą zaakceptowaną przez klienta, za każdym razem, w kodzie, zanim pobierzesz płatność.

Co zrobić przy rozbieżności, zależy od jej wielkości i od tego, kto ją ponosi. Kilka groszy zaokrąglenia między walutami to tolerancja ustawiana raz. Wszystko większe wraca do klienta jako nowa cena z wyraźnym przyciskiem akceptacji. Nigdy nie pochłaniaj tego automatycznie i nigdy nie pobieraj automatycznie.

Awaria druga: zarezerwowane, ale niewystawione

Istnienie PNR to nie to samo, co istnienie biletu. Wiele przepływów najpierw tworzy rezerwację, a e-bilet wystawia w osobnym kroku, z limitem czasu pomiędzy nimi. Jeśli płatność przejdzie, a wystawienie zawiedzie, trzymasz pieniądze klienta i rezerwację, która wygaśnie według własnego zegara.

Ta awaria rzadko jest głośna. Wywołanie wystawienia zwraca błąd lub timeout, a rezerwacja tkwi w stanie, który Twoja baza nazywa «opłacona», podczas gdy dostawca nadal mówi «wstrzymana». Tymczasem limit wystawienia biegnie, i w odróżnieniu od Twojej kolejki zgłoszeń linia lotnicza nie czeka.

Traktuj to jako osobny stan, nie wariant sukcesu czy porażki. Rezerwacja potrzebuje co najmniej takich stanów: utworzona, wstrzymana, płatność pobrana, wystawianie, wystawiona, nieudana-i-do-zwrotu. «Płatność pobrana, wystawianie» to stan wymagający timera: gdy rezerwacja siedzi w nim zbyt długo, zadanie powinno ponownie odczytać rezerwację u dostawcy i zdecydować, zamiast czekać, aż człowiek to zauważy. Decyzja jest tania, gdy znasz limit czasu dostawcy, bo mówi on, jak długo możesz bezpiecznie ponawiać, zanim trzeba zwrócić pieniądze.

Awaria trzecia: timeout z nieznanym wynikiem

To zgłoszenie z czwartkowego wieczoru. Żądanie wyszło; odpowiedź nie wróciła; połączenie padło albo brama się poddała. Dostawca mógł przetworzyć je w całości, częściowo lub wcale.

Kuszące jest ponowienie. Nie ponawiaj ślepo wywołania tworzącego rezerwację, bo druga próba może dać drugą rezerwację, a duplikat to realny koszt: dwa zablokowane miejsca, może dwa wystawione bilety, spór o zwrot przy jednym z nich.

Bezpieczna kolejność to: zatrzymać, odczytać, zdecydować. Zatrzymaj przepływ widoczny dla klienta uczciwym stanem «potwierdzamy Twoją rezerwację». Odczytaj stronę dostawcy, wyszukując rezerwację po referencji wygenerowanej przed wywołaniem (dlatego najpierw tworzysz własną referencję klienta i wysyłasz ją, jeśli dostawca ją przyjmuje). Dopiero potem decyduj: znaleziona oznacza kontynuację z prawdziwego stanu; nieznaleziona po upływie okna przetwarzania dostawcy oznacza, że można raz bezpiecznie ponowić.

Jeśli dostawca nie pozwala szukać po Twojej referencji, szukaj po nazwisku pasażera, trasie i dacie w wąskim oknie i uznaj dopasowanie za znalezione. Brzydkie, ale znacznie tańsze niż duplikat.

Tabela decyzji, z którą możesz się nie zgodzić

Co widziszCo wieszCo zrobićCzego nie robić
Dostawca zwraca «taryfa zmieniona»Nic nie zarezerwowanoPokaż nową sumę, poproś o akceptację, uruchom tworzenie ponownieUruchamiać ponownie ze starą ceną w nadziei, że przejdzie
Sukces, ale suma różni się od zaakceptowanej przez klientaIstnieje rezerwacja w nowej cenieWstrzymaj płatność, zapytaj klienta, anuluj rezerwację, jeśli odmówiPobrać starą kwotę i połknąć różnicę
Płatność pobrana, wywołanie wystawienia kończy się błędemIstnieje PNR, status biletu nieznanyOdczytaj rezerwację ponownie, ponów wystawienie w limicie, po nim zwróć pieniądzeOznaczyć rezerwację jako nieudaną i zapomnieć o PNR
Timeout przy tworzeniuWynik nieznanySzukaj po własnej referencji, potem kontynuuj lub ponów razNatychmiastowe ślepe ponowienie
Timeout przy anulowaniuMożesz nadal odpowiadać za odcinekSprawdź status ponownie, zanim cokolwiek powiesz klientowiPokazać «anulowano», bo kliknięcie się odbyło

Jeden wiersz, z którym można się spierać: niektóre zespoły zwracają pieniądze przy pierwszym błędzie wystawienia, żeby uspokoić klienta. To do obrony przy tanich biletach i zły nawyk przy drogich, bo można stracić taryfę, którą minutę później dałoby się uratować.

Ile kosztuje błąd

Każda awaria ma inny rachunek. Przeoczona zmiana ceny to utracona marża na każdej dotkniętej rezerwacji, często zauważona dopiero przy uzgadnianiu. Przypadek zarezerwowane-niewystawione to klient, który przychodzi na lotnisko z wygasłą rezerwacją i obciążeniem na karcie, czyli chargeback i problem wizerunkowy naraz. Ślepe ponowienie po timeoucie to zdublowana rezerwacja, a linie lotnicze audytują duplikaty; ich seria to rzecz, która kończy się w ADM.

Nic z tego nie jest egzotyczne. To mało efektowna hydraulika, która oddziela demo od czegoś, co można zostawić włączone na weekend.

Zbuduj zadanie uzgadniające, zanim będzie potrzebne

Wszystkie trzy awarie kończą się tak samo: Twoja baza i baza dostawcy się nie zgadzają. Napisz więc zadanie, które je porównuje, przed pierwszym incydentem, nie po nim. Nocne uruchomienie to minimum; co kilka minut dla wszystkiego w stanie przejściowym jest lepiej. Zadanie wypisuje rezerwacje utknięte we wstrzymanych, wystawianiu lub nieznanych, pyta dostawcę o jego zdanie i naprawia rekord albo zakłada zgłoszenie z dołączonymi dowodami.

Przechowuj każde żądanie i odpowiedź wywołań rezerwacji, także timeouty, razem z wysłaną referencją. Gdy klient kwestionuje obciążenie, ten log jest Twoim argumentem. Utrzymuje też uczciwość rozmowy o opóźnieniach: zobacz co możesz, a czego nie możesz naprawić w opóźnieniach API, by zrozumieć, dlaczego timeouty to fakt życia, a nie błąd do wyeliminowania.

Jeśli wciąż decydujesz, jak podłączyć samo połączenie z dostawcą, omówienie w integracji API rezerwacji lotów obejmuje kolejność wywołań, którą zakłada ten artykuł. A jeśli chcesz porozmawiać o tym, jak te stany mapują się na nasze API lotów i hoteli, dostęp zaczyna się od rozmowy: zobacz stronę API podróżnych.

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.