msCDEK

Требования

• MODX 3.x
• PHP >= 8.2
• MiniShop3 >= 1.8.0-beta1

Важно: название изменилось

Раньше компонент назывался ms_CDEK2, теперь произошло возвращение к корням — msCDEK, но с новой кодовой базой.

Что это

msCDEK — компонент для расчёта стоимости доставки через СДЭК, выбора пункта выдачи (ПВЗ) из списка или на карте, подсказок адреса через DaData. Работает с MiniShop3 версии 1.8.0-beta1 и выше.

Что нового в 3.0

• Вкладка СДЭК в карточке заказа — при редактировании заказа в админке появляется отдельная вкладка. На ней можно посмотреть выбранный ПВЗ, выбрать другой из списка, увидеть карту и пересчитать стоимость доставки. Всё без перезагрузки страницы.
• Сортировка ПВЗ по расстоянию — и на фронтенде, и в админке список пунктов выдачи сортируется от ближайшего к дальнему. Рядом с каждым ПВЗ показывается расстояние в километрах.
• Карта центрируется на ближайшем ПВЗ — при загрузке списка карта автоматически перемещается к ближайшему пункту выдачи и увеличивает масштаб (только на фронте).
• ПВЗ сохраняется в заказе — при оформлении заказа код выбранного ПВЗ передаётся в MiniShop3 через стандартный механизм валидации полей. Не нужно ничего дополнительно настраивать.
• Пересчёт доставки из админки — кнопка на вкладке СДЭК вызывает расчёт стоимости через API СДЭК на основе товаров в заказе и обновляет стоимость.

Как выглядит вкладка СДЭК в админке

На странице редактирования заказа появляется вкладка «СДЭК» (через механизм MS3OrderTabsRegistry). На ней:
— стоимость доставки
— код выбранного ПВЗ
— список ПВЗ с расстоянием
— карта Яндекс с маркерами (если настроен API-ключ)
— кнопка «Пересчитать доставку» (по нажатию происходит пересчёт стоимости доставки и сохранение данных)

Как работает фронтенд

Для вывода списка ПВЗ на странице заказа:

<div data-mscdek-list></div>

Для карты:

<div class="hide" data-mscdek-map></div>

Для подсказок адреса добавьте атрибут полю ввода и блок для списка:

<input type="text" name="street" data-mscdek-suggest-field>
<ul class="hide" data-mscdek-suggest-list></ul>

Для отображения сроков и стоимости:

<div class="hide" data-mscdek-status></div>

REST API

Компонент предоставляет REST API через роутер MiniShop3:

GET  /api/v1/cdek/suggestions   — подсказки адреса
GET  /api/v1/cdek/points        — список ПВЗ
GET  /api/v1/cdek/status        — статус доставки
POST /api/v1/cdek/status        — сохранение выбранного ПВЗ
GET  /api/v1/cdek/postal-code   — индекс по городу
POST /api/v1/cdek/order/update-point — обновление ПВЗ из админки

Расчёт пакетов

Компонент поддерживает 6 режимов расчёта пакетов для отправки:

• 0 — один пакет, размеры складываются из товаров
• 1 — по одному пакету на каждую позицию
• 2 — по одному пакету на каждый товар
• 3 — расчёт по объёму (товары укладываются в коробки)
• 4 — один пакет с размерами из настроек
• 5 — один пакет с размерами из настроек и суммой весов товаров

События для расширения

Компонент генерирует события на PHP и JavaScript, которые позволяют изменить поведение без редактирования кода:

// PHP: подменить тариф
switch ($modx->event->name) {
    case 'msCdekOnSetTariffCode':
        $object->tariffCode = 123;
        break;
}

// JS: изменить масштаб карты
document.addEventListener('mscdek:map:show', e => {
    e.detail.object.mapUpdParams.zoom = 10;
});

Быстрый старт

1. Установите пакет через менеджер пакетов MODX
2. В системных настройках (пространство имён mscdek) укажите логин и пароль API СДЭК
3. Укажите почтовый индекс отправителя
4. ID способов доставки и тарифы заполняются автоматически при установке
5. Укажите шаблоны страниц с формой заказа
6. Добавьте нужные блоки в чанк формы заказа