Настройка трекинга отправлений на 1С-Битрикс

Настройка трекинга отправлений на 1С-Битрикс

Трекинг отправлений — задача, которая на первый взгляд кажется простой, пока не начинаешь делать её правильно. «Показывать статус заказа» означает: получать актуальный статус от перевозчика, хранить историю статусов, уведомлять покупателя при изменении, корректно отображать в личном кабинете.

Архитектура трекинговой системы

Базовая схема: агент Битрикс периодически опрашивает API перевозчиков для заказов в активных статусах, сохраняет историю, при смене статуса отправляет уведомление.

// Таблица истории трекинга (миграция)
class TrackingHistoryTable extends \Bitrix\Main\ORM\Data\DataManager
{
    public static function getTableName(): string { return 'custom_tracking_history'; }

    public static function getMap(): array
    {
        return [
            new \Bitrix\Main\ORM\Fields\IntegerField('ID', ['primary' => true, 'autocomplete' => true]),
            new \Bitrix\Main\ORM\Fields\IntegerField('ORDER_ID'),
            new \Bitrix\Main\ORM\Fields\StringField('CARRIER'),          // sdek, boxberry, etc.
            new \Bitrix\Main\ORM\Fields\StringField('TRACK_NUMBER'),
            new \Bitrix\Main\ORM\Fields\StringField('STATUS_CODE'),
            new \Bitrix\Main\ORM\Fields\StringField('STATUS_TEXT'),
            new \Bitrix\Main\ORM\Fields\StringField('LOCATION'),         // текущее местонахождение
            new \Bitrix\Main\ORM\Fields\DatetimeField('STATUS_DATE'),
            new \Bitrix\Main\ORM\Fields\DatetimeField('CREATED_AT'),
        ];
    }
}

Агент трекинга

class DeliveryTrackingAgent
{
    public static function run(): string
    {
        // Выбираем заказы с трекинг-номерами в активных статусах
        $orders = \Bitrix\Sale\Order::getList([
            'filter' => [
                '!PROPERTY_TRACK_NUMBER' => false,
                'STATUS_ID'              => ['N', 'P', 'Q'], // не закрыты
            ],
            'select' => ['ID', 'PROPERTY_TRACK_NUMBER', 'PROPERTY_CARRIER_CODE'],
        ]);

        $carriers = [
            'sdek'     => new SdekTracker(),
            'boxberry' => new BoxberryTracker(),
            'pochta'   => new PochtaTracker(),
        ];

        while ($order = $orders->fetch()) {
            $carrier = $carriers[$order['PROPERTY_CARRIER_CODE_VALUE']] ?? null;
            if (!$carrier) continue;

            try {
                $status = $carrier->getStatus($order['PROPERTY_TRACK_NUMBER_VALUE']);
                self::saveStatus($order['ID'], $status);
            } catch (\Throwable $e) {
                // логируем, не падаем
                \Bitrix\Main\Diag\Debug::writeToFile($e->getMessage(), 'tracking', '/local/logs/tracking.log');
            }
        }

        return __CLASS__ . '::run();';
    }

    private static function saveStatus(int $orderId, array $status): void
    {
        // Проверяем, изменился ли статус
        $last = TrackingHistoryTable::getRow([
            'filter' => ['ORDER_ID' => $orderId],
            'order'  => ['STATUS_DATE' => 'DESC'],
            'select' => ['STATUS_CODE'],
        ]);

        if ($last && $last['STATUS_CODE'] === $status['code']) return; // не изменился

        TrackingHistoryTable::add([
            'ORDER_ID'    => $orderId,
            'STATUS_CODE' => $status['code'],
            'STATUS_TEXT' => $status['text'],
            'LOCATION'    => $status['location'] ?? '',
            'STATUS_DATE' => new \Bitrix\Main\Type\DateTime($status['date']),
            'CREATED_AT'  => new \Bitrix\Main\Type\DateTime(),
        ]);

        // Отправить уведомление при смене статуса
        self::notifyCustomer($orderId, $status);
    }
}

Страница трекинга в личном кабинете

// Компонент отображения истории трекинга
$orderId = (int)$_REQUEST['ORDER_ID'];
$order   = \Bitrix\Sale\Order::load($orderId);

if ($order && $order->getUserId() === $USER->GetID()) {
    $history = TrackingHistoryTable::getList([
        'filter' => ['ORDER_ID' => $orderId],
        'order'  => ['STATUS_DATE' => 'ASC'],
        'select' => ['STATUS_CODE', 'STATUS_TEXT', 'LOCATION', 'STATUS_DATE'],
    ])->fetchAll();

    // Трекинговый номер для ссылки на сайт перевозчика
    $trackNumber = $order->getPropertyCollection()
        ->getItemByOrderPropertyCode('TRACK_NUMBER')
        ?->getValue();
}

Сроки