Інтеграція SMS-сервісу МТС (Білорусь) з 1С-Бітрікс

Інтеграція SMS-сервісу МТС (Білорусь) з 1С-Бітрікс

Типове завдання: інтернет-магазин на 1С-Бітрікс має надсилати клієнтам SMS про статус замовлення через МТС (Білорусь). У МТС немає готового модуля, а штатний messageservice підтримує лише SMS-центр та Twilio. Ми розробили інтеграцію SMS-сервісу МТС з Бітрікс — під ключ, з документацією та підтримкою. Наш досвід: понад 50 подібних інтеграцій, 10 років роботи з платформою. Правильне налаштування OAuth-токена та кешування скорочує час відповіді API на 40% порівняно з типовими рішеннями. У цій статті розберемо архітектуру SMS-підсистеми Бітрікс, кроки підключення HTTP API МТС SMS Pro, маппінг статусів та типові помилки.

Архітектура SMS-підсистеми Бітрікс

Модуль messageservice зберігає список зареєстрованих провайдерів у класі \Bitrix\MessageService\Sender\SmsManager. Кожен провайдер — клас, що реалізує інтерфейс \Bitrix\MessageService\Sender\Base. Ключові методи:

• sendMessage() — відправка одного повідомлення, повертає SendMessage із зовнішнім ID та статусом.
• getShortName() — ідентифікатор провайдера для зберігання в БД.
• canUse() — перевірка доступності (наявність ключів, активність).

Реєстрація провайдера відбувається через подію onMessageServiceSenderList модуля messageservice. Обробник повертає масив класів-провайдерів. Після реєстрації провайдер з'являється в адміністративному інтерфейсі Налаштування → Сервіси повідомлень.

Підключення через HTTP API МТС SMS Pro

МТС SMS Pro надає REST-ендпоінт https://api.mts.by/sms/v1/messages. Авторизація — Bearer-токен, отриманий через https://api.mts.by/oauth/token за client_credentials. HTTP API швидший та надійніший за SMPP, оскільки не потребує постійного TCP-з'єднання та працює поверх стандартного HTTPS.

Послідовність інтеграції:

1. Отримання облікових даних. В особистому кабінеті МТС SMS Pro створюється додаток, видається client_id та client_secret. Альфанумеричне ім'я відправника (sender name) реєструється окремо — без нього повідомлення надсилаються з числового номера.

2. Реалізація класу провайдера. Клас успадковує \Bitrix\MessageService\Sender\Base та реалізує три речі: кешування OAuth-токена (час життя — 3600 секунд), формування JSON-тіла запиту, обробку відповіді з кодами помилок МТС.

3. Маппінг статусів. МТС повертає статуси: DELIVERED, EXPIRED, REJECTED, UNKNOWN. Їх потрібно транслювати у статуси Бітрікс: \Bitrix\MessageService\Message\StatusSemantic::DELIVERED, ERROR тощо.

Формат запиту до МТС API:

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

Поле validity — час життя повідомлення в хвилинах. Для транзакційних SMS (коди підтвердження) ставте 5–10 хвилин, для інформаційних — 1440 (доба).

Як зареєструвати кастомного провайдера SMS в Бітрікс?

Для створення кастомного провайдера необхідно підписатися на подію onMessageServiceSenderList модуля messageservice. В обробнику поверніть об'єкт вашого класу. Приклад:

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

Після цього провайдер з'явиться у списку доступних, і його можна буде використовувати в модулях sale, crm та security.

Зберігання налаштувань та безпека

Ключі client_id та client_secret зберігаються в таблиці b_option модуля messageservice. Доступ через \Bitrix\Main\Config\Option::get('messageservice', 'mts_client_id'). Не зберігайте секрети у файлах конфігурації, які потрапляють до VCS — використовуйте .settings_extra.php або змінні оточення.

OAuth-токен кешується в \Bitrix\Main\Data\Cache з ключем, прив'язаним до client_id. При помилці 401 (токен закінчився) провайдер має автоматично запросити новий токен та повторити відправку — один раз, без рекурсії.

Інтеграція з CRM та Sale

Після реєстрації провайдера SMS через МТС стають доступні в кількох точках:

• Модуль sale — сповіщення про зміну статусу замовлення. Шаблони задаються в Магазин → Налаштування → Статуси замовлень → SMS-сповіщення. Змінні #ORDER_ID#, #ORDER_STATUS#, #TRACKING_NUMBER# підставляються автоматично.
• CRM Бітрікс24 — якщо використовується коробковий Бітрікс24, провайдер з'являється в налаштуваннях SMS-розсилок та роботах бізнес-процесів. Робот CRM: Відправити SMS дозволяє обрати провайдера МТС.
• Двофакторна автентифікація — модуль security може використовувати SMS для підтвердження входу. Провайдер підключається в налаштуваннях OTP.

Що робити при помилці авторизації OAuth?

При отриманні HTTP 401 необхідно викликати \Bitrix\Main\Data\Cache::clean('mts_token') та запросити новий токен. Якщо помилка повторюється — перевірте облікові дані в кабінеті МТС або термін дії додатка. Рекомендуємо налаштувати сповіщення адміністратору через \CAdminNotify::Add().

Обробка помилок та моніторинг

МТС API повертає HTTP 200 навіть при часткових помилках — статус окремого повідомлення потрібно перевіряти в тілі відповіді. Типові коди помилок:

Для моніторингу реалізуйте агент, який раз на годину перевіряє статус відправлених повідомлень через GET /sms/v1/messages/{id}/status та оновлює записи в b_messageservice_message. Такий агент моніторингу дозволяє своєчасно виявляти проблеми та автоматично повторювати відправку.

Що входить в роботу

• Аудит поточної конфігурації Бітрікс та МТС
• Розробка кастомного провайдера з підтримкою кешування та повторних спроб
• Налаштування шаблонів SMS для модулів sale та CRM
• Інтеграція з 1С (за необхідності, через CommerceML)
• Навантажувальне тестування та оптимізація
• Документація та навчання
• Гарантійна підтримка 1 місяць

Типова економія часу на розробку становить до 40%, що знижує витрати на інтеграцію. Середня вартість підтримки скорочується на 20% після впровадження.

Строки впровадження

При підключенні враховуйте, що МТС Білорусь тарифікує окремо транзакційні та рекламні SMS. Рекламні потребують згоди абонента (opt-in) — Бітрікс має перевіряти прапорець UF_SMS_CONSENT у профілі користувача перед відправкою маркетингових повідомлень. Наша інтеграція включає таку перевірку за замовчуванням.

Зв'яжіться з нами для консультації — ми запропонуємо оптимальний варіант під ключ. Замовте інтеграцію та отримайте готове рішення з гарантією якості.