RazGazממשק אינטגרציה

1איזה חלק שלכם

שני החלקים אינם חלופיים זה לזה:

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

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

2משותף לשני החלקים

2.1כתובות ותעבורה

2.2סטטוסים של הזמנה

חלק א אינו יכול לקרוא את הסטטוס של הזמנה. הטבלה היא בכל זאת השפה שבה מוקדן של RazGaz מדבר כשאתם פונים אליו. חלק ב קורא את הסטטוס בכל הזמנה, §14.

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

2.3זמן הכנה

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

כשלא שולחים אותו, ‏RazGaz משתמשת במה שהיא יודעת על הסניף. כל סניף נמצא באחד משלושה מצבים:

המצב הראשון הוא הסיבה שמערכת שיודעת את זמן ההכנה צריכה לשלוח אותו תמיד. כך נחסך שלב ידני שאחרת מעכב כל הזמנה.

המינימום של האזור. כשאזור עמוס, ‏RazGaz קובעת לו זמן הכנה מינימלי (Busy Lag). כל חלק מטפל אחרת בזמן שנמוך מהמינימום:

• חלק א מעלה אותו למינימום בלי לומר לכם.
• חלק ב דוחה אותו ב‑400 ‏(§12.6). המינימום הנוכחי ניתן לקריאה, §14.4.

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

2.4כתובות

שורת הכתובת היא רחוב, מספר בית ועיר, ולא יותר.

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

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

2.5כסף

חלק א — מערכות קופה: שליחת הזמנות פנימה

3מה RazGaz מנפיקה לכם

שני דברים מקבלים מ‑RazGaz לפני ההזמנה הראשונה:

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

4הזדהות

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

אם שתיהן נשלחו, הכותרת קובעת.

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

5הקריאה: הוספת הזמנה

POST https://api.raz-gaz.com/ingestOrder

5.1בקשה — מה חייב להופיע

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

• deliveryLocation כקואורדינטות, או
• deliveryAddress לא ריק, ש‑RazGaz תחפש.

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

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

5.2בקשה — כתובת ומיקום

כתובת שלא ניתן למקם על המפה עדיין מתקבלת (201). ההזמנה ממתינה אז ב‑awaiting_location עד שמוקדן של RazGaz ימקם אותה. שום דבר בתשובה לא מספר שזה קרה.

5.3בקשה — שדות אופציונליים

5.4שדות שמורים — אין לשלוח

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

estimatedPayout, broadcastRadius, platformOrderRef, regionId, restaurantId.

‏scheduledFor אינו חלק מהאינטגרציה הזו. הוא נשמר ואין לו השפעה: הזמנה שנשלחת עם שעה עתידית יוצאת מיד. אל תשלחו הזמנה למועד מאוחר לפני שהגיע זמנה.

‏restaurantName מתקבל כגיבוי לזיהוי הסניף כשלא נשלח externalId או שהקוד לא מתאים לדבר. אז הוא חייב להיות זהה, תו בתו, לאיות של שם הסניף אצל RazGaz (הנוכחי או שם קודם). אל תסתמכו עליו — שלחו externalId.

5.5תשובה

שתיהן חוזרות עם אותו גוף:

{ "success": true, "orderId": "acme-102-58817", "created": true }

orderId הוא המזהה ששלחתם, מוחזר כפי שהוא. ‏created הוא true ב‑201 ו‑false ב‑200.

התייחסו לכל 2xx כהצלחה. ‏created: false היא תשובה רגילה ומוצלחת, לא שגיאת כפילות.

5.6שגיאות

גוף כל שגיאה הוא { "error": "<message>" }.

תום זמן ברשת בלי תשובה לא ניתן להבחנה מ‑500. טפלו בו באותה דרך: חזרו על הבקשה. חזרה על בקשה תמיד בטוחה, §7.

6זיהוי המסעדה

שלחו externalId בכל הזמנה. ‏RazGaz שומרת את הקוד שלכם לכל סניף מול אותו סניף, ומקושר למפתח ה‑API שלכם, ולכן:

• הקודים שלכם לא צריכים שום קשר למזהים או לשמות של RazGaz;
• שתי מערכות קופה יכולות להשתמש בקודים שונים לאותו סניף בלי להפריע זו לזו.

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

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

7‏Idempotency, ניסיונות חוזרים ותיקונים

ה‑orderId ששלחתם הוא זהות ההזמנה ב‑RazGaz. בקשה שנייה עם orderId שכבר קיים היא עדכון, אף פעם לא משלוח שני.

מה עדכון עושה:

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

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

• זמן הכנה שהמטבח כבר ענה עליו בעצמו נשמר;
• מחיר שמנהל ב‑RazGaz קבע נשמר;
• אם את הכתובת שנשלחה מחדש לא ניתן למקם על המפה, הנקודה והמחיר הקודמים נשמרים;
• ‏placedAt שהושמט נקבע לזמן השליחה החוזרת.

מה זה אומר למערכת הקופה:

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

8זמן הכנה

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

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

דרכים נוספות שבהן הזמנה ממתינה. ‏201 אומר שההזמנה נרשמה. הוא לא אומר שהיא הוצעה לשליחים. שלושה מצבים נוספים מרחיקים הזמנה משליחים, והתשובה לא מזכירה אף אחד מהם (§2.2):

• awaiting_location — לא ניתן היה למקם את הכתובת על המפה;
• held — הסניף מפרסם ידנית, הכתובת לא התאימה לאף מחיר משלוח, או שההזמנה סומנה;
• awaiting_prep_time — הסניף נותן זמן לכל הזמנה, ולא נשלח זמן.

מוקדן של RazGaz רואה את שלושתם.

9לפני העלייה לאוויר

1. ‏RazGaz הנפיקה את מפתח ה‑API וקוד מסעדה אחד לכל סניף.
2. ה‑orderId שלכם לא יכול להתנגש במזהה של מערכת אחרת (§5.1).
3. בכל הזמנה יש נקודת מסירה. קואורדינטות נשלחות כמספרים, או ששורת הכתובת היא רחוב, מספר בית ועיר, והקומה והדירה ב‑deliveryAddressParts.
4. נשלחה הזמנה אמיתית אחת מכל סניף, ווידאתם עם RazGaz שהיא הגיעה מקושרת למסעדה הנכונה. פרק 6 מסביר למה תשובת ה‑HTTP לבדה לא מאשרת זאת.
5. ‏estimatedReadyMinutes נשלח בכל פעם שמערכת הקופה יכולה להפיק אותו.
6. יש ניסיונות חוזרים על 500 ועל תום זמן. על 400 ו‑401 לא חוזרים באופן עיוור, אלא מציגים אותם למי שיכול לטפל.

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

10מה RazGaz מנפיקה לכם

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

שלושה דברים מקבלים מ‑RazGaz לפני ההזמנה הראשונה:

אין כאן קוד סניף ואין מפתח API כמו של מערכת קופה. בממשק הזה החשבון הוא הזהות, והסניף נגזר ממנו. סניף ש‑RazGaz סימנה כלא פעיל לא יכול לפתוח הזמנות (403). ההזמנות הקיימות שלו נשארות קריאות וממשיכות להתעדכן.

11הזדהות

11.1קבלת טוקן

POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=<WEB_API_KEY>

{
  "email": "branch@example.com",
  "password": "…",
  "returnSecureToken": true
}

שמרו שלושה שדות מהתשובה:

11.2רענון

POST https://securetoken.googleapis.com/v1/token?key=<WEB_API_KEY>, עם grant_type=refresh_token&refresh_token=<refreshToken> בקידוד application/x-www-form-urlencoded. התשובה מכילה id_token חדש.

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

11.3שימוש בטוקן

בכל בקשה, לכל כתובת:

Authorization: Bearer <idToken>

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

12פתיחת הזמנה

POST https://api.raz-gaz.com/createRestaurantOrder

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

12.1בקשה — שדה החובה

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

12.2בקשה — נקודת המסירה על המפה

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

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

שלושה מקרים שכדאי לתכנן סביבם:

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

12.3בקשה — שדות אופציונליים

12.4שדות שמורים — אין לשלוח

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

12.5תשובה

201 עם:

{ "success": true, "orderId": "…" }

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

12.6שגיאות

גוף כל שגיאה הוא { "error": "<message>" }.

12.7קריאה חוזרת פותחת הזמנה שנייה

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

ניסיון חוזר אוטומטי על הקריאה הזו הוא באחריות המערכת שלכם, והוא בטוח רק כשידוע שהבקשה הראשונה לא נכתבה. כדי לבדוק, קראו את ההזמנות הפעילות (§14.1) וחפשו אחת עם אותה כתובת, אותו טלפון ואותה שעה. הזמנה שנפתחה פעמיים בטעות מבטלים לפי §15.2.

13זמן הכנה ותזמון

13.1איך הזמנה חדשה מתחילה

אין שחרור אוטומטי מ‑awaiting_prep_time. להציע הזמנה לשליחים על סמך ניחוש גרוע יותר מלחכות. הדרך הפשוטה להימנע מההחזקה היא לשלוח תמיד estimatedReadyMinutes.

13.2"מוכן בעוד N דקות"

POST https://api.raz-gaz.com/submitPrepTime

{ "orderId": "…", "minutes": 20 }

minutes הוא מספר דקות מעכשיו: גדול מ‑0, לא יותר מ‑240, ולא פחות מהמינימום של האזור (§2.3).

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

בשחרור אפשר לשלוח גם paymentMethod ("cash" או "card") ו‑orderAmount (חובה במזומן, גדול מ‑0) כדי לציין את התשלום באותה קריאה.

תשובה:

{ "success": true, "orderId": "…", "minutes": 20, "released": true,
  "readyAt": 1762520400000, "paymentMethod": "card" }

released אומר אם הקריאה שחררה את ההזמנה או עדכנה אותה. ‏readyAt הוא באלפיות שנייה מ‑epoch בשחרור, ו‑null בעדכון.

13.3תזמון הזמנה שכבר פתוחה

אם אתם יודעים את השעה כשאתם פותחים את ההזמנה, שלחו scheduledFor ב‑createRestaurantOrder ‏(§12.3) וזהו. הקריאה הזו מיועדת להזמנה שכבר פתוחה ומוחזקת ב‑awaiting_prep_time.

POST https://api.raz-gaz.com/scheduleRestaurantOrder

{ "orderId": "…", "scheduledFor": "2026-11-08T20:30:00+02:00", "minutes": 25 }

זו תשובה אחרת לאותה שאלה. במקום כמה זמן האוכל לוקח מעכשיו, אומרים מתי השליח צריך לבוא לקחת אותו. ‏RazGaz מחזיקה את ההזמנה ב‑scheduled ומציעה אותה לשליחים 20 דקות לפני השעה הזו.

תשובה:

{ "success": true, "orderId": "…", "scheduledFor": 1762626600000,
  "releaseAt": 1762625400000, "minutes": 25, "paymentMethod": null }

שתי השעות באלפיות שנייה מ‑epoch. ‏releaseAt הוא הרגע שבו ההזמנה תוצע לשליחים.

הזמנה שכבר הוצעה לשליחים אי אפשר לתזמן מהממשק הזה. אם הלקוח מזיז את השעה אחרי השחרור, בטלו (§15.2) ופתחו הזמנה חדשה לשעה הנכונה.

14קריאת ההזמנות שלכם

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

https://firestore.googleapis.com/v1/projects/razgaz-f7295/databases/(default)/documents

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

כל אחת מהמגבלות האלה כבר נשברה באינטגרציה אחרת. מערכת אחת תשאלה אותנו כל 0.37 שניות, מסביב לשעון, מכמה עמדות, בשביל מסעדה אחת.

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

14.1ההזמנות הפעילות

POST …/documents:runQuery

{
  "structuredQuery": {
    "from": [{ "collectionId": "orders" }],
    "where": { "compositeFilter": { "op": "AND", "filters": [
      { "fieldFilter": {
        "field": { "fieldPath": "restaurantId" },
        "op": "EQUAL",
        "value": { "stringValue": "<restaurant id>" } } },
      { "fieldFilter": {
        "field": { "fieldPath": "status" },
        "op": "IN",
        "value": { "arrayValue": { "values": [
          { "stringValue": "scheduled" },
          { "stringValue": "awaiting_prep_time" },
          { "stringValue": "awaiting_location" },
          { "stringValue": "held" },
          { "stringValue": "pending" },
          { "stringValue": "broadcasting" },
          { "stringValue": "accepted" },
          { "stringValue": "arrived_at_pickup" },
          { "stringValue": "picked_up" },
          { "stringValue": "arrived_at_delivery" }
        ] } } } }
    ] } }
  }
}

<restaurant id> הוא הערך מפרק 10. סננו תמיד לפי restaurantId. שאילתה שלא ניתן להוכיח שהיא נוגעת רק בהזמנות שלכם נדחית כולה, בשגיאת הרשאה ולא בתוצאה מסוננת. השאילתה לפי שם הסניף שהופיעה בגרסאות קודמות של המסמך נדחית גם היא, מחוסר אינדקס: העבירו אותה ל‑restaurantId.

14.2הזמנה בודדת

GET …/documents/orders/<orderId>, עם הטוקן בכותרת.

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

14.3היסטוריה

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

{
  "structuredQuery": {
    "from": [{ "collectionId": "orders" }],
    "where": { "fieldFilter": {
      "field": { "fieldPath": "restaurantId" },
      "op": "EQUAL",
      "value": { "stringValue": "<restaurant id>" } } },
    "orderBy": [{ "field": { "fieldPath": "createdAt" }, "direction": "DESCENDING" }],
    "limit": 50
  }
}

14.4השדות שחוזרים

התשובה היא מסמך Firestore, ולכן כל ערך עטוף בטיפוס שלו (stringValue, integerValue, ‏doubleValue, ‏timestampValue, ‏nullValue, ‏geoPointValue, mapValue, ‏arrayValue). אלה השדות שמעניינים מערכת מסעדה. להזמנה יש שדות נוספים, כולם פנימיים ל‑RazGaz:

זמן ההכנה המינימלי של האזור (§2.3) ניתן לקריאה ב‑GET …/documents/regions/<regionId>, בשדה busyLagMinutes. ה‑regionId של הסניף נמצא במסמך שלו, GET …/documents/restaurants/<restaurant id>. שדה חסר או 0 פירושו שאין מינימום.

14.5מעקב אחרי השליח

GET …/documents/carrierPublic/<carrierId>, מרגע שלהזמנה יש carrierId.

זה כל מה שמסעדה יכולה לקרוא על שליח. הרשומה של השליח עצמו (carriers/<carrierId>) פרטית ונענית בשגיאת הרשאה.

14.6בלי תשאול בכלל — הדרך המומלצת

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

ערוץ ההאזנה עובד ב‑gRPC ולא קיים ב‑REST, ולכן הוא דורש את ה‑SDK של Firebase. ב‑Node:

const { initializeApp } = require('firebase/app');
const { getAuth, signInWithEmailAndPassword } = require('firebase/auth');
const { getFirestore, collection, query, where, onSnapshot } = require('firebase/firestore');

const app = initializeApp({ apiKey: '<WEB_API_KEY>', projectId: 'razgaz-f7295' });
const { user } = await signInWithEmailAndPassword(getAuth(app), 'branch@example.com', '…');
const { restaurantId } = (await user.getIdTokenResult()).claims;

onSnapshot(
  query(
    collection(getFirestore(app), 'orders'),
    where('restaurantId', '==', restaurantId),
    where('status', 'in', ['scheduled', 'awaiting_prep_time', 'awaiting_location', 'held',
      'pending', 'broadcasting', 'accepted', 'arrived_at_pickup', 'picked_up',
      'arrived_at_delivery']),
  ),
  (snap) => {
    for (const change of snap.docChanges()) {
      // 'added' — an order joined the board · 'modified' — status, carrier or ETA changed
      console.log(change.type, change.doc.id, change.doc.data().status);
    }
  },
);

השאילתה וההרשאות שלה זהות לאלה של §14.1. ה‑SDK מחזיק ומרענן את הטוקן בעצמו, כך ש‑§11.2 לא נדרש במסלול הזה. השדות הם אלה של §14.4, ומגיעים כערכים פשוטים ולא עטופים בטיפוסי Firestore.

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

מתי בכל זאת לתשאל. השתמשו בתשאול של §14.1 כשאין SDK, למשל בסביבת PHP או .NET ישנה שלא יכולה להחזיק חיבור פתוח. אז חלות המגבלות שבראש פרק 14.

15פעולות על הזמנה קיימת

שתי הפעולות הן POST …/documents:commit לכתובת מסד הנתונים מפרק 14, עם אותו טוקן, בדיוק בצורה שמוצגת. רק השדות האלה ניתנים לכתיבה בהזמנה מהממשק הזה, ורק בהזמנות של הסניף שלכם. שדה שאינו ברשימה, או הזמנה של סניף אחר, מקבלים שגיאת הרשאה ולא כתיבה חלקית.

בכל בקשה, <orderId> הוא המזהה מ‑§12.5.

15.1האוכל מוכן

{ "writes": [ {
  "update": {
    "name": "projects/razgaz-f7295/databases/(default)/documents/orders/<orderId>",
    "fields": { "readySource": { "nullValue": null } }
  },
  "updateMask": { "fieldPaths": ["markedReadyAt", "readySource"] },
  "updateTransforms": [
    { "fieldPath": "markedReadyAt", "setToServerValue": "REQUEST_TIME" }
  ]
} ] }

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

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

כדי לשנות את זמן ההכנה, השתמשו ב‑§13.2 ולא בכתיבה ישירה. ‏submitPrepTime גם מודיע לשליח שכבר שובץ; כתיבה ישירה לא מודיעה לאיש.

15.2ביטול

{ "writes": [ {
  "update": {
    "name": "projects/razgaz-f7295/databases/(default)/documents/orders/<orderId>",
    "fields": {
      "status": { "stringValue": "cancelled" },
      "cancellationReason": { "stringValue": "הלקוח ביטל" },
      "cancelledBy": { "stringValue": "restaurant" }
    }
  },
  "updateMask": { "fieldPaths": ["status", "cancelledAt", "cancellationReason", "cancelledBy"] },
  "updateTransforms": [
    { "fieldPath": "cancelledAt", "setToServerValue": "REQUEST_TIME" }
  ]
} ] }

‏"cancelled" הוא הערך היחיד של status שהממשק הזה רשאי לכתוב. את הסטטוסים האחרים כותבת RazGaz, כי הם מתארים מה קורה עם השליח. הזמנה שמסומנת מבחוץ למצב שלא תואם את המציאות מתרחקת ממה שהמוקדן והשליח רואים.

‏cancellationReason נקרא על ידי אדם, אז כתבו סיבה ממשית — "הלקוח ביטל", "הסניף סגור" — ולא ריק.

ביטול הוא סופי. הזמנה שבוטלה לא מוצעת שוב לשליחים ואי אפשר להחיות אותה. אם צריך, פותחים הזמנה חדשה (פרק 12).

‏cancelledBy: "restaurant" הוא מה שמודיע לשליח. איתו, ‏RazGaz שולחת את הביטול לשליח שעל ההזמנה — או, כל עוד היא מוצעת, לכל השליחים שהיא הוצעה להם. זה הערך היחיד שמתקבל בשדה הזה, ורק בכתיבה שמבטלת. ביטול בלעדיו עדיין מתקבל אבל לא מודיע לאף שליח, ולכן שלחו אותו תמיד.

ביטול הזמנה שהשליח כבר אסף לא מחזיר את האוכל. מ‑picked_up ואילך, התקשרו גם למוקד של RazGaz.

16מה אין בממשק הזה

כדאי לדעת לפני שמתכננים, כדי ששום דבר לא יהיה תלוי בזה:

17לפני העלייה לאוויר

בסדר הזה, מול סניף אמיתי אחד:

1. ההתחברות מחזירה טוקן, והרענון עובד. בדקו גם את המסלול אחרי שעה, לא רק את ההתחברות: בסביבת ייצור זה המסלול שפוגשים כל הזמן.
2. הזמנת בדיקה נפתחת ומחזירה 201 ו‑orderId, והמערכת שלכם שומרת את ה‑orderId לצד ההזמנה.
3. השאילתה של §14.1 מחזירה בדיוק את ההזמנה הזו. שגיאה כאן פירושה שהשאילתה לא מסננת לפי ה‑restaurantId שלכם בדיוק כפי שמוצג.
4. הסטטוס זז. הוא עובר מ‑pending ל‑broadcasting, ואז ל‑accepted כששליח לוקח את ההזמנה. בשלב הזה carrierId מתמלא ו‑§14.5 מחזיר את המיקום של השליח.
5. "האוכל מוכן" (§15.1) נכתב. ‏markedReadyAt מתמלא בקריאה הבאה.
6. הביטול (§15.2) עובד על הזמנת הבדיקה וסוגר אותה, עם cancelledBy בכתיבה. סיימו בשלב הזה, כדי שמשלוח בדיקה לא יישאר מוצע לשליחים.
7. ‏estimatedReadyMinutes נשלח בכל הזמנה, במינימום של האזור או מעליו. אחרת, ודאו עם RazGaz שהסניף לא מוגדר לתת זמן לכל הזמנה; אם הוא כן, ההזמנה הראשונה בסביבת ייצור תישאר מוחזקת (§13.1).

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