איך מחברים אתר B2B לפריוריטי: מדריך מעשי

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

המדריך מבוסס על ניסיון מעשי: מאז 2016 מוביל מייסד AC את הפיתוח של פלטפורמת B2B עם אינטגרציות ל-Priority, ל-SAP Business One ולמערכות ERP נוספות. הוא מסכם את מה שחשוב לדעת לפני שמתחילים, מנקודת המבט של מי שצריך שהאינטגרציה תעבוד בשגרה, ולא רק בדמו.

לפני שכותבים שורת קוד: מה צריך להיות מוכן בצד של Priority

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

• מודול API ורישיונות. הגישה דרך ה-REST API מחייבת מודול API ורישיונות API למשתמשים. כתיבת נתונים דרך ה-API נספרת כטרנזקציות, שנרכשות בחבילות.
• משתמש API ייעודי. מגדירים משתמש נפרד לאינטגרציה, עם הרשאות רק למה שהוא צריך. כך ברור בלוגים מה נעשה על ידי האתר, וקל לחסום אותו בלי לפגוע באף אחד אחר.
• פתיחת טפסים ל-API. טפסי הרמה העליונה שהאינטגרציה צריכה (לקוחות, פריטים, הזמנות וכו') צריכים להיות מוגדרים כזמינים ל-API. טפסי משנה נכללים אוטומטית עם טופס האב.
• שיטת הזדהות. לחיבור שרת-לשרת, Personal Access Token הוא בדרך כלל הבחירה הנכונה: אפשר להחליף או לבטל אותו בלי לגעת בסיסמה של משתמש. OAuth2 רלוונטי כשמשתמשי קצה צריכים להתחבר עם המשתמש שלהם ב-Priority, והוא דורש מודול נוסף.
• כתובת השירות. ה-API מבוסס OData, וכל הקריאות יוצאות מכתובת בסיס אחת שכוללת את קובץ ה-ini ואת שם החברה. כדאי לקבל אותה בכתב, יחד עם סביבת בדיקות נפרדת מסביבת הפרודקשן.

מה מסנכרנים, ולאיזה כיוון

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

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

ארכיטקטורה: שכבת אינטגרציה, לא קריאות ישירות מהדפדפן

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

1. אבטחה. פרטי ההזדהות ל-ERP לעולם לא צריכים להגיע לדפדפן. כל הגישה עוברת דרך השרת שלכם.
2. מגבלות קצב. ב-Priority בענן יש מגבלת שימוש הוגן: עד 100 קריאות בדקה למשתמש, ומעבר לזה הבקשות נדחות עם שגיאת 429. קטלוג שנטען מה-ERP בכל צפייה בעמוד יגיע לתקרה הזאת מהר מאוד.
3. זמינות. אם השרת של Priority בתחזוקה, האתר צריך להמשיך להציג קטלוג ולקבל הזמנות.

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

משיכת קטלוג, לקוחות ומחירים

כמה הרגלים שחוסכים הרבה בעיות:

• לבקש רק את מה שצריך. עם $select מבקשים רק את השדות שהאתר באמת מציג, ועם $filter רק את הרשומות הרלוונטיות (למשל פריטים פעילים).
• לעבוד בעמודים. מגרסה 25.1 מספר התוצאות המקסימלי לקריאה נקבע בקבוע מערכת, וברירת המחדל היא 2,000 רשומות. במקום להגדיל אותו, עדיף לדפדף עם $top ו-$skip.
• סנכרון מצטבר. כשיש בטופס שדה של תאריך עדכון, מושכים רק מה שהשתנה מאז הריצה הקודמת, ופעם ביום מריצים סנכרון מלא כרשת ביטחון.
• לכבד את הקצב. כשמתקבלת שגיאת 429, מחכים ומנסים שוב עם השהיה שהולכת וגדלה. אין טעם להעמיס על השרת בבקשות חוזרות.
• שמות מדויקים. שמות הטפסים והשדות רגישים לאותיות גדולות וקטנות, ובדרך כלל כתובים באותיות גדולות. כשיש ספק, בודקים ב-$metadata של הסביבה שלכם, כי התאמות מקומיות משנות את המבנה.

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

שליחת הזמנה לפריוריטי, בלי כפילויות

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

POST {serviceRoot}/ORDERS
{
  "CUSTNAME": "C1001",
  "ORDERITEMS_SUBFORM": [
    { "PARTNAME": "A-100", "TQUANT": 12 },
    { "PARTNAME": "B-220", "TQUANT": 3 }
  ]
}

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

הפתרון הוא לבנות את השליחה כך שאפשר לחזור עליה בבטחה:

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

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

טיפול בשגיאות וניטור

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

• להבדיל בין סוגי שגיאות. שגיאת 429 או שגיאת שרת מצדיקות ניסיון חוזר. שגיאת 400 שנובעת מחוק עסקי (לקוח חסום, פריט לא פעיל) לא תיפתר מעצמה, ולכן היא צריכה להגיע לטיפול ידני.
• לשמור את הודעת השגיאה המלאה. מגרסה 19.1 השגיאות חוזרות כ-JSON, ואפשר להציג אותן כפי שהן במסך הניהול.
• מסך הזמנות תקועות. רשימה של הזמנות שלא נקלטו, עם הסיבה וכפתור "שלח שוב" אחרי תיקון. זה חוסך לא מעט שיחות טלפון.
• ניפוי תקלות (Debug) בצד של Priority. כשהתנהגות דרך ה-API שונה מהקלדה ידנית, אפשר להפעיל Trace לבקשה בעזרת כותרת ייעודית, בתיאום עם מנהל המערכת.
• התראה על שקט. אם לא נכנסה אף הזמנה לפריוריטי במשך כמה שעות בשעות פעילות, כנראה שמשהו נתקע.

צ'קליסט קצר לפני עלייה לאוויר

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

לסיכום

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

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

מקורות

1. Priority Developer Portal: REST API — התיעוד הרשמי של ה-REST API של Priority