פיתוח אפליקציות מוטמעות ב-Bitrix24 במפתח סופי

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

עבור חברת לוגיסטיקה, פתרנו את הבעיה הזו: פיתחנו אפליקציה שמשתלבת בכרטיס העסקה וטוענת את סטטוס המשלוח מה-WMS בזמן אמת. התוצאה הייתה קיצור זמן עיבוד ההזמנות מ-15 ל-3 דקות. החיסכון הסתכם בכ-cost calculated after audit בשנה.

מדוע אפליקציה מוטמעת ב-Bitrix24 מהירה יותר מאשר ווידג'ט?

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

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

על פי תיעוד BX24 SDK, אפליקציות מוטמעות (Embedded Apps) הן אפליקציות מסוג IFRAME הרושמות placements ופועלות בתוך ממשק הפורטל. בשונה מאפליקציות חיצוניות (צד שרת), יש להן גישה ישירה ל-BX24 JS SDK והן יכולות:

• לקרוא ולשנות את השדות של כרטיס CRM פתוח בזמן אמת ללא רענון
• להפעיל דיאלוגים, סליידרים והתראות של Bitrix24 (BX24.openPath, BX24.showMessagePopup)
• להירשם לאירועי ממשק באמצעות BX24.placement.call('getInterface', ...)

כיצד אפליקציה מוטמעת מאיצה את העבודה עם CRM?

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

// Subscribe to entity updates
BX24.placement.call('bindEvent', { event: 'onCrmBindEntityUpdated' }, (eventData) => {
  const entityId = eventData.ENTITY_ID;
  refreshWidgetData(entityId);
});

// Change a field visually
BX24.placement.call('setFieldValue', { FIELD: 'UF_CRM_CUSTOM_STATUS', VALUE: 'shipped' }, () => {
  console.log('Field updated in the interface');
});

הרשימה המלאה של האירועים תלויה בסוג הכרטיס (CRM_DEAL, CRM_LEAD וכו') — לכל אחד יש תיעוד משלו.

קבלת ממשק המיקום — פיתוח אפליקציה מוטמעת

עבור CRM_DEAL_DETAIL_TAB, ניתן לקבל את ממשק המיקום הנוכחי:

BX24.placement.call('getInterface', {}, (interfaceData) => {
  /* interfaceData contains: {
    ID: "42", // Deal ID
    ENTITY_TYPE: "CRM_TYPE_DEAL",
    FIELDS: { ... }, // Current field values
    BUTTONS: [ ... ] // Available buttons
  } */
});

כיצד פועלת ההרשאה ומחזור החיים?

כאשר נפתחת לשונית עם אפליקציית Bitrix24, היא יוצרת בקשת iframe לכתובת ה-handler שלך עם הפרמטרים:

GET https://your-app.com/handler?
  DOMAIN=company.bitrix24.ru&
  PROTOCOL=1&
  AUTH_ID=abc123&
  AUTH_EXPIRES=3600&
  REFRESH_ID=xyz789&
  member_id=a1b2c3&
  PLACEMENT=CRM_DEAL_DETAIL_TAB&
  PLACEMENT_OPTIONS={"ID":"42","SECTION":""}

AUTH_ID תקף למשך שעה אחת. עבור הפעלות ארוכות טווח (המשתמש השאיר את הלשונית פתוחה), נדרש רענון:

BX24.init(() => {
    // Automatically refreshes the token if it has expired
    BX24.getAuth((auth) => {
        // auth.access_token — the current token
        fetch('/api/data', {
            headers: {
                'X-Bitrix-Auth': auth.access_token
            }
        });
    });
});

בשרת שלך, אמת את הטוקן באמצעות שיטת ה-REST ‏rest/profile.

השוואה בין אפליקציה מוטמעת לבין ווידג'ט רגיל

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

איך עובד פיתוח אפליקציה מוטמעת: 5 שלבים

1. ניתוח — אנו מזהים אילו מיקומים נדרשים, אילו API-ים חיצוניים יהיו מעורבים, וקובעים את לוחות הזמנים.
2. עיצוב — אנו יוצרים את סכימת ההרשאה, מגדירים את מבנה המטפל ואת צד השרת.
3. מימוש — אנו כותבים את קוד צד הלקוח ב-JS (React/Vue/Vanilla) עם BX24 SDK, ואת רכיב השרת על Express/Fastify.
4. בדיקות — דיבוג בפורטל הפיתוח דרך ngrok עם פרמטרים מדומים, בדיקת refresh tokens.
5. פריסה ותמיכה — אנו פורסים לפרודקשן, מחברים ניטור, ומכשירים עובדים.

מבנה הפרויקט

מבנה מינימלי:

• /public/index.html — נקודת כניסה (כתובת URL של המטפל)
• /public/app.js — קוד צד הלקוח עם BX24 SDK
• /src/api/bitrix.js — עטיפה מעל BX24.callMethod
• /src/api/external.js — בקשות ל-API החיצוני
• /src/components/DealTab.jsx — React/Vue/Vanilla
• server.js — Express/Fastify עבור OAuth callback ופרוקסי API

רכיב השרת הכרחי מכיוון ש-OAuth callback (/oauth/callback) חייב להיות מטופל בשרת, אסור לחשוף את client_secret לדפדפן, ופרוקסי בקשות ל-API-ים חיצוניים מונע בעיות CORS.

מה כלול בפיתוח אפליקציה משובצת

לוח זמנים לפיתוח

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

טעויות נפוצות ואיך להימנע מהן

• דיבוג בתוך iframe: יש להשתמש בפתיחה ישירה של כתובת ה-handler עם פרמטרים מדומים.
• שכחה מרענון טוקן: תמיד יש ליישם רענון אוטומטי דרך BX24.init().
• אי-התחשבות ב-CORS: יש לבצע פרוקסי לבקשות ל-API חיצוניים דרך השרת שלך.

למה כדאי להזמין מאיתנו פיתוח אפליקציה משובצת

אנחנו בשוק כבר למעלה מ-7 שנים ופיתחנו למעלה מ-50 אפליקציות משובצות. אנחנו מבטיחים איכות: כל פרויקט עובר בדיקות תלת-שלביות בפורטל פיתוח עם ngrok. הפרויקט הממוצע מחזיר את ההשקעה תוך 3-6 חודשים באמצעות הפחתת הוצאות תפעוליות.

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

קראו עוד על OAuth 2.0 ב-Wikipedia. תיעוד BX24 SDK — dev.1c-bitrix.ru.