Доставка

СДЭК

Доставка СДЭК для магазина на SkeekS.

Описание

Модуль подключает доставку СДЭК к магазину на SkeekS Платформе. Покупатель выбирает пункт выдачи на карте прямо при оформлении заказа, а стоимость доставки считается и добавляется к заказу автоматически.

Что получает покупатель

  • Карта пунктов выдачи СДЭК с поиском по адресу и фильтрами — прямо на странице оформления заказа.
  • Город на карте подставляется сам: заданный в настройках или определённый по местоположению покупателя.
  • Выбор тарифа СДЭК со сроком и ценой доставки, если этот режим включён.
  • Стоимость доставки пересчитывается автоматически, когда меняется состав заказа.

Два режима расчёта

  • Фиксированная цена. Покупатель выбирает только пункт выдачи, стоимость берётся из настройки способа доставки.
  • Тариф СДЭК. Покупатель выбирает пункт и тариф, стоимость тарифа добавляется к заказу.

Что настраивается в панели управления

  • Название, описание и логотип способа доставки, порядок в списке.
  • Цена доставки и сумма заказа, от которой доставка бесплатная.
  • Способы оплаты, доступные при доставке СДЭК.
  • Город отправления, город по умолчанию и страна, для которой показываются пункты выдачи.
  • Обязателен ли выбор пункта выдачи для оформления заказа.

Что понадобится

Договор со СДЭК и ключи интеграции — идентификатор и пароль из личного кабинета СДЭК (раздел «Интеграция»). Ключи указываются в настройках способа доставки «СДЭК» в разделе «Магазин → Службы доставки».

Установка

Подключите пакет в корне проекта на SkeekS Платформе, затем примените миграции проекта.

composer require skeeks/cms-shop-delivery-cdek

Зависимости

Инструкция из репозитория

cms-shop-delivery-cdek

Courier delivery and sender handoff

Each delivery method has independent recipientMode (office by default, or door) and senderMode (all by default, office, or door). Old sites retain pickup selection and their previous tariff list. Create/configure two delivery methods for separate cart buttons. Sender office means the merchant hands parcels to CDEK; sender door means CDEK collects from the sender. Filter both the pickup widget response and server-side quote by these modes.

Courier mode renders an address form without loading Yandex/provider maps. Cities autocomplete after two characters with a 400 ms debounce using CDEK location/suggest/cities with name. location/cities with city matches complete names and is unsuitable for prefixes. Suggestions provide code and full_name; show region/country to distinguish duplicate names. The server resolves the chosen CDEK city code; do not trust a posted city name. Street and house are mandatory; apartment/office, entrance, floor and courier comment are optional. Save them in handler data and standard order delivery fields. Fixed-price courier mode still requires and validates the address.

Calculated courier tariffs use the current cart and verified city/address. Only matching sender-to-door tariffs are offered. Retain tariff selection on quantity changes, invalidate options on address edits, and force verification at checkout through the common delivery lifecycle. Include delivery mode and address in the quote fingerprint. Use a hidden canonical tariff input so disabling the visible select during loading does not remove its code from a concurrent form save. Apply async responses only to the matching saved address, active delivery tab and latest request. Unload inactive pickup map iframes. Load tariffs automatically after address fields are saved; show the retry button only after a failed tariff request.

This package calculates delivery and saves checkout details. It does not create a CDEK waybill or book a courier collection automatically.

Automatic recalculation

Requires the delivery calculation contract in skeeks/cms-shop >= 3.2.7.26. In tariff mode the callback stores the selected tariff_code. The server resolves the pickup point's city through CDEK, builds parcels from the current order and requests calculator/tarifflist; the browser's amount is not trusted. The widget and server share CdekDeliveryHandler::getOrderPackages() (grams, dimensions converted from mm to cm; fractional units round up to whole parcels).

Successful quotes are reused for up to 300 seconds only while point, tariff, origin, account, currency and packages match. Failures clear the old price and are retried; checkout rejects them. A missing/unavailable tariff requires the buyer to select one again. Old selections without a tariff code require one reselection. Automatic CDEK calculations currently support RUB.

The shop owns mutation/open-cart/checkout triggers. The adapter implements supportsAutomaticCalculation() and refreshDeliveryPrice($force) rather than subscribing independently to every item/controller event. Completed orders keep their agreed delivery price. Fixed-price mode is unchanged.

The checkout invalidates its map iframe when the server's delivery input hash changes. An open map rebuilds with current parcels. A hidden map stays unloaded: selecting a point removes its iframe, and a saved selection does not create one on cart load. Opening the map loads it once after the selection update returns, using the current basket. Fixed-price mode does not invalidate on cart changes.

Run php tests/delivery-recalculation.php <vendor/autoload.php> for isolated SQLite tests of item callbacks, totals, cache freshness, server-owned metadata, failure/unavailable/zero quotes, fixed price and completed orders.

Widget v4 checkout contract

The optional defaultLatitude and defaultLongitude fields set the initial map centre without Yandex geocoding. Validate them together (latitude -90..90, longitude -180..180); comma decimals are normalized. The widget receives [longitude, latitude]. Explicit coordinates take priority; otherwise known defaultCity names use the saved approximate city-centre presets, and other names retain geocoding. Empty city defaults to Moscow. Admin preset buttons fill the city and both coordinates in the current form without submitting it. Coordinates affect only the initial camera, never the quote's origin or destination. Yandex Maps itself still requires a valid key; text search still uses the geocoder.

The map uses the pinned official widget 4.0.0. It requests pickup points for the visible rectangle (action=byCoordinate), forwarded to deliverypoints/byPolygons. Panning/zooming loads the new area after the widget's 500 ms debounce and cancels obsolete browser requests. Do not supply offices/officesRaw: that opts out of loading by bounds. Tariffs remain calculated for the selected destination, independently of loading markers. Update the map view and CdekService together: v4 checks the major version in X-Service-Version. The legacy offices action remains for older integrations.

Use recipient mode (sender: false) for a buyer choosing a delivery point. isChooseTariff defaults to 0, including for old configurations that only contain isCalculatePrice. That legacy key remains loadable but no longer controls the checkout. The administration form exposes the new setting instead.

With isChooseTariff=0, pass from: null and empty goods to the widget: it selects a pickup point without requesting or presenting tariffs. Do not render the checkout price input, and always use the delivery method's fixed price, even when the order contains an old calculated price.

With isChooseTariff=1, pass the configured origin and order parcels and render the checkout price input. The buyer selects a pickup point and tariff. The map's onChoose(type, tariff, address) callback passes the selected tariff and pickup point to the checkout. The delivery amount is tariff.delivery_sum, not a top-level price. When calculation is enabled, the checkout stores that amount as a string in CdekCheckoutModel[price] and submits the delivery form so the order totals are refreshed. A missing tariff must clear the previous amount rather than retain a price from another point.

After changing this integration, verify selection of a pickup point, the delivery line and total, and persistence after reloading the cart. Also verify that disabling calculation leaves the price input absent. Selecting a pickup point does not require placing an order.

README на GitHub

Поддержка

Вопросы по установке и работе решения можно задать командой SkeekS или завести обращение в репозитории.

Обновления

v2.2.2

Исправлена загрузка тарифов курьерской доставки СДЭК при переключении с пункта выдачи.

Теперь после выбора города и заполнения адреса доступные тарифы появляются автоматически. Не нужно перезагружать страницу, повторно выбирать город или нажимать отдельную кнопку расчёта. Достаточно закончить ввод: форма сохраняет адрес после короткой паузы, даже если курсор остаётся в последнем поле.

При изменении адреса прежний список тарифов сбрасывается и обновляется для новых данных. После выбора тарифа рассчитанная стоимость включается в итог заказа. Дополнительные сведения для курьера — подъезд, этаж и комментарий — также сохраняются автоматически.

Исправление проверено на действующем сайте: открытие корзины с выбранным ПВЗ, переход на курьерскую доставку, первое заполнение адреса, выбор тарифа и обратное переключение на карту пунктов выдачи.

v2.2.1

Исправлено переключение между курьерской доставкой СДЭК и пунктами выдачи в корзине.

  • При переходе с курьерской доставки на ПВЗ карта открывается без перезагрузки страницы.
  • При переходе с ПВЗ на курьерскую доставку доступные тарифы загружаются автоматически после заполнения адреса.
  • Скрытая карта по-прежнему выгружается и не замедляет работу с курьерской формой.

Обновление рекомендуется для магазинов, использующих оба способа доставки СДЭК. Настройки доставки менять не требуется.

v2.2.0

В модуле СДЭК появилась курьерская доставка до адреса покупателя. Теперь магазин может предложить в корзине два отдельных способа получения: доставку в пункт выдачи и доставку курьером.

Что изменилось для покупателей
  • Доставка до двери. Покупатель выбирает город, указывает улицу и дом. При необходимости можно добавить квартиру или офис, подъезд, этаж и комментарий курьеру.
  • Удобный поиск города. Подсказки из справочника СДЭК появляются в выпадающем списке уже после двух введённых букв. В названии указан регион, чтобы было проще выбрать нужный населённый пункт.
  • Расчёт без лишних действий. После заполнения адреса доступные тарифы со стоимостью и сроками загружаются автоматически. Покупатель выбирает тариф — доставка добавляется к итоговой сумме заказа.
  • Актуальная стоимость. При изменении количества или состава товаров выбранный тариф пересчитывается автоматически. Если тариф становится недоступен, покупатель видит сообщение и должен выбрать доступный вариант перед оформлением заказа.
Новые настройки для магазина

В настройках способа доставки СДЭК можно выбрать:

  • Как покупатель получает заказ: в пункте выдачи или курьером до двери.
  • Как отправление передаётся СДЭК: магазин сдаёт его в пункт СДЭК либо курьер забирает у отправителя.

В корзине будут предложены только тарифы, подходящие выбранной схеме: «склад → склад», «склад → дверь», «дверь → склад» или «дверь → дверь». В названиях тарифов «склад» означает пункт СДЭК, а «дверь» — адрес отправителя или получателя.

Чтобы предложить оба варианта получения, создайте два способа доставки с обработчиком СДЭК и настройте каждый отдельно. Для расчёта по тарифам включите настройку «Выбирать тарифы при выборе пункта» — она также действует в курьерском режиме. При отключённой настройке используется фиксированная стоимость способа доставки.

Совместимость и работа корзины

Существующие способы доставки после обновления сохраняют режим ПВЗ и прежние настройки. Курьерская доставка включается отдельно. Карта пунктов выдачи выгружается при переходе на другой способ доставки; курьерская форма работает без загрузки карты.

Адрес и дополнительные указания покупателя сохраняются в заказе. Обновление отвечает за выбор и расчёт доставки; создание накладной СДЭК и вызов курьера выполняются отдельно.

v2.1.5

СДЭК: центр карты по координатам и быстрый выбор города

Добавили возможность задать начальное положение карты СДЭК без обращения к геокодеру. Теперь карта может сразу открываться в нужном месте по сохранённым координатам, без преобразования названия города в точку на карте.

Удобная настройка центра карты

В настройках доставки появились необязательные поля «Широта центра карты» и «Долгота центра карты» с пояснениями, зачем они нужны. Заполненные координаты имеют приоритет над названием города. Можно указать центр города, район или другую удобную точку.

Готовые города в один клик

Добавили кнопки для 12 городов: Москвы, Санкт-Петербурга, Рязани, Калуги, Нижнего Новгорода, Казани, Екатеринбурга, Новосибирска, Самары, Краснодара, Ростова-на-Дону и Воронежа. Нажатие подставляет город, широту и долготу — остаётся сохранить настройки.

Если один из этих городов уже указан в настройках, его сохранённые координаты используются автоматически, даже когда новые поля пусты. Для остальных городов без координат сохраняется определение по названию. Если город не указан, карта открывается в Москве.

Покупатель свободно выбирает пункт

Координаты задают только начальный центр карты. Покупатель может перемещать её, менять масштаб и выбирать пункты в других городах. Город отправки и правила расчёта стоимости доставки не меняются.

Что важно знать

Для самой карты по-прежнему нужен действующий ключ Яндекс.Карт, а для поиска адресов текстом — доступ к геокодеру. Координаты позволяют обойти геокодер при открытии карты, но не заменяют авторизацию СДЭК для загрузки пунктов и расчёта тарифов.

v2.1.4

СДЭК: более быстрая загрузка карты пунктов выдачи

Улучшили работу карты СДЭК в корзине. Теперь при её открытии загружаются пункты выдачи только для видимой области, а не полный список. Это уменьшает объём данных и нагрузку на браузер, особенно на телефонах и при медленном интернете.

Карта подгружает пункты по мере просмотра

При перемещении карты и изменении масштаба список пунктов обновляется для новой области. Быстрые движения объединяются, чтобы не отправлять лишние запросы. Поиск другого города также загружает пункты в выбранной области.

Расчёт доставки работает как прежде

Покупатель выбирает пункт и, если включён расчёт, подходящий тариф. Стоимость автоматически обновляется при изменении состава корзины. После подтверждения пункта карта выгружается и не замедляет изменение количества товаров. При повторном открытии используются актуальные данные корзины.

Обновление не требует новых настроек

Оба режима сохранены: выбор пункта с фиксированной стоимостью и выбор пункта с расчётом тарифа. Для включения новой загрузки карты достаточно обновить модуль СДЭК до версии 2.1.4. Требуется модуль магазина skeeks/cms-shop версии 3.2.7.26 или новее.

v2.1.3

СДЭК: автоматический пересчёт доставки и более лёгкая корзина

Обновили модуль СДЭК, чтобы покупатель видел актуальную стоимость доставки при изменении заказа, а скрытая карта не замедляла работу с корзиной.

Два режима доставки

В настройках СДЭК появился переключатель «Выбирать тарифы при выборе пункта»: — Нет: покупатель выбирает только пункт выдачи, а стоимость берётся из фиксированного поля варианта доставки. Этот режим установлен по умолчанию. — Да: покупатель выбирает пункт и тариф на карте, а стоимость доставки рассчитывается для его корзины.

Стоимость обновляется автоматически

При изменении количества, добавлении или удалении товара доставка пересчитывается для выбранного пункта и тарифа. Расчёт также проверяется при возвращении в корзину и перед оформлением заказа. Если при окончательной проверке цена изменилась, покупатель увидит новый итог и сможет проверить его перед повторным оформлением.

Если выбранный тариф недоступен или СДЭК не смог рассчитать доставку, в корзине появится красное сообщение. Оформление будет остановлено до успешного расчёта или выбора другого способа доставки.

Карта загружается только тогда, когда нужна

После выбора пункта карта выгружается. Изменение количества товаров больше не запускает скрытую карту: стоимость обновляется на сервере. При нажатии «Выбрать другой пункт» карта загрузится с актуальным составом корзины. Открытая карта также обновляется при изменении товаров; незавершённый выбор потребуется повторить.

Что учесть при обновлении

Для расчёта тарифов установите модуль СДЭК 2.1.3 вместе с модулем магазина 3.2.7.26 или новее и включите «Выбирать тарифы при выборе пункта». После обновления проверьте этот переключатель: прежняя настройка «Рассчитывать цену по выбранному ПВЗ» больше не включает расчёт тарифов.

Для расчёта используются вес и размеры товаров, поэтому заполните их в каталоге. Автоматический расчёт поддерживает рубли. Если в старой корзине пункт был сохранён без кода тарифа, покупателю потребуется один раз выбрать пункт и тариф заново.

v2.1.1
v2.1.0
v2.0.0.2
v2.0.0.1
Показать ещё 5 обновлений