SMS при смене статуса заказа в Bitrix Sale: событие OnSaleStatusOrderChange

Когда включать отправку из кода

Стандартный сценарий магазина часто уже шлёт письма и push по статусам. Отдельные SMS нужны там, где важно дублировать переход клиентом по смс-подтверждению оператора или уведомить о готовности к выдаче. Реализация опирается на модуль «Служба сообщений» и типы SMS-событий — см. общий разбор отправки через \Bitrix\Main\Sms\Event в заметке отправке SMS средствами ядра; здесь описан только узел на смене статуса заказа Sale.

Имена типов SMS-под каждый переход

Удобный шаблон, совместимый с привычкой к почтовым триггерам: суффикс _SMS. Для каждого символьного кода статуса, который вы хотите сопровождать текстом в SMS, в административке должен существовать отдельный тип события вида SALE_STATUS_CHANGED_N_SMS, SALE_STATUS_CHANGED_P_SMS и т.д. Если типа для конкретного статуса нет, отправка завершится ошибкой записи в b_messageservice_message — добавляйте событие заранее или расширяйте код проверками.

Обработчик OnSaleStatusOrderChange

Ниже — каркас: белый список статусов, выбор свойств с кодами PHONE и EMAIL, упаковка полей под макросы шаблонов:

<?php
namespace Ciftix\Integration;

use Bitrix\Main\Event;
use Bitrix\Main\EventManager;
use Bitrix\Main\Sms\Event as SmsEvent;

EventManager::getInstance()->addEventHandler(
    'sale',
    'OnSaleStatusOrderChange',
    [SaleOrderStatusSms::class, 'handleChange']
);

class SaleOrderStatusSms
{
    /** @var string[] символьные коды статусов, когда SMS разрешена */
    private const ALLOWED = ['N', 'P', 'SZ', 'F'];

    public static function handleChange(Event $event): void
    {
        $order = $event->getParameter('ENTITY');
        $statusId = (string)$order->getField('STATUS_ID');
        if (!in_array($statusId, self::ALLOWED, true)) {
            return;
        }

        $phone = '';
        $email = '';
        foreach ($order->getPropertyCollection() as $prop) {
            $code = (string)$prop->getField('CODE');
            if ($code === 'PHONE') {
                $phone = (string)$prop->getField('VALUE');
            } elseif ($code === 'EMAIL') {
                $email = (string)$prop->getField('VALUE');
            }
        }

        $fields = [
            'PHONE' => $phone,
            'ORDER_ID' => $order->getField('ACCOUNT_NUMBER'),
            'ORDER_REAL_ID' => $order->getField('ID'),
            'ORDER_DATE' => $order->getField('DATE_STATUS')->format('Y.m.d'),
            'ORDER_STATUS' => $statusId,
            'ORDER_PRICE' => \SaleFormatCurrency($order->getPrice(), $order->getCurrency()),
            'EMAIL' => $email,
            'ORDER_DESCRIPTION' => (string)$order->getField('USER_DESCRIPTION'),
        ];

        $smsType = 'SALE_STATUS_CHANGED_' . $statusId . '_SMS';
        $sms = new SmsEvent($smsType, $fields);
        $sms->setSite($order->getSiteId());
        $sms->setLanguage('ru');
        $sms->send();
    }
}

Список ALLOWED замените на реальные статусы проекта и синхронизируйте с заведёнными типами событий. Код свойств телефона/почты при необходимости подставьте из настроек конкретного типа плательщика.

Поля, доступные шаблону

• #PHONE# — номер для доставки SMS.
• #ORDER_ID# — номер заказа, видимый покупателю.
• #ORDER_REAL_ID# — внутренний идентификатор.
• #ORDER_DATE# — дата, отформатированная в коде.
• #ORDER_PRICE# — сумма через SaleFormatCurrency.
• #ORDER_STATUS# — символьный код статуса.
• #EMAIL# и #ORDER_DESCRIPTION# — контакт и пользовательский комментарий, если они нужны в тексте сообщения.

Практика на проде

• Перед боевым включением прогоните сценарий на копии: смените статус вручную и убедитесь, что в таблице b_messageservice_message статус финальный «успешно», а текст соответствует шаблону.
• Нормализуйте телефон к формату провайдера (E.164, без лишних скобок) отдельной функцией, если оператор этого требует.
• При высокочастотных массовых сменах статусов следите за квотой SMS и идемпотентностью: при необходимости добавьте флаг в свойство заказа, чтобы не дублировать одно и то же уведомление.