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

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

Стандартні SMS-провайдери (SMS.ru, SMSC) не працюють з білоруськими номерами або працюють з обмеженнями: немає alphanumeric sender ID, висока вартість, проблеми з доставляємістю. A1 (колишній Velcom) — найбільший оператор Беларусі — надає SMS-шлюз для юридичних осіб з білоруським відправником і гарантованою доставкою по мережах MTS, 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 будуть приходити з числовим номером.

Інтеграція з коробковим Bitrix

У коробковому Bitrix 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 доступен як один з каналів відправки.

Інтеграція з Bitrix24

У Б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 у коробковому Bitrix — агент CAgent, який вибирає невідправлені SMS з HL-блока SmsQueue та повторює спробу. Для Б24 — retry на рівні обробника.

Що реалізуємо

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

Терміни

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