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

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

У MTS Білорусь немає готового модуля для 1С-Бітрікс. SMPP-шлюз MTS (smpp.mts.by) працює за бінарним протоколом SMPP v3.4, а HTTP API MTS SMS Pro — через REST з авторизацією OAuth 2.0. Стандартний модуль messageservice у Бітрікс умітиме відправляти SMS через провайдерів, але з коробки підтримує лише sms.ru, SMS-центр та Twilio. Для MTS Білорусь потрібен кастомний провайдер.

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

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

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

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

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

MTS SMS Pro надає REST-ендпоінт https://api.mts.by/sms/v1/messages. Авторизація — Bearer-токен, отримуваний через https://api.mts.by/oauth/token за client_credentials.

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

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

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

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

Формат запиту до MTS API:

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

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

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

Ключі 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 через MTS стають доступні в кількох точках:

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

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

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

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

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

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