דילוג לתוכן
בלוג

API לזמינות מלונות: תכנון לספקים איטיים

מערכת Tekravel
נכתב בסיוע בינה מלאכותית

המשימה מגיעה בדרך כלל בניסוח תמים: "להוסיף חיפוש מלונות לעמוד ההזמנה — הספק נתן לנו API לזמינות מלונות, יש סביבת sandbox, זה ספרינט אחד." אתם קוראים את התיעוד, שולחים בקשה לשני מבוגרים באילת לשלושה לילות, ותשובה חוזרת. אחר כך אתם שולחים את אותה בקשה לעיר עם הרבה יותר בתי מלון, ובמשך זמן ארוך ומביך לא חוזר כלום. כשהתשובה מגיעה סוף סוף, זה מסמך גדול מספיק כדי שה-parser של ה-JSON שלכם יתחיל לחשוב מחדש על בחירת הקריירה שלו.

ברגע הזה העבודה משנה את צורתה. זמינות מלונות היא לא שליפה פשוטה. היא fan-out: שאלה אחת של המשתמש הופכת לשאלות רבות לספקים רבים, וכל אחד עונה בקצב שלו, באוצר המילים שלו ועם ההגדרה שלו למה זה "חדר". הלקוח שאתם בונים צריך להישאר שימושי כל עוד הפיזור הזה עוד לא הסתיים. המאמר הזה עוסק בתכנון הלקוח הזה, והוא נכתב למפתחים שמכירים היטב REST ו-JSON, אבל מעולם לא נאלצו להסביר למלון למה תעריף שאינו ניתן להחזר הוצג לאורח כביטול חינם.

למה API לזמינות מלונות איטי יותר מה-endpoints שאתם רגילים אליהם

חיפוש טיסות וחיפוש מלונות נראים דומים מבחוץ: שאילתה יוצאת, אפשרויות עם מחיר חוזרות. מבפנים זו לא אותה בעיה. אם קראתם את הרשימות שלנו על מה באמת כרוך באינטגרציה של API להזמנת טיסות, אתם כבר יודעים שהמחיר בחיפוש הוא לא תמיד המחיר בהזמנה. מלונות מוסיפים מעל זה קושי שני: נפח.

בעיר אחת יכולים להיות מאות בתי מלון. כל מלון מוכר כמה סוגי חדרים. כל סוג חדר נמכר תחת כמה תוכניות תעריף — עם ארוחת בוקר או בלי, ניתן להחזר או לא, תעריף חברים, תעריף חבילה. וכל תוכנית תעריף יכולה להגיע מיותר מספק אחד: bedbank, מנהל ערוצים, חוזה ישיר, או סיטונאי שחתמתם איתו כי ה-allotment שלו במלון מסוים היה טוב משל כל האחרים. הכפילו את כל זה, וחיפוש "פשוט" הוא עץ גדול שהורכב ממקורות שלא מסכימים לא על שמות ולא על מזהים.

אז החלק האיטי הוא לעיתים רחוקות הקוד שלכם. זה הספק האיטי ביותר שבחרתם לחכות לו.

תוצאות הדרגתיות או תשובה מלאה: לבחור במודע

יש שתי דרכים כנות להחזיר תוצאות חיפוש מלונות, ורוב האינטגרציות נתקעות איפשהו באמצע לא נוח.

לחכות לכולם. ה-backend מפזר את הבקשה, מחכה שכל ספק יענה או יגיע ל-timeout, ממזג, מסיר כפילויות, ממיין ומחזיר רשימה מלאה אחת. התוצאה נקייה: בקשה אחת, תשובה אחת, ומחירים שאפשר להשוות כי כולם על השולחן. המחיר: המשתמש בוהה באייקון טעינה בכל פעם, בדיוק כמה זמן שלוקח לספק האיטי ביותר.

להזרים את מה שהגיע. ה-backend מתחיל את הפיזור ומחזיר מיד מזהה חיפוש. הלקוח שואל את המזהה הזה שוב ושוב, או מחזיק stream פתוח, ומקבל תוצאות במנות ככל שספקים עונים. המלונות הראשונים מופיעים מהר. המחיר הוא מורכבות בכל מקום אחר: הרשימה משנה סדר בזמן שהמשתמש קורא אותה, תג "הזול ביותר" עלול לזוז, ומלון שהגיע מספק אחד עשוי לקבל מאוחר יותר תעריף זול יותר מספק אחר.

אם הממשק שלכם הוא עמוד חיפוש מול בן אדם, הגישה ההדרגתית נכונה כמעט תמיד — האדם מעיין, הוא לא מריץ batch job, ועמוד שעובד לנגד העיניים עדיף על עמוד שחושב בשקט. אם הצרכן הוא מכונה אחרת — תהליך להשוואת תעריפים, כלי הזמנות לעסקים שצריך תשובה סופית אחת — לחכות זה לעיתים קרובות פשוט ונכון יותר.

מה שלא תבחרו, שלושה כללים שומרים על לקוח הדרגתי שפוי:

  • כל מנה נושאת סטטוס השלמה של החיפוש כולו, כדי שהלקוח יבחין בין "אין עוד תוצאות כרגע" לבין "לא יהיו עוד תוצאות".
  • התוצאות ממוזגות בשרת לפי מפתח מלון יציב, ולא סתם מצורפות לסוף. הלקוח לעולם לא צריך להסיק בעצמו ששני כרטיסים הם אותו בניין.
  • מיון לפי מחיר הוא זמני עד שהחיפוש מסתיים, והממשק אומר את זה. משתמשים סולחים לרשימה שמתייצבת; הם לא סולחים לתווית "המחיר הנמוך ביותר" שהתבררה כשגויה.

מידול חדרים ותוכניות תעריף בלי שהכול יקרוס

כאן רוב אינטגרציות המלונות נכשלות בשקט, והכישלון צץ חודשים אחר כך כפנייה לתמיכה ולא כדיווח באג.

המודל המפתה הוא שטוח: למלון יש רשימת הצעות, ולכל הצעה שם חדר ומחיר. זה נראה יפה על המסך. ואז ספק אחד מחזיר "Deluxe King" ו-"Deluxe Room, 1 King Bed" עבור מה שהוא בבירור אותו חדר, ספק אחר מחזיר את אותו שם לשני חדרים שונים באמת (אחד עם נוף לעיר ואחד בלי), וספק שלישי מחזיר מחיר ללילה כשכל השאר נותנים מחיר לכל השהייה. רשימה שטוחה לא יכולה לומר לכם באיזה מהמקרים מדובר. היא רק מציגה.

מודל ששורד מפגש עם ספקים אמיתיים כולל לפחות ארבע רמות, ושומר אותן נפרדות:

רמהמה היא מחזיקההטעות שצריך להימנע ממנה
מלוןמזהה יציב משלכם, ממופה לקוד של כל ספקלהשתמש במזהה המלון של ספק כמפתח ראשי
חדרתפוסה, תצורת מיטות, וטקסט החדר המקורי של הספק כפי שהוא"לנקות" שמות חדרים עד ששני חדרים שונים מתמזגים לאחד
תוכנית תעריףבסיס ארוחות, אפשרות החזר, אופן תשלום, הספק שממנו הגיעהלהתייחס לארוחת בוקר או לאפשרות החזר כחלק משם החדר
מחירסך הכול לשהייה, מטבע, אילו מסים ועמלות כלולים ואילו משולמים במלוןלהציג מחיר ללילה ליד מחירים לשהייה, או להסתיר עמלות שמשולמות בהגעה

אפשר לחלוק על מיקום הקווים — יש צוותים שמפרידים את התפוסה לרמה משלה, וזה הגיוני ברגע שמוכרים הזמנות של כמה חדרים. מה שאי אפשר לעשות זה למזג רמות רק כי הממשק מציג שתיים מהן. הממשק יכול לשטח בזמן הרינדור. הנתונים — לא.

פרט אחד ראוי למשפט משלו: שמרו את תיאור החדר הגולמי של הספק לצד כל מה שאתם מנרמלים. כשאורח מגיע ומקבל חדר אחר מזה שבשובר שלו, השאלה הראשונה של כולם תהיה: מה הספק שלח בפועל?

מדיניות ביטול היא נתונים, לא פסקה

ספקים רבים מחזירים את תנאי הביטול כטקסט חופשי: "ביטול חינם עד 3 ימים לפני ההגעה, לאחר מכן קנס של לילה 1." מאוד מפתה להציג את המחרוזת הזאת ולהמשיך הלאה.

אל תעשו את זה. טקסט אי אפשר להשוות, למיין, לסנן או לאכוף. המשתמש רוצה לסנן לתעריפים שניתנים להחזר. מחלקת הכספים רוצה לדעת אילו הזמנות הופכות מחר ללא ניתנות להחזר, כדי שהסוכנות תפנה ללקוח לפני שהמועד חולף. התהליך שאחרי ההזמנה צריך לומר ללקוח, ברגע שהוא לוחץ על ביטול, בדיוק כמה יחויב. שום דבר מזה לא עובד על משפט.

מדלו כל מדיניות כרשימה מסודרת של חלונות קנס: מהרגע הזה ועד הרגע ההוא, הקנס הוא הסכום הזה (או חלק כזה מהשהייה, או כך וכך לילות). הגבולות הם חותמות זמן עם אזור זמן — של המלון, לא של השרת שלכם ולא של המשתמש — כי "3 ימים לפני ההגעה" הוא רגע אחר בהתאם לחצות של מי סופרים. שמרו את הטקסט המקורי של הספק לצד הגרסה המובנית, הציגו את המובנית, והתייחסו לכל אי-התאמה ביניהן כמשהו שצריך לבדוק ולא כמשהו שצריך להסתיר.

ובדקו שוב את המדיניות בזמן ההזמנה, לא רק בזמן החיפוש. מדיניות משתנה בין שתי הקריאות לעיתים קרובות יותר ממה שמישהו מצפה.

כמה טעות עולה באמת

חיפוש איטי עולה לכם בהמרות — רע, אבל גלוי; מישהו יתלונן. הכישלונות היקרים הם השקטים.

תעריף שהוצג כניתן להחזר והספק מתייחס אליו כלא ניתן להחזר הוא סכסוך עם לקוח שמחזיק צילום מסך, ובדרך כלל הסוכנות משלמת את הקנס בעצמה. מחיר ללילה שהוצג כסך הכול לשהייה מוכר חדרים מתחת לעלות עד שמישהו בהנהלת החשבונות שם לב. חדר שמוזג עם חדר אחר שולח משפחה של ארבע נפשות לחדר שנבנה לשניים. עמלות שמשולמות במלון ולא הוצגו מעולם הופכות ביקורת של חמישה כוכבים לחיוב חוזר (chargeback). כל אחד מאלה הוא החלטת מידול שהתקבלה בספרינט הראשון, בדרך כלל תחת התווית "נסדר את זה אחר כך".

מטמון: מה מותר לשמור ומה אסור

כל צוות שמשלב API של מלונות שואל בסוף אם אפשר לשמור תוצאות במטמון כדי שהחיפוש יהיה מהיר וזול יותר. התשובה היא כן, לחלק מהדברים, והקו שמפריד ביניהם חשוב יותר מכל מדד ביצועים.

תוכן סטטי — שמות מלונות, כתובות, קואורדינטות, תמונות, רשימות מתקנים, תיאורי חדרים — משתנה לעיתים רחוקות, ובדיוק אותו כדאי לשמור במטמון בנדיבות, באחסון שלכם. בדקו את תנאי הספק לגבי האופן שבו מותר לאחסן ולהציג אותו; יש רישיונות שמגבילים את זה. למשוך אותו בזמן אמת בכל חיפוש זה איטי ולא מועיל.

תעריפים וזמינות בזמן אמת הם עניין אחר. מחיר במטמון הוא ניחוש לגבי מה שהספק יגבה, וספקים לא מכבדים את הניחושים שלכם. מטמון קצר טווח לתוצאות חיפוש יכול להיות סביר להצגת עמוד — בתנאי שכל מסלול הזמנה מתמחר מחדש מול הספק לפני שגובים כסף, ושהממשק מתייחס למחיר שהשתנה כתוצאה רגילה ולא כשגיאה. יש ספקים שגם מגבילים את היחס בין חיפושים להזמנות; מטמון אגרסיבי שמסתיר מהם את התעבורה האמיתית שלכם הוא לא פרצה שכדאי לסמוך עליה.

מה שאסור לשמור במטמון לעולם הוא כל דבר שמייצג התחייבות: טוקן מחיר מוחזק, מספר הזמנה, הצעת מחיר לביטול. אלה שייכים למשתמש אחד ולרגע אחד.

לפני שאומרים שזה גמור

בדיקה קצרה שכדאי להריץ על האינטגרציה שלכם לפני שהיא נושאת הזמנות אמיתיות:

  • החיפוש מחזיר סטטוס השלמה, והלקוח מתנהג אחרת לפניו ואחריו.
  • המלונות מזוהים לפי מזהה משלכם, וקוד כל ספק ממופה אליו.
  • חדר, תוכנית תעריף ומחיר הם אובייקטים נפרדים בנתונים שלכם, לא משנה מה המסך מציג.
  • כל מחיר אומר אם הוא ללילה או לשהייה, ומה משולם בהגעה.
  • מדיניות הביטול שמורה כחלונות קנס מתוזמנים לפי אזור הזמן של המלון, והטקסט המקורי נשמר.
  • מסלול ההזמנה מתמחר מחדש וקורא שוב את המדיניות לפני שהוא מחייב מישהו.
  • שום דבר שמייצג התחייבות לא מוגש אף פעם ממטמון.

אם אתם שוקלים אם לבנות את כל זה מול כל ספק בנפרד או להתחיל מפלטפורמה שכבר נתקלה בבעיות האלה, הצד החוזי חשוב לא פחות מהקוד — המאמר שלנו על חוזי קונסולידטור מלונות ותעריפי bedbank מפרט מה לדרוש. ממשקי ה-API שלנו לטיסות ולמלונות נפתחים דרך שיחה ולא דרך מפתח בשירות עצמי; אם זה הכיוון שאתם רוצים לבחון, פתחו את השיחה בעמוד ממשקי ה-API לתיירות.

ה-fan-out לא נעלם אף פעם. לקוח טוב פשוט מפסיק להעמיד פנים שהוא לא שם.

מערכת Tekravel

דסק טכנולוגיות תיירות

דסק טכנולוגיות התיירות של Tekravel כותב לאנשי הענף: בעלי סוכנויות, קונסולידטורים והמפתחים שמחברים אליהם מערכות. כל כתבה נבדקת מול הפלטפורמה שהיא מתארת לפני הפרסום.