Розробка модуля відстеження доставки 1С-Бітрікс

Розроблення модуля стеження за доставкою для 1С-Bitrix

Покупець оформив замовлення та чекає посилку. Якщо він кожен раз змушений йти на сайт служби доставки, копіювати номер треку та шукати статус — це погана користувацька кількість. Модуль стеження за доставкою вирішує проблему: статус оновлюється автоматично, користувач бачить його в особистому кабінеті та отримує сповіщення про зміни.

Джерела даних

Номер треку з'являється в замовленні після передачі служба доставки. У Bitrix він зберігається у полі TRACKING_NUMBER таблиці b_sale_order_delivery або у користувацькій властивості замовлення, залежно від конфігурації доставки. Модулі доставки (DPD, CDEK, Boxberry, Пошта Росії) зберігають номери треків по-різному — це потрібно враховувати при реалізації.

Архітектура модуля

local/modules/vendor.tracking/
├── lib/
│   ├── Provider/           # Адаптери для API служб доставки
│   │   ├── CdekProvider.php
│   │   ├── DpdProvider.php
│   │   └── RussianPostProvider.php
│   ├── TrackingService.php # Оркестратор
│   └── StatusMapper.php    # Нормалізація статусів
├── install/
│   └── db/install.sql
└── cron/
    └── update_statuses.php

Таблиця b_tracking_status — історія статусів за кожним замовленням:

Інтеграція з API служб доставки

Кожний провайдер реалізує інтерфейс:

interface DeliveryProviderInterface
{
    public function getStatuses(string $trackingNumber): array;
    public function getProviderCode(): string;
}

CDEK використовує REST API v2. Отримання токена через POST /v2/oauth/token, статуси через GET /v2/orders?cdek_number={number}. Відповідь містить масив statuses з полями code, name, date_time, city.

Пошта Росії надає SOAP-сервіс https://tracking.russianpost.ru/rtm34. Метод getOperationHistory повертає XML з операціями за відправленням. Парсинг через SoapClient або прямий розбір XML за допомогою SimpleXMLElement.

DPD — REST API, стеження через GET /api/tracing/order/{trackingNumber}.

Нормалізація статусів

Кожний провайдер має свої коди статусів. StatusMapper приводить їх до єдиного набору:

Це дозволяє будувати єдиний інтерфейс стеження незалежно від служби доставки.

Автоматичне оновлення статусів

Cron-задача запускається кожні 30 хвилин:

*/30 * * * * php /var/www/site/local/modules/vendor.tracking/cron/update_statuses.php

Скрипт вибирає замовлення у статусах, що передбачають активну доставку (DELIVERY, DELIVERING), отримує для кожного актуальні статуси від провайдера, порівнює з останньо записаним у b_tracking_status. Якщо статус змінився — пише новий запис та встановлює прапор NOTIFIED = 0.

Окремий агент або наступний запуск cron обходить записи з NOTIFIED = 0 та надсилає сповіщення.

Сповіщення покупцю

При зміні статусу покупець отримує:

• Email — через поштову подію TRACKING_STATUS_CHANGED. Шаблон містить: поточний статус, номер треку, посилання на сторінку замовлення, кнопку «Стежити на сайті служби доставки».
• Push-сповіщення (якщо реалізований web push) — коротке повідомлення про зміну статусу.

Віджет у особистому кабінеті

Сторінка замовлення в особистому кабінеті показує часову шкалу доставки — всі подіï в хронологічному порядку з іконками статусів. Дані беруться з b_tracking_status за ORDER_ID без звернення до API провайдера — це швидко та не залежить від доступності зовнішнього сервісу.

Терміни розроблення