Налаштування трекінгу відправлень на 1С-Бітрікс

Налаштування трекінгу відправлень у 1С-Бітрікс

Трекінг відправлень — автоматичне отримання та відображення статусів доставки від служби доставки. Покупець бачить актуальний статус в особистому кабінеті, менеджер — в адміністративній частині без необхідності заходити в особистий кабінет кожної служби.

Два підходи до трекінгу

Вебхуки (push): служба доставки сама надсилає POST-запит при зміні статусу. Не навантажує сервер, дані актуальні. Вимагає білого IP або публічного домену. Підтримують: СДЕК, Яндекс Доставка, Dostavista.

Polling (pull): агент 1С-Бітрікс періодично опитує API служби доставки. Працює без білого IP, але створює навантаження при великій кількості активних відправлень. Використовується для Boxberry, ПЕК, Ділових Ліній, Пошти Росії.

Агент для polling

class DeliveryTrackingAgent
{
    public static function run(): string
    {
        $activeShipments = self::getActiveShipments();

        foreach ($activeShipments as $shipment) {
            try {
                $service = \Bitrix\Sale\Delivery\Services\Manager::getObjectById(
                    $shipment['DELIVERY_ID']
                );

                $trackCode = $shipment['TRACKING_CODE'];
                $newStatus = $service->getTrackingStatus($trackCode);

                if ($newStatus !== $shipment['LAST_STATUS']) {
                    self::updateStatus($shipment['ORDER_ID'], $newStatus);
                    self::notifyIfNeeded($shipment['ORDER_ID'], $newStatus);
                }
            } catch (\Exception $e) {
                \Bitrix\Main\Diag\Debug::writeToFile($e->getMessage(), 'tracking');
            }
        }

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

    private static function getActiveShipments(): array
    {
        // Вибираємо замовлення зі статусами, при яких відстеження ще актуальне
        $finalStatuses = ['DELIVERED', 'RETURNED', 'CANCELLED'];
        // Повертаємо замовлення не в фінальних статусах з трек-кодом
        return \Bitrix\Sale\Internals\ShipmentTable::getList([
            'filter' => [
                '!TRACKING_NUMBER' => false,
                '!STATUS_ID' => $finalStatuses,
            ],
            'select' => ['ORDER_ID', 'DELIVERY_ID', 'TRACKING_NUMBER', 'TRACKING_STATUS'],
        ])->fetchAll();
    }
}

Агент реєструється при встановленні модуля через \CAgent::AddAgent('DeliveryTrackingAgent::run();', ...) з інтервалом 3600 секунд (раз на годину).

Обробник вебхука

// /local/php_interface/delivery_webhook.php
$data = json_decode(file_get_contents('php://input'), true);
$source = $_GET['source'] ?? '';

$handler = DeliveryWebhookHandlerFactory::create($source);
$handler->process($data);

Один URL (/bitrix/services/delivery/webhook.php?source=sdek) приймає вебхуки від усіх служб. Параметр source визначає, який обробник використовувати.

Відображення трекінгу в особистому кабінеті

У шаблоні компонента bitrix:sale.order.detail додаємо блок трекінгу:

// У шаблоні detail/template.php
if ($trackCode = $arResult['ORDER']['PROPS']['TRACKING_CODE']['VALUE']) {
    $events = TrackingCache::get($trackCode); // кешуємо на 30 хвилин
    include __DIR__ . '/tracking_timeline.php';
}

Шаблон tracking_timeline.php виводить історію статусів у вигляді візуального таймлайну — поточний крок підсвічується.

Дані трекінгу кешуються в \Bitrix\Main\Data\Cache на 30–60 хвилин: статус посилки не змінюється щосекунди, а без кешу кожне відкриття сторінки замовлення створює API-запит до зовнішньої служби.

Зберігання історії статусів

Кожна зміна статусу зберігається в окрему таблицю b_sale_order_delivery_status_log (кастомна) або в нотатки замовлення (OnSaleOrderHistoryInsert). Це дозволяє показувати покупцю повний таймлайн подій, а не тільки поточний статус.

private static function updateStatus(int $orderId, string $newStatus): void
{
    // Зберігаємо в історію статусів
    \Bitrix\Main\Application::getConnection()->add(
        'b_delivery_status_log',
        [
            'ORDER_ID'   => $orderId,
            'STATUS'     => $newStatus,
            'DATE_ADD'   => new \Bitrix\Main\Type\DateTime(),
        ]
    );

    // Оновлюємо поточний статус у властивості замовлення
    $order = \Bitrix\Sale\Order::load($orderId);
    $order->getPropertyCollection()
        ->getItemByOrderPropertyCode('TRACKING_STATUS')
        ?->setValue($newStatus);
    $order->save();
}

Повідомлення при зміні статусу

private static function notifyIfNeeded(int $orderId, string $newStatus): void
{
    $notifyStatuses = ['arrived_at_destination', 'out_for_delivery', 'delivered'];
    if (!in_array($newStatus, $notifyStatuses)) return;

    $event = new \Bitrix\Main\Mail\Event([
        'EVENT_NAME' => 'DELIVERY_STATUS_CHANGED',
        'LID'        => SITE_ID,
        'C_FIELDS'   => [
            'ORDER_ID' => $orderId,
            'STATUS'   => $newStatus,
        ],
    ]);
    $event->send();
}

Продуктивність polling при зростанні замовлень

При 500+ активних відправленнях polling раз на годину створює 500 зовнішніх API-запитів за один прогін агента. Це навантажує і ваш сервер, і API служби доставки (більшість мають квоти). Оптимізація:

• Batch-запити: Пошта Росії та деякі інші служби підтримують запит статусів відразу для кількох трек-номерів в одному запиті — використовуємо це.
• Пріоритизація: спочатку опитуємо відправлення в активних статусах («Кур'єр у дорозі», «Прибуло до міста»), фінальні статуси — рідше.
• Дроселінг: між запитами вставляємо usleep(200000) (200 мс) — не перевантажуємо API.

Терміни виконання

Налаштування polling-агента для однієї служби доставки — 1 робочий день. Вебхук-обробник — 1 день. Відображення трекінгу в особистому кабінеті покупця з історією статусів та повідомленнями — 2–3 дні сумарно.