Не просто добавить способ доставки
В действующем интернет-магазине на Drupal 11 и Drupal Commerce нужно было встроить СДЭК в полный цикл заказа: покупатель выбирает доставку, магазин получает корректные данные, оператор готовит отправление, а система отслеживает его состояние.
Один запрос к API эту задачу не решает. Покупатель может поменять город, вернуться на предыдущий шаг или выбрать другого перевозчика. Внешний сервис может задержать ответ. Заказ может потребовать нескольких коробок. При этом повторное действие не должно создавать второе отправление.
Я разработал собственный модуль интеграции СДЭК, связанный с checkout, заказами и механизмами доставки Drupal Commerce. Решение используется в production и участвует в ежедневной работе магазина.
Технологии этого решения
Платформа магазина, логика заказов и собственный модуль доставки через API СДЭК.
Drupal 11: данные, роли и интеграции
Заказы, checkout и способы доставки
Сервисы интеграции, очереди и обработка API
Два процесса. Одна интеграция.
Для покупателя доставка — несколько понятных действий при оформлении заказа. Для магазина — управляемый процесс с упаковкой, регистрацией отправлений и обработкой ошибок. Модуль связывает эти два сценария.
На стороне покупателя
Выбор города и пункта выдачи, получение доступных вариантов доставки и тарифа, сохранение контактных данных. При переходах между шагами checkout выбранный пункт остаётся связан с актуальным городом и способом доставки.
На стороне магазина
Подготовка упаковки, создание отправления через API, сохранение внешнего идентификатора и трек-номера. Далее — синхронизация статусов, отмена и отдельная обработка ситуаций, требующих внимания оператора.
Регистрация отправления вынесена из checkout. Пока покупатель выбирает пункт выдачи и оформляет заказ, система не создаёт логистические заказы в СДЭК. Регистрация запускается отдельно через очередь после размещения заказа. Внешняя операция не привязана к тому, сколько раз пользователь открыл или обновил шаг оформления.
Выбор доставки
Город, пункт выдачи, тариф и контакты собираются в согласованное состояние заказа.
Подготовка отправления
Проверяются данные, состав и упаковка. Система определяет, можно ли переходить к регистрации.
Создание через API СДЭК
Фоновая задача создаёт отправление с контролем повторных действий и сохраняет полученные идентификаторы.
Сопровождение доставки
Состояние отправления синхронизируется с магазином. Ошибки и спорные ответы обрабатываются как отдельные состояния процесса.
Самая важная часть — между успешными ответами API
Интеграцию определяет не только то, что происходит при успешном запросе. Важнее, как она ведёт себя при изменении данных, повторном запуске и неопределённом результате внешней операции.
Смена города без старого ПВЗ
При смене города сбрасываются связанные с ним тариф, способ доставки и пункт выдачи. Запоздавший ответ по предыдущему городу не должен перезаписать новый выбор. Нельзя завершить оформление с ПВЗ, который относится к уже неактуальному состоянию checkout.
Возврат на шаг оформления
Выбор сохраняется при возврате и перезагрузке. Если обновление списка ПВЗ завершается ошибкой, ранее сохранённый пункт не исчезает из интерфейса без объяснения. При переключении перевозчика данные СДЭК очищаются, чтобы не смешивать разные сценарии доставки.
Защита от повторного создания
Перед созданием проверяются сохранённый внешний идентификатор и состояние операции. Блокировки не дают двум обработчикам одновременно регистрировать одно отправление. Повторный запуск задачи учитывает уже выполненные действия.
Таймаут — не повод создавать ещё раз
Если результат запроса создания неоднозначен, операция переводится в состояние для ручной проверки. Система не повторяет такой запрос вслепую: отправление могло быть создано на стороне СДЭК, даже если магазин не получил ответ.
Отмена также имеет собственные состояния: запрос на отмену, подтверждение, отказ или ошибка. Синхронизация учитывает завершённые отправления и возможность приостановить обновление. Это помогает сохранить понятную историю процесса вместо одного поля «успешно / неуспешно».
Один заказ не всегда равен одной коробке
Для подготовки отправления реализован отдельный механизм упаковки. Он распределяет целые единицы заказа по коробкам с учётом веса, массы тары и заданного ограничения на коробку. Сотрудник может проверить и скорректировать упаковку до отправки.
Это распределение по весу, а не обещание автоматически решить трёхмерную укладку. Габариты коробок требуют проверки на складе. Такой подход учитывает границу между тем, что система может вычислить, и тем, что зависит от фактической упаковки.
При изменении состава заказа сохранённый расчёт можно сопоставить с текущими позициями: упаковка не должна незаметно остаться от предыдущей версии заказа.
Для предусмотренного в модуле сценария отказа исходного отправления реализовано разделение доставки на несколько отправлений. Для частей рассчитываются отдельные варианты, сохраняются собственные идентификаторы, трек-номера, стоимости и состояния. Стоимость для покупателя при этом не переписывается автоматически — логистическая операция и коммерческие условия заказа остаются управляемыми отдельно.
Кастомный модуль внутри Drupal Commerce
Модуль использует плагин доставки Drupal Commerce, собственные элементы checkout, обработчики событий заказа и фоновые задачи. Работа с API, хранение состояния, упаковка и управление отправлениями разделены по сервисам.
Такое разделение позволяет менять логику упаковки или обработки статусов, не переписывая интерфейс выбора пункта выдачи. А операторская часть работает с теми же сохранёнными данными, которые использует фоновая синхронизация.
В исходниках предусмотрены unit- и kernel-тесты, а также ручные сценарии проверки checkout: смена города, возврат между шагами, переключение перевозчика и ошибки загрузки ПВЗ. Эти сценарии отражают реальные точки риска интеграции.
Стек: Drupal 11, Drupal Commerce, Commerce Shipping, PHP, API СДЭК, Queue API, Lock API.
Рабочий процесс вместо изолированной кнопки
Магазин получил действующую интеграцию СДЭК, которая охватывает оформление заказа и дальнейшую работу с отправлением. Решение развёрнуто и используется ежедневно.
Для покупателя
Выбор доставки и ПВЗ встроен в оформление заказа. Смена города и переходы между шагами учитываются в логике checkout.
Для команды магазина
Регистрация, упаковка, трек-номера и статусы связаны с заказом. Неоднозначные ответы API выделены в отдельный процесс проверки.
Этот кейс показывает мой подход к разработке интеграций для интернет-магазинов: связать пользовательский интерфейс, бизнес-процесс и внешнюю систему, предусмотрев поведение каждого участника при сбоях и повторных действиях.
О подключении СДЭК к Drupal
Можно ли интегрировать СДЭК с Drupal 11 и Drupal Commerce?
Да. В этом проекте интеграция реализована собственным модулем: выбор доставки в checkout, работа с ПВЗ и тарифами, регистрация отправлений через API и последующая синхронизация.
Это готовый модуль СДЭК для установки на любой сайт?
Это кейс заказной разработки под процессы конкретного магазина. Он демонстрирует реализованные возможности, но не является страницей скачивания универсального модуля. Для другого проекта сначала нужно определить сценарии доставки, правила упаковки и требования к обработке заказа.
Почему понадобилась кастомная интеграция?
Требовался полный процесс: согласованное состояние checkout, фоновая регистрация, защита от повторного создания, упаковка, разделение отправлений и обработка спорных ответов API. Решение проектировалось под эту совокупность требований.
Можно ли заказать похожее решение для своего магазина?
Да. Можно разработать интеграцию СДЭК с Drupal Commerce или отдельные части процесса: оформление доставки, управление отправлениями, синхронизацию статусов и автоматизацию работы операторов. Начать стоит с разбора текущего заказа и правил доставки.
