חגים במערכת זימון תורים: ה-API והבאג של ערב החג

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

מה Hebcal נותן

יש REST API שמחזיר JSON, ובנוסף חבילות npm - @hebcal/core לחישוב מקומי ו-@hebcal/rest-api לייצוא. הכיסוי כולל חגים, זמני הדלקת נרות והבדלה לפי מיקום, המרה בין תאריך עברי ללועזי, פרשת השבוע וספירת העומר.

שני דברים מעשיים:

• אין אימות. אין מפתח API, אין הרשמה. זה מפשט מאוד את ההקמה.
• הרישיון הוא Creative Commons Attribution 4.0 - כלומר נדרשת ייחוס. אם אתה מציג את הנתונים למשתמשי הקצה, שווה לבדוק מה זה אומר במוצר שלך. זה לא נטל כבד, אבל זו חובה אמיתית ולא פרט שולי.

את מבנה הבקשה המדויק והפרמטרים יש לקחת מהתיעוד הרשמי ב-hebcal.github.io/api/.

הבאג שכמעט כל מערכת עושה: ערב החג

זו הנקודה החשובה ביותר במאמר.

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

ההשלכה המעשית: מערכת שחוסמת רק את תאריך החג עדיין תציע תור ב-16:00 בערב שלפניו - בדיוק בשעות שבהן העסק כבר סגר. הלקוח יקבל אישור, יגיע, וימצא דלת נעולה.

וזה נראה כמו באג אקראי, כי רוב השנה המערכת עובדת מצוין.

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

אותו היגיון חל על שבת: היא מתחילה ביום שישי בערב, לא בשבת בבוקר.

ישראל אינה תפוצות

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

ל-Hebcal יש אפשרות שקובעת באיזה לוח להשתמש. אם לא תגדיר אותה, תקבל את לוח התפוצות - ותחסום יום שבו העסק בישראל דווקא פתוח. לקוחות לא יוכלו לקבוע תור בלי סיבה, ואף אחד לא ידווח על זה כבאג.

יש לבדוק את שם הפרמטר המדויק בתיעוד ולהגדיר אותו מפורשות. לא להסתמך על ברירת מחדל.

זמני שבת זזים

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

זה לא: זמן כניסת השבת משתנה לאורך השנה, ובישראל הפער בין קיץ לחורף הוא שעות. סגירה ב-15:00 בקיץ מבזבזת שעות פעילות; אותה סגירה בחורף מאחרת אחרי הזמן.

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

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

ארכיטקטורה: מטמון, לא קריאה חיה

הפיתוי הוא לקרוא ל-API בכל בדיקת זמינות. אל תעשה את זה.

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

הדפוס הנכון:

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

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

אפשרות נוספת: @hebcal/core מחשב מקומית, כלומר אפשר לוותר על הקריאה החיצונית לגמרי.

מה שהמערכת עדיין צריכה מהעסק

ה-API נותן את הלוח. הוא לא יודע איך העסק הזה עובד. שלוש שאלות שדורשות תשובה מהלקוח ולא מהקוד:

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

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

מה שנשבר בפועל

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

צ'קליסט

1. להגדיר מפורשות את אפשרות ישראל - לא להסתמך על ברירת מחדל.
2. לחסום מהערב שלפני, לא מתחילת התאריך.
3. למשוך זמני שבת לפי מיקום העסק, לא ערך קבוע.
4. מרווח לפני כניסת שבת כפרמטר, לא בקוד.
5. מטמון שנה קדימה; לרענן מתוזמן, לא בבקשה.
6. לבדוק מה קורה לתורים קיימים כשנוספת חסימה.
7. לבדוק את חובת הייחוס ברישיון מול הדרך שבה אתה מציג את הנתונים.