Интеграция SMS-сервиса МТС SMS (Беларусь) с 1С-Битрикс

Интеграция SMS-сервиса МТС SMS (Беларусь) с 1С-Битрикс

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

Архитектура 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.

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

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 (сутки).

Хранение настроек и безопасность

Ключи 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.

Обработка ошибок и мониторинг

МТС API возвращает HTTP 200 даже при частичных ошибках — статус отдельного сообщения нужно проверять в теле ответа. Типичные коды ошибок:

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

Сроки внедрения

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