Ozon Доставка внутри оформления заказа
В действующем интернет-магазине на Drupal 11 и Drupal Commerce нужно было добавить Ozon Доставку как полноценный способ доставки: покупатель выбирает её в общем оформлении заказа, магазин получает корректные данные, оператор работает с отправлением, а система отслеживает его состояние.
Подключить Ozon «одной галочкой» не получается. Пункты выдачи, доступность доставки, стоимость и сроки приходят из внешнего API и зависят от склада, состава заказа и схемы работы магазина. У товаров должны быть собственные идентификаторы на стороне Ozon, а данные, которые покупатель видит в браузере, нельзя переносить в заказ без проверки на сервере.
Я разработал собственный модуль интеграции Ozon Доставки на официальном API Ozon для продавцов. Модуль связан с оформлением заказа, расчётом доставки и заказами Drupal Commerce: отправления создаются фоновыми задачами, а состояние доставки возвращается в магазин.
Технологии этого решения
Магазин, логика заказов и собственный модуль доставки, который работает с API Ozon.
Drupal 11: данные, роли и интеграции
Заказы, checkout и способы доставки
Пункты выдачи, тарифы и статусы отправлений
Сервис API, очереди и обработка отправлений
Путь заказа: от карты ПВЗ до трек-номера
Для покупателя Ozon Доставка — ещё один способ доставки в знакомом оформлении заказа. Для магазина — отдельный процесс со своими проверками, состояниями и точками отказа. Модуль связывает оба сценария в одном заказе.
На стороне покупателя
Карта пунктов выдачи и постаматов прямо в оформлении заказа, выбор пункта, доступность доставки для текущего состава заказа и телефона получателя, стоимость и срок из расчёта Ozon. Выбранный пункт сохраняется в заказе и в профиле покупателя, чтобы в следующий раз не искать его заново.
На стороне магазина
Серверная проверка доставки, расчёт стоимости, создание отправления в Ozon, трек-номер в заказе и письмах покупателю, синхронизация статусов и отмена. Всё, что происходит с отправлением, собрано в одном отчёте по заказам интеграции.
Проверка доставки повторяется на сервере. Оформление заказа сохраняет выбор покупателя, но склад, стоимость и срок доставки берутся из повторного запроса к Ozon — в момент оформления и без кэша. Данные из браузера не участвуют в создании отправления: их можно подменить, ответ Ozon — нет.
Выбор пункта выдачи
Покупатель открывает карту ПВЗ в оформлении заказа. Пункты и их детали приходят из API порциями по области карты и кэшируются на ограниченное время.
Проверка и расчёт
Сервер проверяет, что доставка доступна для выбранного состава заказа, собирает стоимость из данных Ozon и наценки магазина и сохраняет подтверждённый выбор в заказе.
Создание отправления
После оформления заказа фоновая задача создаёт отправление в Ozon и сразу сохраняет все полученные номера отправлений как трек-номера заказа.
Сопровождение доставки
Статусы обновляются по расписанию и после отгрузки. Отмена проходит отдельный сценарий с проверкой возможности отмены и подтверждением результата.
Самое сложное — между запросом и ответом
Внешнюю систему нельзя уговорить вести себя как локальная функция. Интеграцию определяет не успешный ответ API, а поведение при повторных действиях, таймаутах и чужих изменениях.
Данные из браузера не используются
Оформление заказа присылает выбор покупателя, но не истину. Склад, стоимость, состав отправления и срок доставки сервер получает и проверяет сам — на момент оформления, без кэша. Если Ozon не вернул цену, способ доставки становится недоступен: бесплатная доставка «по ошибке» здесь не появляется.
Повторное создание не проходит
Создание отправления защищено блокировкой и проверкой уже сохранённого заказа в Ozon. Повторный запуск задачи не создаёт второй заказ: сначала проверяется сохранённый номер, и только потом отправляется новый запрос.
Таймаут — не отказ
Если результат создания отправления неоднозначен, операция не повторяется вслепую: у метода нет безопасного ключа идемпотентности, и отправление могло уже появиться в Ozon. Такие заказы помечаются для ручной проверки — два заказа вместо одного дороже паузы.
У отмены результат тоже неизвестен
Перед отменой проверяется, можно ли отменить заказ. Если ответ на запрос отмены неоднозначен, состояние не додумывается: оно проверяется отдельным методом статуса отмены, а ошибка сохраняется вместе с причиной.
Лимиты API — часть работы, а не исключение: запросы к Ozon ограничены по частоте, ответы с Retry-After соблюдаются, повторные чтения идут с экспоненциальной задержкой и разбросом. Ответы карты пунктов выдачи и расчёта кэшируются ограниченное время, чтобы оформление заказа не зависело от каждого нажатия. Полные ключи и заголовки авторизации в логи не попадают.
Работа с отправлениями после оформления
Дальше начинается ежедневная эксплуатация. Отгрузка, обновление статусов и отмена выполняются фоновыми задачами, поэтому оператор не ждёт ответа внешней системы в интерфейсе заказа.
Схемы отгрузки FBO и FBS
Статус отправления запрашивается методом, который соответствует сохранённой схеме работы магазина. Отгрузка FBS подтверждается передачей состава отправления, а перед этим проверяется текущее состояние — повторная отгрузка не отправляется.
Статусы и завершённые отправления
Статусы синхронизируются по расписанию и сразу после отгрузки. Ошибки обновления повторяются с нарастающей задержкой, а завершённые отправления перестают опрашиваться: нет смысла дёргать API там, где процесс уже закончен.
Трек-номер в заказе
Каждый номер отправления сохраняется в заказе сразу после создания, поэтому покупатель и оператор видят трекинг в магазине, не заходя в кабинет Ozon. Заказ может содержать несколько отправлений — магазин показывает все.
Отчёт по интеграции
Отдельная страница в админке собирает заказы Ozon Доставки: заказ магазина, номер отправления, состояние, ошибки и историю операций. Это рабочее место для разбора проблемных заказов, а не отладочный лог.
Отдельная часть процесса — сопоставление товаров. Ozon требует собственные идентификаторы товаров, поэтому модуль разрешает их по сохранённому сопоставлению, а локальный артикул магазина никогда не подставляется вместо идентификатора Ozon. Если у позиции нет нужного идентификатора, оформление заказа и создание отправления блокируются: лучше остановить заказ, чем получить отказ уже на стороне Ozon.
Кастомный модуль внутри Drupal Commerce
Модуль использует штатные точки расширения Drupal Commerce: плагин способа доставки, панель оформления заказа, события переходов заказа и отправлений, очередь и обработчик очереди. Работа с API, хранение состояния, расчёт и управление отправлениями разделены по сервисам — логику расчёта можно менять, не переписывая карту пунктов выдачи.
Ниже — то, что обычно оказывается самым хрупким: таймауты, повторные действия, чужие статусы и цена. В исходниках есть unit- и kernel-тесты, покрывающие расчёт доставки, создание отправления и обработку неопределённых ответов API.
Стек: Drupal 11, Drupal Commerce, Commerce Shipping, PHP, Ozon Delivery API, Queue API, Lock API, OAuth 2.0.
Ozon Доставка как часть системы магазина
Магазин получил действующую интеграцию Ozon Доставки: покупатель оформляет заказ с пунктом выдачи, магазин создаёт отправления и ведёт их до передачи в доставку, а трек-номера и статусы видны в заказе.
Для покупателя
Пункт выдачи, стоимость и срок доставки Ozon выбираются в общем оформлении заказа. Трекинг приходит в заказ, а не только в письмо от перевозчика.
Для команды магазина
Отправления создаются фоном, отгрузка и отмена идут через понятные состояния, проблемные заказы собраны в отчёте. Ни один неоднозначный ответ API не превращается в дубль заказа.
Этот кейс показывает мой подход к интеграциям для интернет-магазинов: связать пользовательский интерфейс, работу оператора и внешнюю систему так, чтобы сбой на любом шаге оставался управляемым. Такие задачи решаются в рамках разработки интернет-магазинов на Drupal; если кроме магазина нужны личные кабинеты, каталоги и внешние сервисы, это уже разработка сайтов и веб-платформ.
Вопросы о подключении Ozon Доставки
Можно ли подключить Ozon Доставку к сайту на Drupal?
Да. Готового модуля для Drupal нет, поэтому интеграция разрабатывается под конкретный магазин: карта пунктов выдачи в оформлении заказа, серверная проверка доступности и стоимости, создание отправлений, трек-номера, статусы и отмена. В этом кейсе так и сделано — собственным модулем на Drupal 11 и Drupal Commerce.
Есть ли готовый модуль Ozon Доставки для Drupal?
Публичных решений для Drupal нет — в отличие от Битрикса, OpenCart или Webasyst, где готовые модули продаются как продукт. Для Drupal это заказная разработка: она учитывает схему работы магазина, правила упаковки и то, как заказы обрабатываются сейчас.
Чем отличается Ozon Доставка для продавцов от доставки для бизнеса?
Это два разных продукта. Сценарий для продавцов работает через кабинет продавца и Seller API: товары должны быть заведены на Ozon, а заказ магазина превращается в отправление с идентификаторами товаров Ozon. Сценарий для бизнеса использует отдельный кабинет доставки и Delivery API, где карточки товаров на Ozon не нужны. В этом проекте реализован сценарий для продавцов; для второго логика расчёта и создания отправлений другая, и её определяют до начала работ.
Что происходит, если API Ozon недоступен или отвечает ошибкой?
Оформление заказа не ломается: способ доставки, который нельзя подтвердить, становится недоступен, а не «бесплатным». Создание отправления выполняет фоновая задача с повторами для безопасных операций, а неоднозначные ответы уходят в ручную проверку. Статусы обновляются с нарастающей задержкой, завершённые отправления больше не опрашиваются. Сбой API не превращается в потерянный или продублированный заказ.
Сколько занимает разработка такой интеграции?
Зависит от схемы работы, количества исключений в правилах доставки и требований к обработке заказов. Карта пунктов выдачи и расчёт стоимости собираются быстро; основное время уходит на надёжность, сопоставление товаров и операторские сценарии. Порядок работ и объём фиксируются после разбора текущего процесса — с честной оценкой, а не обещанием дат.
Что нужно, чтобы интеграция появилась у нас?
Доступ к кабинету Ozon и частному приложению (Client ID и Client Secret), сопоставление товаров с идентификаторами Ozon, описание правил доставки, упаковки и обработки заказов. Дальше — разбор текущего оформления заказа: карта пунктов выдачи, расчёт стоимости и создание отправлений проектируются под ваш процесс, а не копируются целиком.
