שילוב אפליקציית מובייל של Bitrix24 באמצעות REST API ו-Webhooks

שילוב אפליקציית Bitrix24 למובייל באמצעות REST API ו-Webhooks

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

תהליך האימות OAuth 2.0

לפי תיעוד Bitrix24, OAuth 2.0 היא שיטת האימות המומלצת לאפליקציות מובייל. Bitrix24 משתמשת ב-Authorization Code Flow. האפליקציה למובייל פותחת WebView או Chrome Custom Tab עם כתובת ההרשאה:

https://{portal}.bitrix24.ru/oauth/authorize/? client_id={app_id}& response_type=code& redirect_uri={deeplink} 

לאחר הרשאה מוצלחת, מתקבל https://{portal}.bitrix24.ru/oauth/authorize/? client_id={app_id}& response_type=code& redirect_uri={deeplink} אשר מוחלף ב-code וב-access_token. ה-refresh_token תקף לשעה אחת, וה-access_token ל-30 יום. חידוש הטוקן משתמש ב-refresh_token הסטנדרטי. שמרו את ה-grant_type=refresh_token ב-Keychain/Keystore לצורך אבטחה.

כיצד להגדיר OAuth 2.0 לאפליקציית המובייל שלכם: שלב אחר שלב

1. רשמו את האפליקציה שלכם ב-Bitrix24 (מפתחים → יישומים).
2. ציינו את ה-redirect URI כ-deep link (לדוגמה, myapp://oauth).
3. יישמו WebView או Chrome Custom Tab עם כתובת ההרשאה המכילה client_id, response_type=code, redirect_uri.
4. לאחר קבלת code, שלחו בקשת POST אל https://oauth.bitrix24.ru/oauth/token/ עם grant_type=authorization_code, client_id, client_secret, code, redirect_uri.
5. שמרו את ה-access_token וה-refresh_token שהתקבלו ב-Keychain/Keystore. חדשו את הטוקן כל שעה באמצעות grant_type=refresh_token.

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

מתודות API מרכזיות

עבודה עם עסקאות באמצעות Retrofit:

interface Bitrix24Api {
    @GET("crm.deal.list")
    suspend fun getDeals(
        @Query("auth") token: String,
        @Query("filter[STAGE_ID]") stageId: String,
        @Query("select[]") fields: List<String>,
        @Query("start") offset: Int
    ): Bitrix24ListResponse<Deal>
}

הפרמטר interface Bitrix24Api { @GET("crm.deal.list") suspend fun getDeals( @Query("auth") token: String, @Query("filter[STAGE_ID]") stageId: String, @Query("select[]") fields: List<String>, @Query("start") offset: Int ): Bitrix24ListResponse<Deal> } הוא ה-offset עבור פגינציה. Bitrix24 מחזירה מקסימום 50 רשומות לכל בקשה. התשובה כוללת start עבור ה-offset הבא ו-next עבור הסכום הכולל. כדי לטעון את הרשימה המלאה, בקשו דפים ברצף עד ש-total יהיה null.

מגבלת בקשות: 2 בקשות בשנייה גם עבור OAuth וגם עבור webhooks נכנסים. עיבוד קבוצתי (batch) מאגד עד 50 קריאות לבקשת HTTP אחת, ומגדיל את התפוקה האפקטיבית פי 50.

{
  "halt": 0,
  "cmd": {
    "get_deals": "crm.deal.list?filter[STAGE_ID]=NEW",
    "get_contacts": "crm.contact.list?filter[TYPE_ID]=CLIENT"
  }
}

מהי מתודת ה-Batch וכיצד היא מאיצה סנכרון?

מתודת ה-batch מאפשרת עד 50 קריאות REST בבקשת HTTP אחת. העבירו JSON עם פרמטר next שבו המפתחות הם שמות שרירותיים והערכים הם מתודות עם פרמטרים. התשובה מכילה תוצאות של כל הפקודות. זה מפחית את מספר הבקשות, עוזר לעקוף מגבלות ומאיץ סנכרון של כמויות נתונים גדולות. עבור 1000+ רשומות, שלבו batch עם פגינציה.

כיצד Webhooks יוצאים מספקים התראות בזמן אמת

webhook יוצא ב-Bitrix24 שולח בקשת POST לכתובת שצוינה כאשר מתרחש אירוע: שינוי עסקה, ליד חדש, עדכון משימה. השרת מקבל את האירוע, מזהה את הסוג ושולח התראת push למכשיר. Bitrix24 שולחת רק את המזהה ואת סוג האירוע; כדי לקבל נתונים מלאים, יש צורך בבקשת null נוספת. זה מוסיף עיכוב של 1-2 שניות אך מבטיח דיוק נתונים.

אירועים נפוצים:

עבור משימות: ONTASKADD, ONTASKUPDATE. עבור פעילויות: ONCRMACTIVITYADD.

כיצד לעקוף את מגבלות הבקשות של Bitrix24

ללא קשר לשיטת האימות, Bitrix24 מגבילה ל-2 בקשות בשנייה. חריגה מחזירה שגיאת { "halt": 0, "cmd": { "get_deals": "crm.deal.list?filter[STAGE_ID]=NEW", "get_contacts": "crm.contact.list?filter[TYPE_ID]=CLIENT" } } . עיבוד קבוצתי מגדיל למעשה את התפוקה פי 50. לסנכרון נתונים גדול, שלבו batch ופגינציה.

טלפוניה ושיחות

Bitrix24 מתעדת שיחות באמצעות cmd או crm.deal.get. עבור אפליקציית מובייל, ניתן ליזום click-to-call: WRONG_REQUEST יוצר רשומת שיחה ב-Bitrix24 המקושרת ללקוח. לאחר השיחה, voximplant.infocall.startwithsound עם משך ותוצאה. לשיחות VoIP באפליקציה, שלבו עם Voximplant או Twilio באמצעות REST.

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

• אנליטיקה: סקירת תהליכים קיימים, בחירת ישויות לסנכרון.
• עיצוב: ארכיטקטורת אינטגרציה, בחירת פרוטוקול (REST/Webhook/Batch), סכמת טוקנים.
• יישום: הגדרת OAuth, פיתוח לקוח API, פגינציה ומאגר אופליין.
• בדיקות: בדיקות אינטגרציה, בדיקות עומס עד 1000 עסקאות.
• תיעוד: תיאור מתודות API, סכמות נתונים, הוראות תמיכה.
• תמיכה לאחר השקה: ניטור למשך שבועיים, תיקוני באגים.

אנו מבטיחים אינטגרציה יציבה התואמת ל-הנחיות בדיקת App Store (סעיף 5.1) ול-מדיניות Google Play Store.

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

אינטגרציה בסיסית (עסקאות, אנשי קשר, משימות) עם OAuth ופגינציה: 1-2 שבועות. הוספת webhooks, התראות push ומאגר אופליין: +שבוע. העלות מחושבת באופן אישי — בקשו הערכת פרויקט תוך יום אחד.

מקרה בוחן: תוצאות אמיתיות

עבור לקוח לוגיסטי עם 50+ מנהלים, שילבנו את Bitrix24 עם האפליקציה המותאמת שלהם. באמצעות עיבוד קבוצתי ו-webhooks, קיצרנו את עיכוב הסנכרון מ-10 דקות לפחות מ-2 שניות, והפחתנו הזנת נתונים ידנית ב-95%. האינטגרציה החזירה את השקעתה תוך שלושה חודשים בזכות יעילות תפעולית.

מלכודות נפוצות שיש להימנע מהן

• אחסון טוקני webhook במובייל: השתמשו תמיד ב-OAuth 2.0 ללקוחות מובייל.
• התעלמות מתום תוקף טוקן הרענון: חדשו טוקנים לפני חלון 30 הימים כדי למנוע שיבושים.
• אי שימוש ב-batch לפעולות בכמות גדולה: קריאות batch מפחיתות שגיאות מגבלה ומאיצות סנכרון.
• שכחת טיפול בתרחישי אופליין: יישמו מאגר אופליין כדי למנוע אובדן נתונים.

צרו קשר לייעוץ. שתפו את הדרישות שלכם, ונעריך את הפרויקט שלכם תוך יום עסקים אחד.