Підключення A1 SMS до 1С-Бітрікс: відправка сповіщень у Білорусі

Підключаємо A1 SMS до 1С-Бітрікс: швидка відправка по Білорусі

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

Чому A1 SMS кращий за альтернативи для Білорусі?

На відміну від зарубіжних SMS-провайдерів, A1 гарантує доставку на номери МТС, A1 та life:) без втрати алфавітного Sender ID. Вартість одного повідомлення — в рази нижча, ніж через SMS.ru на білоруські номери. Крім того, A1 надає офіційний DLR (Delivery Report) та callback-сповіщення, що дає повний контроль над доставкою.

Як працює API A1 SMS?

A1 надає HTTP API, документація видається при укладенні договору. Основні ендпоінти:

• 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 повертає коди помилок: