שלוש דרכים לחבר מערכת לפריוריטי
לפני שמדברים על API, שווה להבין שיש שלוש דרכים שונות לגמרי לחבר אפליקציה, אתר או CRM לפריוריטי, וההחלטה ביניהן קובעת את רוב העלות.
תוסף מדף שכבר מחובר. בשוק הישראלי יש מוצרים שנבנו מראש מעל פריוריטי. נגב מובייל (mobile4erp), למשל, מציגה בעמוד המוצר שלה אפליקציות לסוכני מכירות, לטכנאים, למחסן ולנהגים שעובדות מול פריוריטי בלי ממשק חיצוני. אם התהליך שלכם סטנדרטי, זו לרוב הדרך המהירה והזולה.
קריאות ישירות מהאפליקציה ל-API. האפליקציה פונה לפריוריטי בכל פעולה. נראה פשוט על הנייר, ונשבר בפועל ברגע הראשון שיש עומס, ניתוק או שינוי בטופס.
שכבת ביניים (middleware). שרת שיושב בין המערכות, מדבר עם פריוריטי מצד אחד ועם האפליקציה, האתר או ה-CRM מהצד השני. זו הדרך שאנחנו ממליצים עליה כמעט בכל פרויקט שבו המוצר הוא לא תוסף מדף.
| גישה | מתי מתאימה | החיסרון המרכזי |
|---|---|---|
| תוסף מדף מחובר | תהליך סטנדרטי: סוכן שמזמין, טכנאי שסוגר קריאה, ליקוט במחסן | גמישות מוגבלת בחוויית המשתמש ובלוגיקה |
| קריאות ישירות | כלי פנימי קטן עם מעט משתמשים וקריאה בלבד | פרטי גישה בתוך הלקוח, תלות מלאה בזמינות, מגבלת קריאות |
| שכבת ביניים | אפליקציה ללקוחות, אתר מסחר, סנכרון דו-כיווני, נפח גבוה | עוד רכיב לבנות ולתחזק |
מה צריך לדעת על ה-API של Priority
ה-REST API של Priority מבוסס על פרוטוקול OData. כל טופס שנחשף ל-API הופך ל-entity שאפשר לשלוף ממנו נתונים, לסנן, למיין, לדפדף ולמשוך רשומות קשורות. כתובת הבסיס כוללת את קובץ ה-tabula.ini ואת שם החברה במערכת, ומנהל המערכת יכול להפיק אותה מתוך פריוריטי.
טפסים לא חשופים כברירת מחדל
זו הנקודה שמפתיעה הכי הרבה מפתחים שלא עבדו עם פריוריטי. מנהל המערכת צריך לאשר במפורש כל טופס רמה עליונה לשימוש ב-API, בטופס ייעודי לכך (API Forms). תתי-הטפסים נכללים אוטומטית עם טופס האב. בפועל זה אומר שהשלב הראשון בכל פרויקט הוא רשימת טפסים מסודרת שעוברת לשותף הפריוריטי, ולא שורת קוד.
שלוש שיטות הזדהות
- Basic. ברירת המחדל. שם משתמש API שמוגדר בכרטיס העובד ונפרד משם המשתמש הרגיל שלו.
- Personal Access Token. קיים מגרסה 19.1. הטוקן נשלח בכותרת Basic כשם המשתמש, והסיסמה היא המחרוזת PAT. אפשר לקשר כמה טוקנים לאותו משתמש, ו-Priority ממליצה על השיטה הזו לחיבור שרת לשרת.
- OAuth2 דרך External ID. דורש רכישה של מודול External ID. כשהוא פעיל אי אפשר להשתמש ב-Basic, והמדריך הרשמי מתייחס להתקנות מקומיות ותומך רק ב-Authorization Code עם PKCE.
לממשק בין שרתים, PAT הוא כמעט תמיד הבחירה הנכונה. OAuth2 רלוונטי כשמשתמשי קצה צריכים להתחבר עם הזהות שלהם.
מגבלות שצריך לתכנן סביבן
במדיניות השימוש ההוגן של Priority Cloud, כל משתמש מוגבל ל-100 קריאות API בדקה, ובנוסף יש חלון נע של 5,000 בקשות ל-300 שניות. עד 15 בקשות ממתינות בתור, 10 מהן מעובדות במקביל, ובקשה שלוקחת יותר משלוש דקות נזרקת. כשחוצים את המגבלה מקבלים HTTP 429.
מגרסה 25.1 מספר הרשומות המקסימלי בתשובה נקבע בקבוע מערכת בשם MAXAPILINES, שברירת המחדל שלו היא 2,000 רשומות. קטלוג של 30,000 פריטים לא יגיע בקריאה אחת, וצריך לדפדף.
100 קריאות בדקה נשמע הרבה עד שמחשבים: אפליקציית סוכנים עם 40 משתמשים פעילים שכל מסך בה שולף לקוח, מחירון, מלאי ויתרת חוב ישירות מפריוריטי, תגיע לתקרה בבוקר עמוס. זו הסיבה העיקרית לשכבת ביניים.
רישוי
לפי התיעוד, טרנזקציות API נרכשות בחבילות של 10,000 שמתחדשות חודשית, ומגרסה 25.1 כל משתמשי ה-API חולקים מאגר אחד לפי הרישיון. אפליקציה שקיבלה מזהה ייעודי מ-Priority שולחת כותרות X-App-Id ו-X-App-Key, ובלעדיהן הבקשות נספרות ברישוי ה-API הכללי. את המשמעות הכספית לרישיון שלכם בודקים מול השותף לפני שמתמחרים, לא אחרי.
Webhooks במקום לשאול כל דקה
במקום לשאול את פריוריטי שוב ושוב "השתנה משהו?", אפשר להגדיר Webhook שיופעל מתוך חוק BPM, למשל כשתעודת משלוח עוברת לסטטוס מסוים, וישלח JSON לשרת שלכם. זה דורש את מודול ה-Webhooks. מגרסה 26.0 יש גם יומן שגיאות ל-Webhooks שנשמר שבעה ימים.
מה שכבת הביניים עושה בפועל
כשמישהו אומר "רק צריך לחבר ל-API", זה בדרך כלל החלק שחסר בהצעת המחיר:
- מיפוי שדות. "מספר לקוח" באתר הוא CUSTNAME בטופס CUSTOMERS של פריוריטי, ושדה מותאם שהשותף הוסיף לפני חמש שנים הוא משהו שאף אחד לא זוכר. המיפוי הוא מסמך עבודה, לא פרט טכני.
- סנכרון ומטמון. קטלוג, מחירונים, לקוחות ומלאי נשמרים בבסיס נתונים מקומי ומתעדכנים בתדירות שמתאימה לכל סוג נתון. מלאי אולי כל כמה דקות, קטלוג פעם בלילה.
- תור כתיבה וניסיונות חוזרים. הזמנה שנכנסת באפליקציה נכנסת קודם לתור. אם פריוריטי לא זמינה או החזירה 429, ההזמנה לא הולכת לאיבוד אלא נשלחת שוב.
- מניעת כפילויות. ניסיון חוזר בלי מזהה ייחודי לכל פעולה הוא הדרך הקלה ביותר לייצר שתי הזמנות זהות. זו התקלה הכי נפוצה בממשקים שנבנו מהר.
- טיפול בשגיאות והתראות. פריוריטי מחזירה שגיאות במבנה JSON מגרסה 19.1. מישהו צריך לקרוא אותן: לוג, התראה לאיש תפעול, ומסך שמראה אילו רשומות נתקעו ולמה.
- אבטחה. פרטי הגישה לפריוריטי נשארים בשרת. האפליקציה או האתר מדברים רק עם שכבת הביניים, עם ההרשאות שמתאימות לכל משתמש.
ארבעה תרחישים שחוזרים
אפליקציית הזמנות לסוכנים וללקוחות סיטונאיים
הסוכן או הלקוח העסקי רואה קטלוג, מחיר אישי לפי מחירון, מלאי ויתרת חוב, ופותח הזמנה שנכנסת לפריוריטי כהזמנת לקוח. כאן המחירונים הם הלב: מחיר לפי לקוח, הנחות כמות ומבצעים צריכים להיות מחושבים באותה לוגיקה כמו בפריוריטי, אחרת ההזמנה תיכנס במחיר אחר ממה שהלקוח ראה.
אפליקציה לטכנאי שטח
קריאות שירות נמשכות מפריוריטי, הטכנאי מתעד שעות, חלקים, תמונות וחתימה, והנתונים חוזרים לפריוריטי. הדרישה שמשנה את הארכיטקטורה היא עבודה בלי קליטה. פירטנו את השיקולים במאמר על מערכת לניהול טכנאים.
סנכרון חנות אונליין
מוצרים ומלאי זורמים מפריוריטי לאתר, הזמנות ולקוחות זורמים חזרה. השאלה שצריך לסגור מראש היא מי מפיק את החשבונית ומי מבקש מספר הקצאה כשהעסקה מחייבת אותו. אם אתם מתלבטים בנקודה הזו, ראו מספר הקצאה דרך API.
CRM שמדבר עם פריוריטי
הצוות המסחרי עובד ב-CRM, והכספים בפריוריטי. הממשק פותח לקוח בפריוריטי כשעסקה נסגרת ומחזיר ל-CRM יתרות וחשבוניות פתוחות. כאן ההחלטה החשובה היא איזו מערכת היא מקור האמת לכל שדה, כדי ששתיהן לא ידרסו זו את זו.
מה קובע את העלות ולוח הזמנים
אין מחיר אחד לממשק לפריוריטי, ומי שנותן מספר לפני שראה את רשימת הטפסים מנחש. אלה הגורמים שמזיזים את ההיקף:
| גורם | למה זה משנה |
|---|---|
| מספר הטפסים והכיוון | קריאה בלבד של קטלוג היא עבודה אחרת לגמרי מסנכרון דו-כיווני של לקוחות, הזמנות ותעודות |
| התאמות במערכת שלכם | שדות וטפסים מותאמים, חוקי BPM ומחירונים מורכבים מוסיפים מיפוי ובדיקות |
| גרסת Priority | PAT קיים מ-19.1, ושינויי רישוי ותשובות הגיעו ב-25.1. גרסה ישנה יכולה לחייב עבודה עוקפת |
| ענן או התקנה מקומית | בהתקנה מקומית צריך לפתור גישה לשרת מבחוץ, ולפעמים גם VPN |
| נפח ותדירות | כמה משתמשים, כמה הזמנות ביום וכמה מהר הנתון חייב להתעדכן, מול מגבלת הקריאות |
| עבודה אופליין | מחייבת מסד נתונים במכשיר ויישוב התנגשויות בסנכרון |
| סביבת בדיקות ושותף זמין | בלי סביבת בדיקה, כל בדיקה נעשית על נתונים אמיתיים. זה מאט הכול ומסוכן |
אצלנו את האפליקציה או המערכת עצמה מתמחרים לפי המדרגות הרגילות: MVP ממוקד מ-4,000 ₪, מוצר מלא מ-60,000 ₪, ופלטפורמה ארגונית מ-250,000 ₪. את רכיב הממשק לפריוריטי מתמחרים רק אחרי מיפוי הטפסים והשדות, כי שם נמצא רוב אי הוודאות.
מתי לא לבנות ממשק מותאם
- כשתוסף מדף מכסה את התהליך. אם אפליקציית סוכנים או טכנאים קיימת עושה את מה שאתם צריכים, תקנו אותה. פיתוח מותאם מוצדק כשחוויית המשתמש היא חלק מהמוצר, למשל אפליקציה שהלקוחות שלכם מורידים, או כשהתהליך שלכם באמת שונה. פירטנו את ההיגיון במאמר מערכת מדף מול מותאמת.
- כשמה שחסר הוא דוח. אם הבעיה היא שקשה להוציא נתונים, ייתכן שכלי BI או דוח בפריוריטי יפתרו אותה בלי אפליקציה.
- כשאין שותף פריוריטי שמשתף פעולה. ממשק בלי מי שיחשוף טפסים, יגדיר משתמש API ויענה על שאלות לגבי ההתאמות הוא ממשק שיתקע. סגרו את זה קודם.
מה לברר לפני שמתחילים
- איזו גרסת Priority מותקנת, והאם היא בענן או מקומית.
- מה כולל רישוי ה-API שלכם, כמה טרנזקציות יש במאגר, והאם יש מודול Webhooks.
- האם יש סביבת בדיקות עם נתונים מייצגים.
- אילו טפסים נדרשים, ואילו מהם עברו התאמות.
- מי מקור האמת לכל ישות: לקוחות, מחירים, מלאי, חשבוניות.
- מה קורה כשפריוריטי לא זמינה: האם האפליקציה ממשיכה לעבוד, ומה המשתמש רואה.
אם עוד לא ברור לכם בכלל אם צריך ERP או רק חיבור בין מערכות קיימות, התחילו מERP לעסק קטן. ואם הממשק הוא חלק מפרויקט מחשוב רחב יותר, שווה לבדוק את מענק המחשוב של הסוכנות לעסקים קטנים, שמזכיר במפורש ממשקים עם ספקים ולקוחות.
שורה תחתונה
החיבור הטכני לפריוריטי הוא החלק הקטן. הפרויקט האמיתי הוא רשימת הטפסים, מיפוי השדות ושכבת ביניים שיודעת לשרוד עומס, ניתוקים ושגיאות. תתחילו מתהליך אחד, למשל הזמנות של סוכנים, תריצו אותו מול סביבת בדיקות, ורק אחרי שהוא יציב תוסיפו את הבא.
רוצים שנעבור על הטפסים והתהליך שלכם? פרטי השירות בעמוד פיתוח המערכות, סדר גודל ראשוני במחשבון העלויות, או דברו איתנו ישירות.
מקורות
- Priority REST API: מבוא, מגבלות שימוש ורישוי (Priority Software)
- Priority REST API: שיטות הזדהות
- Priority Webhooks
- נגב מובייל (mobile4erp): עמוד המוצר
המאמר נערך על ידי אביתר אדלר, CTO ב-FlowDev.
