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

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

Покупатель оформил заказ и ждёт посылку. Если он каждый раз вынужден идти на сайт службы доставки, копировать трек-номер и искать статус — это плохой опыт. Модуль отслеживания доставки решает проблему: статус обновляется автоматически, пользователь видит его в личном кабинете и получает уведомления о смене.

Какие данные откуда берутся

Трек-номер появляется в заказе после его передачи в службу доставки. В Битрикс он хранится в поле 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;
}

СДЭК использует 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 на сайте) — короткое сообщение о смене статуса.

Виджет в личном кабинете

Страница заказа в личном кабинете показывает timeline доставки — все события в хронологическом порядке с иконками статусов. Данные берутся из b_tracking_status по ORDER_ID без обращения к API провайдера — это быстро и не зависит от доступности внешнего сервиса.

Сроки разработки