פיתוח אפליקציות ל-Bitrix24 Marketplace: OAuth, REST, Webhooks

תארו לעצמכם שפיתחתם אפליקציה עבור Bitrix24, עברתם מודרציה ופרסמתם אותה במרקטפלייס. כעבור שבוע מגיעות תלונות — אצל חצי מהלקוחות הסנכרון נשבר, והאפליקציה מחזירה 403 על crm.deal.list. מסתבר שתוכנית 'Basic' אינה מעניקה הרשאות CRM, ואתם לא כללתם בדיקה. או ש-webhook מפסיק להגיב — ה-handler נותק, נתונים אבדו. תרחישים אלה הם תוצאה של טעויות אופייניות שניתן למנוע בשלב התכנון. הבעיה היא שתבניות סטנדרטיות ושגיאות לא מטופלות הן הסיבות העיקריות לדחיית מודרציה ולאובדן לקוחות.

יישמנו למעלה מ-50 אפליקציות Bitrix24 מותאמות אישית למרקטפלייס במשך 5 שנים — מווידג'טים פשוטים ועד פתרונות Bitrix24 מרובי-דיירים. אנו יודעים כיצד ליצור מוצר יציב שלא יאכזב לקוחות. אנו מתמחים בתכנון אפליקציות חזקות שעוברות מודרציה בניסיון הראשון. הניסיון שלנו עוזר להימנע ממלכודות הקשורות למגבלות תעריפים וטיפול בשגיאות. עלות הפיתוח מתחילה ב-$3,000 עבור ווידג'ט פשוט ויכולה להגיע עד $15,000 עבור פתרונות מרובי-דיירים מורכבים. ההשקעה משתלמת דרך חיסכון בתמיכה ועבודה חוזרת — בדרך כלל מפחיתה את זמן התמיכה ב-40% ומטפלת ביותר מ-10,000 webhooks בשעה עם עיבוד אסינכרוני נכון.

אילו סוגי אפליקציות קיימים?

אפליקציות משובצות עובדות ב-iframe דרך Placement API. נקודות השמה: CRM_LEAD_DETAIL_TAB, TASKS_TASK_VIEW_TAB, CALL_LIST ועשרות נוספות. ווידג'טים משובצים דרך BX24.placement.call() לפעולות קטנות: כפתור בכרטיס, פאנל בצ'אט. אפליקציות עם ממשק מותאם אישית נפתחות בטאב נפרד — יותר חופש UX, אך המשתמש עוזב את ההקשר. בוטים ואפליקציות צ'אט משתמשים בשיטות imbot.* ו-imsetting.* ויש להם handler משלהם.

השוואה:

OAuth 2.0 באפליקציות Bitrix24

האימות משתמש ב-OAuth 2.0 עם קוד הרשאה. זרימה:

1. המשתמש מתקין את האפליקציה → הפניה ל-redirect_uri עם קוד.
2. האפליקציה מחליפה את הקוד ב-access_token ו-refresh_token דרך https://oauth.bitrix.info/oauth/token/.
3. access_token חי שעה אחת, refresh_token חי 180 יום.
4. הטוקנים נשמרים במסד הנתונים שלכם, מקושרים ל-member_id.

לתקשורת שרת-לשרת, השתמשו ב-grant_type=client_credentials — זמין עבור אפליקציות מסוג 'Application'. member_id הוא קריטי: כל הנתונים במסד הנתונים מחולקים לפיו, אחרת נתונים של חברה אחת עלולים לדלוף לאחרת.

תיעוד רשמי של Bitrix24 REST API OAuth

Bitrix24 REST API: עבודה עם נתונים

Bitrix24 REST API אינו REST קלאסי. שיטות נקראות דרך POST אל https://{portal}.bitrix24.ru/rest/{method} עם form-data או JSON. פגינציה משתמשת ב-start, מגבלה של 50 רשומות. כדי לקבל הכל, בצעו לולאה עם next.

קבוצות פופולריות:

• crm.lead., crm.deal., crm.contact., crm.company. — CRM
• tasks.task.*, task.item.list — משימות
• disk.folder., disk.file. — קבצים
• im.message.add, imbot.message.add — הודעות
• user.get, user.search — משתמשים
• placement.bind — רישום נקודות השמה

Batch: שלחו עד 50 בקשות דרך batch. עיבוד batch מהיר פי 50 מבקשות רציפות.

POST /rest/batch
{
  "halt": 0,
  "cmd": {
    "get_deal": "crm.deal.get?id=123",
    "get_contact": "crm.contact.get?id=456",
    "get_company": "crm.company.get?id=789"
  }
}

טיפול ב-Webhook ללא אובדן נתונים

הירשמו לאירועים דרך event.bind. כאשר אירוע מתרחש, Bitrix24 שולח POST לכתובת ה-handler. פרטים חשובים:

• ה-handler חייב להגיב תוך POST /rest/batch { "halt": 0, "cmd": { "get_deal": "crm.deal.get?id=123", "get_contact": "crm.contact.get?id=456", "get_company": "crm.company.get?id=789" } } .
• לאחר 3 ניסיונות מסירה כושלים, ה-handler מנותק.
• לעיבוד כבד, השתמשו בתור: קבלו את ה-webhook, שימו אותו בתור, הגיבו 200, ועבדו באופן אסינכרוני.

אירועים זמינים: ONCRMLEADADD, ONCRMDEALUPDATE, ONTASKUPDATE, ONIMMESSAGECHAT, ONUSERADD ועוד מאות.

דוגמה: באפליקציית CRM מרובת-דיירים, צמצמנו את זמן הסנכרון מ-30 שניות ל-3 שניות על ידי יישום webhooks מונעי-אירועים של Bitrix24 עם תור אסינכרוני — שיפור של 90%.

נקודות השמה (Placements)

רישום נקודת השמה נעשה במהלך ההתקנה דרך placement.bind. היא מתחברת לנקודת ממשק ומעבירה הקשר: מזהה ישות, סוג, הרשאות משתמש.

BX24.placement.getInterface(function(data) { console.log(data); }); 

התחברו אל //api.bitrix24.com/api/v1/ וקראו ל-BX24.init() לפני גישה ל-API. ב-iframe, השתמשו ב-localStorage או postMessage.

התמודדות עם מגבלות תעריפים

שיטות REST אינן זמינות בכל התעריפים. crm.* — מתוכניות מסוימות, telephony.* — עם תכונת הטלפוניה, tasks.* — עם מודול 'משימות'. בעת ההתקנה, בדקו זמינות דרך app.info ו-profile. הודיעו למשתמש במפורש אם פונקציונליות אינה זמינה. אל תאפשרו 403 לא מטופל.

אחסון נתוני אפליקציה

Bitrix24 מספקת חנות מפתח-ערך app.option.set/get (מגבלה ~32KB). לנתונים רציניים, אתם זקוקים למסד נתונים משלכם. להגדרות משתמש, השתמשו ב-user.option.set/get בצד הפורטל.

ציר זמן פיתוח

מה כלול

• ניתוח דרישות ותכנון ארכיטקטורה
• הגדרת CI/CD ופריסה על השרת שלכם
• תיעוד REST API ותיאור אינטגרציה
• הדרכה למנהלי פורטל
• חודש תמיכה לאחר השחרור

תשתית

האפליקציה חייבת להיות נגישה דרך HTTPS עם תעודה תקפה. לייצור: דומיין ייעודי, קנה מידה אופקי (טוקנים ב-Redis/DB), ניטור של מטפלי webhook. תעדו את כל קריאות REST API, webhooks נכנסים והחלפות OAuth. ארכיטקטורה נכונה יכולה לחסוך עד 40% מזמן התמיכה.

לפרטים נוספים על OAuth, ראו ויקיפדיה: OAuth.

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