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

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

Стандартные SMS-провайдеры (SMS.ru, SMSC) не работают с белорусскими номерами или работают с ограничениями: нет alphanumeric sender ID, высокая стоимость, проблемы с доставляемостью. A1 (бывший Velcom) — крупнейший оператор Беларуси — предоставляет SMS-шлюз для юридических лиц с белорусским отправителем и гарантированной доставкой по сетям МТС, A1, life:). Для интеграции с Битрикс нужно написать обработчик, который свяжет A1 SMS API с модулем messageservice (для Б24) или main.mail (для коробочного Битрикс).

A1 SMS API

A1 предоставляет HTTP API для отправки SMS. Документация выдаётся при заключении договора. Основные эндпоинты:

• POST /api/sms/send — отправка одного или нескольких сообщений
• GET /api/sms/status/{messageId} — статус доставки
• GET /api/sms/balance — баланс аккаунта

Авторизация — Basic Auth или токен в заголовке (зависит от версии API, уточняйте в договоре). Формат тела запроса — JSON:

{
  "phone": "375291234567",
  "text": "Ваш заказ №1234 оформлен",
  "sender": "MyShop"
}

Sender ID — буквенное имя отправителя, регистрируется через A1 при подписании договора. Без регистрации SMS будут приходить с числовым номером.

Интеграция с коробочным Битрикс

В коробочном Битрикс SMS отправляется через модуль messageservice (если установлен) или напрямую через обработчик события. Основной сценарий — отправка SMS при событиях заказа.

Вариант 1: обработчик события OnSaleStatusOrder

EventManager::getInstance()->addEventHandler(
    'sale',
    'OnSaleStatusOrder',
    ['A1SmsHandler', 'onStatusChange']
);

class A1SmsHandler
{
    public static function onStatusChange($orderId, $status)
    {
        if ($status !== 'F') return; // F = выполнен

        $order = \Bitrix\Sale\Order::load($orderId);
        $phone = $order->getPropertyCollection()
            ->getPhone()->getValue();

        self::sendSms($phone, "Заказ №{$orderId} выполнен");
    }

    private static function sendSms(string $phone, string $text): void
    {
        $ch = curl_init('https://a1sms.by/api/sms/send');
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                'Authorization: Bearer ' . A1_SMS_TOKEN,
            ],
            CURLOPT_POSTFIELDS => json_encode([
                'phone' => $phone,
                'text' => $text,
                'sender' => 'MyShop',
            ]),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 10,
        ]);
        $response = curl_exec($ch);
        curl_close($ch);

        // Логирование ответа
    }
}

Вариант 2: модуль sms.manager

Если на проекте используется модуль sms.manager (из Marketplace или кастомный) — пишется провайдер-адаптер, реализующий интерфейс отправки. Провайдер регистрируется в настройках модуля, после чего A1 SMS доступен как один из каналов отправки.

Интеграция с Битрикс24

В Б24 SMS-провайдер подключается через REST API:

1. Регистрация провайдера: messageservice.sender.add с параметрами CODE=a1sms, TYPE=SMS, HANDLER=https://your-site.by/a1sms-handler.php
2. Обработчик (a1sms-handler.php) — принимает запрос от Б24 (номер, текст), пересылает в A1 SMS API, возвращает статус
3. Callback для статусов — A1 отправляет DLR (Delivery Report) на указанный URL. Обработчик вызывает messageservice.sender.update для обновления статуса в Б24

После регистрации A1 SMS появляется в списке провайдеров: в карточке контакта, в роботах CRM, в рассылках CRM-маркетинга.

Кодировка и транслитерация

SMS в кириллице — 70 символов на сообщение (UCS-2). В латинице — 160 символов (GSM 7-bit). Для экономии бюджета длинные уведомления стоит отправлять в латинице или укладывать текст в 70 символов.

A1 API принимает текст в UTF-8, конвертация в GSM/UCS-2 — на стороне шлюза. Но спецсимволы (кавычки «», длинное тире —) могут конвертироваться некорректно. Перед отправкой — замена на ASCII-эквиваленты.

Обработка ошибок

A1 SMS API возвращает коды ошибок:

Для retry в коробочном Битрикс — агент CAgent, который выбирает неотправленные SMS из HL-блока SmsQueue и повторяет попытку. Для Б24 — retry на уровне обработчика.

Что реализуем

• Регистрация аккаунта A1 SMS и получение API-доступа
• Разработка обработчика для отправки SMS через A1 API
• Подключение к модулю messageservice (Б24) или обработчикам событий (коробка)
• Настройка callback для получения статусов доставки
• Обработка ошибок и retry-логика
• Логирование всех отправленных SMS (HL-блок или таблица)

Сроки

Главный организационный момент — договор с A1 и регистрация sender ID. Техническая часть занимает неделю, а согласование с оператором — от 3 до 10 рабочих дней. Начинайте с договора параллельно с разработкой.