SAP Business One Service Layer: מדריך אינטגרציה למפתחים

SAP Business One חושפת את ה-Service Layer - שכבת REST מבוססת OData שהיא הדרך הנתמכת לקרוא ולכתוב לתוך המערכת מבחוץ. היא עובדת היטב, אבל מודל ההתחברות שלה שונה מכל API מודרני אחר, וזו הנקודה שבה רוב האינטגרציות הראשונות נשברות.

למי ששוקל בין המערכות, ראה גם Priority מול SAP Business One.

אימות: session, לא טוקן

אין כאן API key ואין Bearer token. מתחברים בקריאה:

POST /b1s/v1/Login
{
  "UserName": "...",
  "Password": "...",
  "CompanyDB": "..."
}

בהצלחה חוזרת ישות B1Session עם מזהה session בגוף התשובה, ובמקביל אותו מזהה נשלח גם בכותרת Set-Cookie. את העוגייה הזו נושאים בכל קריאה הבאה.

ROUTEID - העוגייה שמפילה אינטגרציות

מלבד B1SESSION מוחזרת גם עוגיית ROUTEID. כשה-Service Layer רץ מאחורי מאזן עומסים - וזה המצב ברוב ההתקנות הרציניות - היא זו שמנתבת אותך חזרה לאותו מופע שבו נוצר ה-session.

אם לקוח ה-HTTP שלך שומר רק את B1SESSION ומתעלם מ-ROUTEID, התוצאה היא כשלי אימות אקראיים: חלק מהקריאות עוברות וחלק נדחות, בלי דפוס ברור. יש להשתמש ב-cookie jar שנושא את שתיהן, לא להעתיק כותרת אחת ידנית.

פקיעה: 30 דקות ושגיאה 5002-

ברירת המחדל היא פקיעה אחרי 30 דקות של חוסר פעילות. כשה-session פג, הקריאה נכשלת עם קוד -5002.

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

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

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

OData v4, לא v3

החל מ-Feature Pack 2405, OData v3 הוצא משימוש ו-v4 הוא הפרוטוקול המרכזי.

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

יצירת מסמכים - בקריאה אחת

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

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

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

הרשאות ומה שהן מסתירות

ההרשאות של משתמש ה-Service Layer חלות על כל קריאה. אם המשתמש לא רואה אובייקט מסוים בממשק, הוא לא יראה אותו גם דרך ה-API.

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

שיקולים לפני שמתחילים

• סביבת בדיקות. כמו בכל ERP, מסמך שהופק בטעות בייצור הוא בעיה חשבונאית. יש לוודא שיש CompanyDB נפרד לפיתוח, ולהחזיק את שם ה-CompanyDB במשתנה סביבה ולא בקוד.
• שדות מותאמים. התקנות SAP B1 צוברות שדות משתמש (UDF) ואובייקטים מותאמים. שני לקוחות על אותה גרסה יכולים לדרוש קוד שונה. יש לקרוא את המטא-דאטה של ההתקנה הספציפית ולא להסתמך על תיעוד גנרי.
• עברית ו-RTL. שדות טקסט בעברית עוברים דרך ה-API כרגיל, אבל ההצגה שלהם ב-PDF, במיילים ובקבצי ייצוא היא סיפור נפרד. ראה עברית ו-RTL במערכות עסקיות.
• מי הבעלים של הלוגיקה. אם המערכת שלך מחליטה איזה סוג מסמך להפיק ומתי, זו החלטה חשבונאית שדורשת אישור, לא בחירה טכנית.

סדר ניפוי שגיאות

1. לוודא ש-/Login מחזיר 200 ושה-cookie jar קלט גם B1SESSION וגם ROUTEID.
2. אם כשלי אימות אקראיים - כמעט תמיד ROUTEID חסרה.
3. אם כשל אחרי הפוגה - לבדוק אם הקוד הוא -5002, כלומר session שפג.
4. אם רשומות חסרות - לבדוק הרשאות של משתמש ה-API מול הממשק.
5. אם דוגמה מהרשת לא עובדת - לבדוק אם היא נכתבה ל-OData v3.