שילוב שירות ה-SMS של MTS (בלארוס) עם 1C-Bitrix

שילוב שירות ה-SMS של MTS (בלארוס) עם 1C-Bitrix

משימה טיפוסית: חנות מקוונת על 1C-Bitrix חייבת לשלוח ללקוחות SMS על סטטוס הזמנה דרך MTS (בלארוס). ל-MTS אין מודול מוכן, והמודול המובנה messageservice תומך רק ב-SMS Center ו-Twilio. פיתחנו אינטגרציה של שירות ה-SMS של MTS עם Bitrix — מוכנה לשימוש, עם תיעוד ותמיכה. הניסיון שלנו: למעלה מ-50 אינטגרציות כאלה, 10 שנות עבודה עם הפלטפורמה. הגדרה נכונה של ה-OAuth token וקיזוז (caching) מפחיתה את זמן תגובת ה-API ב-40% בהשוואה לפתרונות טיפוסיים. מאמר זה יכסה את הארכיטקטורה של תת-מערכת ה-SMS של Bitrix, שלבים לחיבור ל-HTTP API של MTS SMS Pro, מיפוי סטטוסים ושגיאות טיפוסיות.

ארכיטקטורת תת-מערכת ה-SMS של Bitrix

המודול messageservice מאחסן את רשימת הספקים הרשומים במחלקה \Bitrix\MessageService\Sender\SmsManager. כל ספק הוא מחלקה המיישמת את הממשק \Bitrix\MessageService\Sender\Base. שיטות מפתח:

• sendMessage() — שולח הודעה בודדת, מחזיר אובייקט SendMessage עם מזהה חיצוני וסטטוס.
• getShortName() — מזהה ספק לאחסון במסד הנתונים.
• canUse() — בודק זמינות (מפתחות קיימים, פעילות).

רישום ספק מתרחש דרך האירוע onMessageServiceSenderList של המודול messageservice. ה-handler מחזיר מערך של מחלקות ספקים. לאחר הרישום, הספק מופיע בממשק הניהולי הגדרות → שירותי הודעות.

חיבור דרך MTS SMS Pro HTTP API

MTS SMS Pro מספק נקודת קצה REST https://api.mts.by/sms/v1/messages. אימות — Bearer token המתקבל דרך https://api.mts.by/oauth/token באמצעות client_credentials. HTTP API מהיר ואמין יותר מ-SMPP מכיוון שהוא אינו דורש חיבור TCP קבוע ועובד על HTTPS סטנדרטי.

רצף האינטגרציה:

1. קבלת אישורים. בחשבון MTS SMS Pro, צור אפליקציה; client_id ו-client_secret מונפקים. שם השולח האלפאנומרי נרשם בנפרד — בלעדיו, הודעות נשלחות ממספר מספרי.

2. יישם את מחלקת הספק. המחלקה מרחיבה את \Bitrix\MessageService\Sender\Base ומיישמת שלושה דברים: קיזוז ה-OAuth token (אורך חיים — 3600 שניות), יצירת גוף בקשת JSON, טיפול בתגובה עם קודי שגיאה של MTS.

3. מיפוי סטטוסים. MTS מחזיר סטטוסים: DELIVERED, EXPIRED, REJECTED, UNKNOWN. יש לתרגם אותם לסטטוסים של Bitrix: \Bitrix\MessageService\Message\StatusSemantic::DELIVERED, ERROR וכו'.

פורמט הבקשה ל-API של MTS:

POST /sms/v1/messages
{
  "phone": "375291234567",
  "text": "Ваш заказ №123 оформлен",
  "sender": "MyShop",
  "validity": 1440
}

השדה POST /sms/v1/messages { "phone": "375291234567", "text": "Ваш заказ №123 оформлен", "sender": "MyShop", "validity": 1440 } — אורך חיי ההודעה בדקות. עבור SMS טרנזקציוני (קודי אימות) הגדר 5–10 דקות, עבור אינפורמטיבי — 1440 (יום).

כיצד לרשום ספק SMS מותאם אישית ב-Bitrix?

כדי ליצור ספק מותאם אישית, עליך להירשם לאירוע validity של המודול onMessageServiceSenderList. ב-handler, החזר אובייקט של המחלקה שלך. דוגמה:

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'messageservice',
    'onMessageServiceSenderList',
    function() {
        return [
            new \My\Provider\MtsSms()
        ];
    }
);

לאחר מכן, הספק יופיע ברשימת הספקים הזמינים וניתן יהיה להשתמש בו במודולים messageservice, \Bitrix\Main\EventManager::getInstance()->addEventHandler( 'messageservice', 'onMessageServiceSenderList', function() { return [ new \My\Provider\MtsSms() ]; } ); ו-sale.

אחסון הגדרות ואבטחה

המפתחות getShortName ו-canUse מאוחסנים בטבלת client_id של המודול client_secret. גישה דרך b_option. אל תאחסן סודות בקבצי תצורה שמגיעים ל-VCS — השתמש ב-messageservice או במשתני סביבה.

ה-OAuth token נשמר במטמון ב-\Bitrix\Main\Config\Option::get('messageservice', 'mts_client_id') עם מפתח המקושר ל-.settings_extra.php. בשגיאה 401 (פג תוקף ה-token), הספק צריך לבקש אוטומטית token חדש ולנסות לשלוח שוב — פעם אחת, ללא רקורסיה.

אינטגרציה עם CRM ו-Sale

לאחר רישום הספק, SMS דרך MTS זמינים במספר נקודות:

• מודול \Bitrix\Main\Data\Cache — הודעות על שינויי סטטוס הזמנה. תבניות מוגדרות בחנות → הגדרות → סטטוסי הזמנה → הודעות SMS. המשתנים client_id, sale, #ORDER_ID# מוחלפים אוטומטית.
• CRM Bitrix24 — אם משתמשים ב-Bitrix24 מקומי, הספק מופיע בהגדרות קמפיין SMS וברובוטים של תהליכים עסקיים. הרובוט #ORDER_STATUS# מאפשר בחירת ספק MTS.
• אימות דו-שלבי — המודול #TRACKING_NUMBER# יכול להשתמש ב-SMS לאישור התחברות. הספק מחובר בהגדרות OTP.

מה לעשות עם שגיאת אימות OAuth?

בקבלת HTTP 401, קרא ל-CRM: Отправить SMS ובקש token חדש. אם השגיאה חוזרת, בדוק את האישורים בחשבון MTS או את תוקף האפליקציה. אנו ממליצים להגדיר התראה למנהל דרך security.

טיפול בשגיאות וניטור

ה-API של MTS מחזיר HTTP 200 גם עם שגיאות חלקיות — יש לבדוק את הסטטוס של הודעה בודדת בגוף התגובה. קודי שגיאה טיפוסיים:

לניטור, יישם סוכן שבודק מדי שעה את הסטטוס של הודעות שנשלחו דרך \CAdminNotify::Add() ומעדכן רשומות ב-\CAdminNotify::Add(). סוכן ניטור כזה מאפשר זיהוי בזמן של בעיות וניסיון חוזר אוטומטי.

מה כלול בעבודה

• ביקורת של תצורת Bitrix ו-MTS הנוכחית
• פיתוח ספק מותאם אישית עם תמיכה בקיזוז וניסיון חוזר
• הגדרת תבניות SMS עבור מודולי sale ו-CRM
• אינטגרציה עם 1C (במידת הצורך, דרך CommerceML)
• בדיקות עומס ואופטימיזציה
• תיעוד והדרכה
• תמיכה באחריות למשך חודש

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

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

בעת החיבור, קח בחשבון ש-MTS בלארוס מחייבת בנפרד SMS טרנזקציוני ופרסומי. SMS פרסומי דורש הסכמת מנוי (opt-in) — Bitrix חייב לבדוק את דגל GET /sms/v1/messages/{id}/status בפרופיל המשתמש לפני שליחת הודעות שיווקיות. האינטגרציה שלנו כוללת בדיקה זו כברירת מחדל.

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