האם פאוורלינק ו-Fireberry זה אותו דבר?

כן - פאוורלינק עברה מיתוג ל-Fireberry, בעוד ששרת ה-API נשאר api.powerlink.co.il וחלק מהתיעוד עדיין תחת הדומיין הישן. חיפוש כל אחד מהשמות מחזיר חומר רלוונטי חלקית, ולכן אין להתייחס לקוד כמיושן רק כי הוא אומר Powerlink, ולא כעדכני רק כי הוא אומר Fireberry.

איך מתאמתים מול ה-API של Fireberry?

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

למה אינטגרציה מול Fireberry צריכה משתמש ייעודי?

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

איך קוראים נתונים מה-API של Fireberry?

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

איך נמנעים מרשומות כפולות בדחיפת לידים ל-CRM?

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

ה-API של Fireberry - יהונתן סעדיה

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

Fireberry - שנקראה קודם פאוורלינק - היא מערכת CRM ישראלית עם REST API קומפקטי: ארבע פעולות מעל נקודת קצה גנרית לרשומות, בפורמט JSON, עם אימות בטוקן. התכנון הזה נעים לעבודה, ויש בו פרט אחד שמפיל אינטגרציות חודשים אחרי שהן עלו לאוויר.

שינוי השם - ולמה זה מבלבל בחיפוש

המוצר עבר מיתוג מפאוורלינק ל-Fireberry, אבל שרת ה-API עדיין יושב על api.powerlink.co.il, וחלק מהתיעוד והתמיכה עדיין תחת הדומיין הישן.

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

המבנה: ארבע פעולות

ה-API גנרי מעל סוג רשומה:

פעולה	שיטה ונתיב
יצירה	`POST /api/record/{record}`
עדכון	`PUT /api/record/{record}/{id}`
מחיקה	`DELETE /api/record/{record}/{id}`
שאילתה	`POST /api/query`

שתי הערות על המבנה הזה:

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

קריאה היא POST, לא GET. זו נקודת בלבול ראשונה למי שמגיע מ-REST קלאסי. אין GET /api/record/account?status=active; יש מטען סינון שנשלח ב-POST. לכן צריך לבנות אובייקט שאילתה, ולא מחרוזת - ולתכנן עימוד מההתחלה, כי שאילתה שמחזירה הכול תעבוד יפה על חשבון בדיקות ותיפול על חשבון אמיתי.

הפרט שהורג אינטגרציות: הטוקן שייך למשתמש

זו הנקודה החשובה ביותר במאמר.

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

המשמעות אינה טכנית בלבד:

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

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

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

שמות אובייקטים ושדות - מה שצריך לגלות

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

כמו בכל CRM, החשבון צובר שדות מותאמים לאורך שנות שימוש. שני לקוחות על אותה מערכת יכולים לדרוש קוד שונה - בדיוק כמו בפריוריטי ובSAP Business One.

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

ההתאמה שהיא כל העבודה: זהויות

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

ובכל נקודה כזו חוזרת אותה שאלה: האם הרשומה הזו כבר קיימת?

ל-CRM אין בדרך כלל אילוץ ייחודיות אמיתי. אותה חברה יכולה להופיע בשלושה כתיבים. הכלל שמחזיק:

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

כפילויות ב-CRM לא נופלות בבדיקות. הן מצטברות בשקט ומתגלות כשמישהו שואל למה יש שלוש הזדמנויות פתוחות לאותו לקוח.

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

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

צ'קליסט

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

ה-API של Fireberry (פאוורלינק): רשומות, שאילתות ומלכודת הטוקן

עיקרי הדברים