RazGazממשק קליטת הזמנות

1סקירה

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

באינטגרציה הזו אין ערוץ חוזר לסטטוס. ‏RazGaz אינה קוראת חזרה למערכת הקופה, ואין נקודת קצה לתשאול (polling) על מצב המשלוח או על פרטי השליח. אם מערכת הקופה זקוקה לסטטוס המשלוח — יש לומר זאת לפני האינטגרציה: זה חוזה נפרד, לא פרמטר של זה.

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

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

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

3הזדהות

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

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

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

POST /ingestOrder

4.1בקשה — שדות חובה

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

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

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

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

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

estimatedPayout, broadcastRadius, platformOrderRef, regionId, restaurantId.

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

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

4.4תשובה

שניהם מחזירים את אותו גוף תשובה:

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

4.5שגיאות

פסק זמן (timeout) ללא תשובה אינו נבדל מ‑500 ויש לטפל בו באותו אופן: שליחה חוזרת. שליחה חוזרת בטוחה תמיד — ראו §6.

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

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

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

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

6Idempotency ושליחות חוזרות

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

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

מכאן, מבחינת מערכת הקופה:

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

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

7זמן הכנה

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

בהיעדרו, RazGaz נסמכת על מה שהיא יודעת על הסניף:

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

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

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

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