דלגו לתוכן

API

מילון המסחר האלקטרוני

ממשק מתועד להעברת מידע בין מערכות באופן מבוקר.

איך זה עובד בחנות?

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

מה כדאי לבדוק?

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

מהו ההסכם בין שתי המערכות

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

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

בקשת מידע לעומת יצירת פעולה

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

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

מה מספרים השדות

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

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

מתי מחכים לתשובה

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

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

עבודה בקבוצות במקום בקשה לכל שורה

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

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

הרשאות ותחומי אחריות

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

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

מה חשוב במעבר לגרסה חדשה

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

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

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