Məzmuna keçin
Bloq

Aviabilet bron API inteqrasiyası: sənədlərin demədikləri

Tekravel Redaksiyası
Süni intellektin köməyi ilə yazılıb

Lövhədəki tapşırıqda qısaca yazılıb: "aviabiletləri əlavə et". Siz artıq ödəniş şlüzü, çatdırılma tariflərinin hesablanması, bəlkə də xəritə inteqrasiyası qurmusunuz və başınızdakı model aydındır: axtarış, nəticələr, kartdan ödəniş, vəssalam. Sonra ilk real bron nəticələr səhifəsindəkindən fərqli qiymətlə qayıdır, ikincisi timeout-a düşür və heç kim müştərinin yeri olub-olmadığını deyə bilmir, əməliyyat şöbəsindən isə kimsə soruşur ki, niyə rezervasiya var, amma bilet yoxdur. Aviabilet bron API inteqrasiyası kənardan adi onlayn mağaza checkout-una bənzəyir. İçəridə isə bu, REST-dən çox-çox əvvəl layihələndirilmiş sistemlərlə paylanmış tranzaksiyadır və sürprizlərin çoxu məhz bu boşluqdan çıxır.

Bu yazı PNR-ı heç vaxt görməmiş developer üçündür. Söhbət konkret bir təchizatçının endpoint-lərindən getmir: adlar provayderdən provayderə dəyişir, forma isə dəyişmir.

Aviabilet bron API inteqrasiyası: çağırışların ardıcıllığı

Demək olar ki, hər bir aviasiya API-si, metodlarını necə adlandırmasından asılı olmayaraq, eyni dörd addımdan keçir. Onların arasındakı sərhədləri düzgün çəkmək işin böyük hissəsidir.

AddımNə qaytarırNəyi saxlamalısınızNə pozulur
AxtarışQiyməti və qeyri-şəffaf təklif və ya tarif açarı olan marşrutlarUzunömürlü heç nə — nəticələr tez köhnəlirQiyməti son qiymət sayırsınız; açarın müddəti checkout-dan əvvəl bitir
Qiymətin təsdiqiTəsdiqlənmiş qiymət, tarif qaydaları, baqaj, bəzən sərnişin üçün məcburi sahələrTəsdiqlənmiş təklif və onun bitmə vaxtıQiymət dəyişib; sinif satılıb qurtarıb; qaydalar göstərdiyinizdən fərqlidir
BronRezervasiya — PNR — rezervasiya kodu (record locator) və biletin yazılma son tarixi iləÖz referansınız, lokator, son tarix, göndərilən sərnişin məlumatlarının dəqiq surətiCavabsız timeout; dublikat PNR-lar; adlar rədd edilir
Biletin yazılmasıVerilmiş elektron bilet nömrələri; pul məhz burada həqiqətən öhdəliyə çevrilirHər bilet nömrəsi, aid olduğu sərnişin və seqmentə bağlı şəkildəQismən yazılma; son tarix keçdiyi üçün aviaşirkət rezervasiyanı ləğv edib

Ən çox mübahisə doğuran üçüncü sətirdir, çünki bir çox API bronu və biletin yazılmasını bir çağırışda etməyə imkan verir. İstəyirsinizsə, istifadə edin. Aviaşirkətin dünyasında isə bunlar yenə ayrı-ayrı şeylərdir: PNR biletsiz mövcud ola bilər, bilet isə PNR yaradıldıqdan sonra uğursuz ola bilər. Birləşmiş endpoint sadəcə birinin alındığı, digərinin alınmadığı anı gizlədir, ona görə də data modelinizdə bu vəziyyət üçün yenə yer olmalıdır.

Axtarışın nəyi qaytarmadığına da diqqət edin: vədi. Axtarış nəticəsi reklamdır. Qiymət addımı kotirovkadır, satış isə yalnız biletdir.

Niyə axtarışdakı qiymət bron etdiyiniz qiymət deyil

Veb developerlər kataloq gözləyirlər. Aviaşirkətin inventarı kataloq deyil. Reys bron siniflərinə bölünərək satılır — hər biri müəyyən tarifdə yerlərdən ibarət "səbət"dir və aviaşirkət reys doldurulduqca bu səbətləri fasiləsiz açıb-bağlayır. Axtarış nəticələri artıq bir az geridə qala bilən mövcudluq məlumatından tez yığılır; istifadəçi iki pasportun məlumatlarını daxil edənədək həmin reysdə ən ucuz səbət bağlana bilər. Qiymət addımı işə düşəndə sistem yenidən soruşur və dürüst cavab bəzən daha yüksək olur.

Vergilər də öz sürüşməsini əlavə edir. Onlar qiymətləndirmə zamanı dəqiq sərnişinlər və marşrut üçün yenidən hesablanır, uşaq və ya körpə isə axtarışın nəzərdə tutduğu böyükdən fərqli qiymətlənir. Vitrininiz təchizatçının kotirovka verdiyi valyutadan fərqli valyuta göstərirsə, valyuta konvertasiyası rəqəmin dəyişdiyi daha bir yerdir.

Dizayn üçün nəticə sadədir və tez-tez unudulur: heç vaxt axtarış qiyməti ilə ödəniş almayın. Ödənişdən əvvəl qiymət addımını işə salın, müqayisə edin, məbləğ dəyişibsə, yeni rəqəmi göstərin və təsdiq istəyin. Tətbiq etdiyiniz hər hansı əlavə qiymət (markup) nəticələr səhifəsindən daşınmamalı, yenidən qiymətləndirilmiş tarif üzərində təzədən hesablanmalıdır — bu, agentliyin onlayn əlavə qiymət strategiyası qurarkən keçdiyi eyni məntiqdir və baza altından dəyişəndə eyni cür pozulur.

İdempotentlik və bron zamanı timeout nə deməkdir

Bu bölməni iki dəfə oxuyun.

Bron çağırışı timeout-a düşəndə nə baş verdiyini bilmirsiniz. Sorğu heç çatmamış ola bilər. Çatıb uğursuz olmuş ola bilər. Ya da — ən ağrılı hal — çatıb, təchizatçı aviaşirkətdə PNR yaradıb, cavab isə sizə qayıdarkən itib. Kodunuz üçün hər üç hal eyni görünür. Aviaşirkət üçün isə üçüncüsü müştərinizin adına yerləri tutan canlı rezervasiyadır.

Digər inteqrasiyalardan qalan refleks təkrar cəhd etməkdir. Burada kor-koranə təkrar cəhd eyni reysdə eyni sərnişinlər üçün ikinci PNR yarada bilər. Aviaşirkətlər dublikat bronları qayda pozuntusu sayır; aviadaşıyıcıdan və agentliyin müqavilələrindən asılı olaraq nəticə bir və ya hər iki rezervasiyanın avtomatik ləğvindən tutmuş onları yazana göndərilən debet memoya — ADM-ə qədər dəyişir. Onu alan agentlik sisteminizin niyə iki dəfə bron etdiyini bilmək istəyəcək.

Təxminən bu ardıcıllıqla işləyən üsullar:

  • Kənar çağırışdan əvvəl öz bron referansınızı yaradın, onu saxlayın və API müştəri referansını qəbul etdiyi hər yerdə sorğu ilə göndərin. API idempotentlik açarını (idempotency key) dəstəkləyirsə, ondan istifadə edin; dəstəkləmirsə, sonradan bronu tapmağa imkan verən yenə sizin referansınızdır.
  • Naməlum vəziyyəti açıq şəkildə modelləşdirin. Gözləmədə, təsdiqlənib, uğursuz — və naməlum. Timeout bronu uğursuz yox, naməlum vəziyyətinə keçirir.
  • Naməlumu təkrarlamaqla yox, soruşmaqla həll edin. Yenidən cəhd edib-etməmək barədə qərar verməzdən əvvəl bronu öz referansınızla sorğulayın və ya həmin sərnişinlər üzrə son bronların siyahısını alın.
  • Uzlaşdırma (reconciliation) tapşırığı işlədin: o, hələ də naməlum qalan hər şeyi toplayıb təchizatçının hesabatı ilə müqayisə etsin, həll edə bilmədiyini isə təxmin etmək əvəzinə insanların növbəsinə ötürsün.

Biletin yazılması zamanı timeout-lar eyni problemdir, sadəcə işin içində pul var. Kartdan pulu biletin yazılmasından əvvəl tutursunuzsa və yazılma ilişib qalırsa, ödəniş etmiş, amma bəlkə də bileti olmayan müştəriniz var. Bileti ödənişin tutulmasından əvvəl yazırsınızsa və tutulma uğursuz olursa, kiminsə aviaşirkətə pulunu ödəməli olduğu sənədi vermiş olursunuz. Əvvəlcə kartda məbləği avtorizasiya etmək, bileti yazmaq, sonra uğur olduqda pulu tutmaq geniş yayılmış sxemdir — məsələ bunu prodakşnda kəşf etmək yox, şüurlu şəkildə qərara almaqdır.

Veb developerləri təəccübləndirən səyahət anlayışları

Bunların heç biri çətin deyil. Hər biri kiməsə bir həftəyə başa gəlib, çünki o, belə bir şeyin mövcud olduğunu bilmirdi.

PNR bilet deyil

PNR rezervasiya qeydidir: sərnişinlər, seqmentlər, kontaktlar, son tarix. Bilet isə sərnişinə uçmaq hüququ verən ödənilmiş sənəddir. Bileti yazılmamış PNR biletin yazılma son tarixində bitir və yerlər yenidən satışa çıxır — bəzən sizin tərəfdə heç nə hiss olunmadan.

Adları demək olar ki, dəyişmək olmur

Bilet yazıldıqdan sonra əksər tariflər kiçik düzəlişdən başqa ad dəyişikliyinə icazə vermir, nəyin kiçik düzəliş sayılması qaydaları isə aviaşirkətdən aviaşirkətə dəyişir. Ad səyahət sənədindəki ilə üst-üstə düşməlidir. Soyadı və adları ayrıca toplayın, sərbəst mətnli müraciət formasının ad sahəsinə sızmasına imkan verməyin və yoxlamanı bron çağırışından sonra yox, əvvəl edin.

Sərnişin tipləri bəzək deyil, qiymətə təsir edir

Böyük, uşaq və körpə tarif tipləridir və hansının tətbiq olunduğunu həll edən yaş adətən bron tarixindəki yox, səyahət tarixindəki yaşdır. Qucaqda uçan körpə adətən yer tutmur və yalnız böyüklə birlikdə uça bilər. Tipi səhv göstərsəniz, qiymət addımı ya xəta verəcək, ya da səhv tarif qaytaracaq.

Vaxtlar yerlidir, seqmentlər isə uçuş hissələri (leg) deyil

Uçuş və eniş vaxtları hər hava limanının yerli vaxtı ilə verilir. Onları göstərmək üçün istifadəçinin saat qurşağına çevirməyin və müddəti ofsetləri nəzərə almadan sadə çıxma ilə hesablamayın. Səyahət seqmentlərdən ibarətdir; texniki enişi olan seqment birdən çox uçuş hissəsindən (leg) ibarətdir. İnterfeysiniz və datanız bunlardan hansının "dayanacaq" sayıldığında razılaşmalıdır.

Satışdan sonra da hadisələr baş verir

Aviaşirkətlər biletlər yazıldıqdan sonra cədvəlləri dəyişir. Bilet yazılan anda düzgün olan bron həftələr sonra yeni vaxt, yeni reys nömrəsi və ya qırılmış birləşmə göstərə bilər və təchizatçıdan asılı olaraq bu barədə bildiriş, növbə vasitəsilə və ya bronu yenidən sorğulayaraq xəbər tutursunuz. Siz bron haqqında düşünməyi dayandırdıqdan sonra onun dəyişəcəyini əvvəlcədən nəzərə alın.

Void geri qaytarma deyil

Bilet verildikdən qısa müddət sonra adətən elə bir pəncərə olur ki, bileti heç mövcud olmamış kimi ləğv etmək (void) mümkündür. Bu pəncərədən sonra yalnız tarif qaydalarına uyğun geri qaytarma (refund) mümkündür və bu, cərimə ilə olar, ya da heç nə qaytarmaya bilər. Pəncərə və onun qaydaları təchizatçıya və bilet yazma müqaviləsinə aiddir; "ləğv et" düyməsini qurmazdan əvvəl onları oxuyun.

Səhvin qiyməti

Aviasiya inteqrasiyasındakı uğursuzluqlar özünəməxsus şəkildə baha başa gəlir: onlar loglara yox, insanların üstünə düşür. Dublikat bron aviaşirkətə telefon zənginə və bəlkə də agentliyin hesabına qarşı memoya çevrilir. Pulu tutulmuş, amma bileti olmayan müştəri geri ödəmə, şikayət və chargeback riskinə çevrilir. Uğurlu ödəniş olmadan yazılmış bilet kiminsə bağlamalı olduğu aviaşirkət borcuna çevrilir. Heç kimin emal etmədiyi cədvəl dəyişikliyi daha tez uçmuş reys üçün hava limanında dayanan sərnişinə çevrilir.

Bunların heç biri "xoşbəxt yol" testində görünmür. Əvvəlcə uğursuz ssenariləri yazın: bron zamanı timeout, qalxmış qiymət, PNR-dan sonra uğursuz olmuş bilet, uğurlu ödənişdən sonra void. Bunlar həll olunubsa, xoşbəxt yol işin asan hissəsidir.

Aviasiya API-si ilə test

Təchizatçıların test mühitləri faydalıdır, amma natamamdır. Onlar adətən prodakşndan sakit olur, ona görə də satılıb qurtarmış siniflər və qiymət dəyişiklikləri daha nadir rast gəlinir, bəziləri isə timeout-ları ümumiyyətlə simulyasiya etmir. Onlardan çağırışların forması və validasiya xətaları üçün istifadə edin, sonra prodakşnda real bronlarla nəzarətli sınaq planlaşdırın və onları pəncərə daxilində void edin — əməliyyat şöbəsi bunu etdiyinizdən xəbərdar olmaqla.

Ümumiyyətlə inteqrasiya etmək lazımdırmı — bu, ayrı sualdır. Əgər sizə əslində öz sisteminizdə xam inventar yox, vitrin lazımdırsa, seçim white label və ya öz booking engine-inizi qurmaq yazısında açılıb, eyni məntiq subagentlər üçün B2B portalına da aiddir. İnventarı öz kodunuzda istəyirsinizsə, bu platforma aviabilet və otel API-ləri təqdim edir və giriş özünəxidmət açarı ilə yox, istifadə ssenariniz barədə söhbətlə başlayır — yuxarıdakı sualların hər birini vermək üçün də ən doğru an elə budur.

Tekravel Redaksiyası

Səyahət texnologiyaları masası

Tekravel-in səyahət texnologiyaları masası sənaye üçün yazır: agentlik sahibləri, konsolidatorlar və onları inteqrasiya edən developerlər. Hər məqalə dərc olunmazdan əvvəl təsvir etdiyi platformada yoxlanılır.