اتصال API رزرو بلیط هواپیما: آنچه مستندات نمیگویند

تسکی که روی بورد آمده میگوید «پرواز اضافه کن». شما قبلاً درگاه پرداخت وصل کردهاید، محاسبهٔ هزینهٔ ارسال، شاید نقشه هم، و مدلی که در ذهن دارید سادهترینِ ممکن است: جستوجو، نمایش نتایج، کسر از کارت، تمام. بعد اولین رزرو واقعی با قیمتی متفاوت از صفحهٔ نتایج برمیگردد، دومی تایماوت میخورد و هیچکس نمیتواند بگوید مشتری صندلی دارد یا نه، و کسی از بخش عملیات میپرسد چرا رزرو هست ولی بلیط نیست. اتصال API رزرو بلیط هواپیما از بیرون شبیه صفحهٔ پرداخت یک فروشگاه اینترنتی است. در زیرِ آن، یک تراکنش توزیعشده با سیستمهایی است که مدتها پیش از REST طراحی شدهاند، و بیشتر غافلگیریها از همین فاصله میآید.
این نوشته برای توسعهدهندهای است که هرگز PNR ندیده. دربارهٔ اندپوینتهای یک تأمینکنندهٔ خاص نیست؛ نامها از یک ارائهدهنده به دیگری عوض میشوند، شکل کار نه.
ترتیب فراخوانیها در اتصال API رزرو بلیط هواپیما
تقریباً هر API پروازی، هر اسمی که روی متدهایش گذاشته باشد، از همان چهار مرحله میگذرد. درست کشیدن مرز میان این مراحل بیشترِ کار است.
| مرحله | آنچه میگیرید | آنچه باید ذخیره کنید | آنچه خراب میشود |
|---|---|---|---|
| جستوجو | مسیرهای سفر با قیمت و یک کلید پیشنهاد یا نرخ که محتوایش خوانا نیست | هیچ چیز ماندگار — نتایج زود کهنه میشوند | قیمت را نهایی فرض میکنید؛ کلید پیش از پرداخت منقضی میشود |
| استعلام / تأیید قیمت | قیمت تأییدشده، قوانین نرخ، بار مجاز، گاهی فیلدهای اجباری مسافر | پیشنهاد تأییدشده و زمان انقضایش | قیمت عوض شده؛ کلاس پر شده؛ قوانین با آنچه نشان دادید فرق دارد |
| رزرو | یک رزرو — PNR — با کد رزرو و مهلت صدور بلیط | شمارهٔ مرجع خودتان، کد رزرو، مهلت، و دقیقاً همان اطلاعات مسافری که فرستادید | تایماوت بیپاسخ؛ PNR تکراری؛ رد شدن نامها |
| صدور بلیط | شمارههای بلیط الکترونیکی صادرشده؛ اینجاست که پول واقعاً متعهد میشود | تکتک شمارههای بلیط، متصل به مسافر و سگمنت مربوط | صدور ناقص؛ لغو رزرو از سوی ایرلاین چون مهلت گذشته |
ردیفی که سرش بحث میشود سومی است، چون بسیاری از APIها اجازه میدهند رزرو و صدور را در یک فراخوانی انجام دهید. اگر خواستید استفاده کنید. اما در دنیای ایرلاینها این دو همچنان جدا هستند: PNR میتواند بدون بلیط وجود داشته باشد، و صدور بلیط میتواند پس از ساخته شدن PNR شکست بخورد. اندپوینت ترکیبی فقط لحظهای را پنهان میکند که یکی موفق شده و دیگری نه، پس مدل دادهتان همچنان باید جایی برای آن وضعیت داشته باشد.
به این هم دقت کنید که جستوجو چه چیزی برنمیگرداند: قول. نتیجهٔ جستوجو تبلیغ است. مرحلهٔ استعلام، پیشفاکتور است و فقط بلیط، فروش.
چرا قیمت جستوجو قیمت رزرو نیست
توسعهدهندهٔ وب انتظار یک کاتالوگ را دارد. موجودی ایرلاین کاتالوگ نیست. هر پرواز در کلاسهای رزرو فروخته میشود؛ هر کلاس سطلی از صندلیها با یک نرخ است و ایرلاین با پر شدن هواپیما این سطلها را پیوسته باز و بسته میکند. نتایج جستوجو بهسرعت از اطلاعات ظرفیتی سرهم میشوند که ممکن است کمی عقب باشد؛ تا کاربر اطلاعات دو گذرنامه را تایپ کند، ارزانترین کلاس آن پرواز شاید بسته شده باشد. مرحلهٔ استعلام دوباره میپرسد، و پاسخ صادقانه گاهی گرانتر است.
مالیاتها هم جابهجایی خودشان را دارند. در مرحلهٔ استعلام برای مسافران و مسیر دقیق دوباره محاسبه میشوند، و کودک یا نوزاد قیمتی متفاوت از بزرگسالی دارد که جستوجو فرض کرده بود. اگر فروشگاه شما قیمت را به تومان نشان میدهد و تأمینکننده به ارز دیگری نرخ میدهد، تبدیل ارز یک جای دیگر است که عدد تکان میخورد.
نتیجهٔ طراحی ساده است و اغلب نادیده گرفته میشود: هرگز بر اساس قیمت جستوجو پول کسر نکنید. پیش از پرداخت استعلام بگیرید، مقایسه کنید، و اگر مبلغ عوض شد، عدد جدید را نشان دهید و تأیید بگیرید. هر مارکآپی که میگذارید باید روی نرخ جدید از نو حساب شود، نه اینکه از صفحهٔ نتایج منتقل شود — منطقش همان است که یک آژانس هنگام تعیین استراتژی مارکآپ آنلاین طی میکند، و وقتی پایهٔ قیمت زیرش جابهجا شود به همان شکل میشکند.
Idempotency، و معنای تایماوت هنگام رزرو
این بخش را دو بار بخوانید.
وقتی فراخوانی رزرو تایماوت میخورد، نمیدانید چه اتفاقی افتاده. شاید درخواست اصلاً نرسیده. شاید رسیده و شکست خورده. یا — حالتی که درد دارد — رسیده، تأمینکننده PNR را در ایرلاین ساخته، و پاسخ در راه برگشت گم شده. برای کد شما هر سه یکسان به نظر میرسند. برای ایرلاین، سومی یک رزرو زنده است که به نام مشتری شما صندلی نگه داشته.
عادتی که از اتصالهای دیگر آمده، تلاش دوباره است. اینجا تلاش دوبارهٔ کورکورانه میتواند PNR دومی برای همان مسافران روی همان پرواز بسازد. ایرلاینها رزرو تکراری را نقض قوانین میدانند؛ بسته به ایرلاین و قراردادهای آژانس، پیامدش از لغو خودکار یکی یا هر دو رزرو تا یک یادداشت بدهی — ADM — به صادرکننده متغیر است. آژانسی که آن را دریافت کند میخواهد بداند چرا سیستم شما دو بار رزرو کرده است.
آنچه جواب میدهد، تقریباً به این ترتیب:
- پیش از فراخوانی بیرونی، شمارهٔ مرجع رزرو خودتان را بسازید، ذخیرهاش کنید و هر جا API مرجع سمت کلاینت میپذیرد، همراه درخواست بفرستید. اگر API از کلید idempotency پشتیبانی میکند از آن استفاده کنید؛ اگر نه، مرجع شما همچنان ابزار پیدا کردن رزرو در ادامه است.
- وضعیت «نامعلوم» را صریحاً مدل کنید. در انتظار، تأییدشده، ناموفق — و نامعلوم. تایماوت رزرو را به نامعلوم میبرد، نه به ناموفق.
- وضعیت نامعلوم را با پرسیدن حل کنید، نه با تکرار. پیش از تصمیم به تلاش دوباره، رزرو را با مرجع خودتان بازیابی کنید یا فهرست رزروهای اخیر همان مسافران را بگیرید.
- یک جاب تطبیق اجرا کنید که هر چیزِ هنوز نامعلوم را مرور کند، با گزارش تأمینکننده مقایسه کند و آنچه را نمیتواند حل کند به صف بررسی انسانی بفرستد، به جای حدس زدن.
تایماوت در صدور بلیط همان مسئله است، این بار با پول. اگر پیش از صدور از کارت کسر کنید و صدور گیر کند، مشتریای دارید که پول داده و شاید بلیط ندارد. اگر پیش از کسر وجه بلیط صادر کنید و کسر وجه شکست بخورد، سندی صادر کردهاید که کسی باید پولش را به ایرلاین بدهد. الگوی رایج این است: اول مجوز کارت، بعد صدور، و در صورت موفقیت برداشت نهایی — نکته این است که آگاهانه تصمیم بگیرید، نه اینکه در محیط عملیاتی کشفش کنید.
مفاهیم هوایی که توسعهدهندگان وب را غافلگیر میکند
هیچکدام سخت نیست. هر کدام یک هفته از وقت کسی را گرفته، چون نمیدانست چنین چیزی وجود دارد.
PNR بلیط نیست
PNR رکورد رزرو است: مسافران، سگمنتها، اطلاعات تماس، مهلت. بلیط سند پرداختشدهای است که به مسافر حق پرواز میدهد. PNR بدون بلیط در مهلتش منقضی میشود و صندلیها دوباره به فروش میروند، گاهی از نگاه شما بیسروصدا.
نام تقریباً تغییرناپذیر است
پس از صدور، بیشتر نرخها جز یک اصلاح جزئی اجازهٔ تغییر نام نمیدهند، و اینکه چه چیزی جزئی حساب میشود از ایرلاینی به ایرلاین دیگر فرق دارد. نام باید با مدرک سفر یکی باشد. نام خانوادگی و نام را جدا بگیرید، املای لاتین را دقیقاً مطابق گذرنامه وارد کنید، نگذارید عنوانی مثل «آقای» یا «دکتر» از فیلد متنی آزاد به فیلد نام نشت کند، و اعتبارسنجی را پیش از فراخوانی رزرو انجام دهید، نه بعد از آن.
ردهٔ مسافر قیمت دارد، تزئینی نیست
بزرگسال، کودک و نوزاد ردههای نرخاند، و سنی که تعیینکننده است معمولاً سن در روز پرواز است، نه روز رزرو. نوزادی که روی پا مینشیند معمولاً صندلی اشغال نمیکند و فقط همراه بزرگسال میتواند سفر کند. رده را اشتباه بزنید، استعلام یا شکست میخورد یا نرخ غلط میدهد.
ساعتها محلیاند، و سگمنت همان لگ نیست
ساعت حرکت و رسیدن به وقت محلی هر فرودگاه داده میشود. برای نمایش آنها را به منطقهٔ زمانی کاربر تبدیل نکنید، و مدت سفر را با تفریق ساده و بدون اختلاف ساعت حساب نکنید. هر سفر از سگمنتها تشکیل میشود؛ سگمنتی که توقف فنی دارد بیش از یک لگ دارد. رابط کاربری و دادهتان باید توافق کنند که «توقف» به کدامیک گفته میشود.
اتفاقها بعد از فروش هم میافتند
ایرلاینها پس از صدور بلیط هم برنامهٔ پرواز را تغییر میدهند. رزروی که هنگام صدور درست بود ممکن است چند هفته بعد ساعت جدید، شمارهٔ پرواز جدید یا اتصالی قطعشده نشان دهد، و بسته به تأمینکننده از طریق اعلان، صف یا بازیابی دوبارهٔ رزرو از آن باخبر میشوید. طراحی را بر این فرض بگذارید که رزرو پس از آنکه دیگر نگاهش نمیکنید هم تغییر میکند.
ابطال (void) استرداد نیست
کمی پس از صدور معمولاً بازهای هست که میشود بلیط را void کرد، انگار هرگز صادر نشده. پس از آن فقط استرداد طبق قوانین نرخ ممکن است، که شاید جریمه داشته باشد یا هیچ مبلغی برنگرداند. این بازه و قوانینش مال تأمینکننده و قرارداد صدور است؛ پیش از ساختن دکمهٔ «لغو» آنها را بخوانید.
هزینهٔ اشتباه
خطاهای اتصال پرواز به شکل خاصی گراناند: روی دوش آدمها میافتند، نه در لاگها. رزرو تکراری یعنی تماس تلفنی با ایرلاین و شاید یادداشت بدهی علیه حساب آژانس. مشتریِ پولداده بدون بلیط یعنی استرداد، شکایت و خطر chargeback. بلیطی که بدون پرداخت موفق صادر شده یعنی بدهی به ایرلاین که کسی باید تسویهاش کند. تغییر برنامهای که کسی پردازشش نکرده یعنی مسافری در فرودگاه برای پروازی که زودتر رفته است.
هیچکدام از اینها در تست مسیر خوشبینانه دیده نمیشود. اول مسیرهای ناخوشایند را بنویسید: تایماوت هنگام رزرو، قیمتی که بالا رفت، بلیطی که پس از ساخته شدن PNR شکست خورد، void پس از پرداخت موفق. اگر اینها مدیریت شده باشند، مسیر خوشبینانه بخش آسان کار است.
تست در برابر API پرواز
محیطهای تست تأمینکنندگان مفیدند و ناقص. معمولاً از محیط عملیاتی خلوتترند، پس پر شدن کلاسها و تغییر قیمت کمتر رخ میدهد، و برخی اصلاً تایماوت را شبیهسازی نمیکنند. از آنها برای شکل فراخوانیها و خطاهای اعتبارسنجی استفاده کنید، سپس یک اجرای کنترلشده در محیط عملیاتی برنامهریزی کنید با رزروهای واقعی که درون بازهٔ مجاز void میکنید — و بخش عملیات در جریان باشد.
اینکه اصلاً اتصال بزنید یا نه، پرسش جداگانهای است. اگر آنچه واقعاً لازم دارید یک وبسایت فروش است و نه موجودی خام در سیستم خودتان، سبکسنگین کردنش در وایتلیبل یا ساخت موتور رزرو اختصاصی آمده، و همان استدلال دربارهٔ پورتال B2B برای آژانسهای همکار هم صدق میکند. اگر واقعاً موجودی را در کد خودتان میخواهید، این پلتفرم API پرواز و هتل ارائه میدهد، و دسترسی با گفتوگو دربارهٔ کاربرد شما شروع میشود، نه با یک کلید سلفسرویس — که همان لحظهٔ مناسب برای پرسیدن تکتک سؤالهای بالا هم هست.