msCDEK

Внимание

Данная документация актуальна для версии компонента 3.0.0 и выше (MODX 3 + MiniShop3).

Требования

MODX 3.x
PHP >= 8.1
MiniShop3 >= 1.8.0-beta1

Возможности

Расчёт стоимости доставки в соответствии с указанными тарифами.
Выбор ПВЗ из списка или на карте (нужно получить ключ для JavaScript API и HTTP Геокодер).
Подсказки при вводе адреса от сервиса DaData.
Сортировка ПВЗ по расстоянию от адреса покупателя с отображением дистанции.
Вкладка СДЭК в карточке заказа в админке: просмотр выбранного ПВЗ, смена ПВЗ и пересчёт стоимости доставки без перезагрузки страницы.

Порядок работы

Для расчёта стоимости доставки компоненту требуется почтовый индекс, который следует указать в поле [name="index"]. Пользователь может ввести его сам или вы можете настроить подсказки при вводе адреса, и тогда при выборе одной из подсказок индекс заполнится автоматически.

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

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

Информация

Компонент умеет учитывать страну, для этого нужно добавить поле [name="country"]. Страна учитывается при предоставлении подсказок, при получении списка ПВЗ и при расчёте стоимости.

Подбор тарифа (с 3.3.0)

Перед расчётом компонент запрашивает у СДЭК список доступных для адреса и посылки тарифов (calculator/tarifflist) и выбирает самый дешёвый из подходящих. Итоговая стоимость затем считается через calculator/tariff, как и раньше, — с НДС, наценкой способа доставки и правилами округления.

Подходящим считается тариф, который совпадает со способом доставки и режимом отправителя:

способ из door настройки mscdek_main_deliveries — тарифы «до двери»;
способ из pvz — тарифы до пункта выдачи и/или постамата, в зависимости от mscdek_main_point_types. Если покупатель уже выбрал точку, учитывается её тип;
mscdek_main_sender_mode задаёт сторону отправителя: warehouse (по умолчанию) — вы сдаёте посылки на склад СДЭК, door — СДЭК забирает от двери, any — без ограничения.

Настройка mscdek_main_tariffs работает в двух режимах:

пустая — выбирается самый дешёвый из всех подходящих тарифов;
заполнена — выбор только из перечисленных кодов для каждого способа доставки, коды через запятую: {"2":"137,233","3":"136,234"}. Значение в старом формате с одним кодом ({"2":"137","3":"136"}) продолжает работать.

Настройка	Значения	По умолчанию
`mscdek_main_tariffs`	JSON `{"ID способа доставки":"коды тарифов через запятую"}`	пусто
`mscdek_main_point_types`	`PVZ` — пункты выдачи, `POSTAMAT` — постаматы, `ALL` — все	`PVZ`
`mscdek_main_sender_mode`	`warehouse`, `door`, `any`	`warehouse`

mscdek_main_point_types управляет и точками на карте, и тарифами в подборе: при PVZ постаматы не показываются и тарифы до постамата не выбираются.

Если подходящего тарифа в ответе СДЭК нет, используется запасной код: число в поле «Описание» способа доставки, а если его нет — первый код из mscdek_main_tariffs для этого способа. При установке компонент больше не записывает код тарифа в описание способа доставки.

После подбора вызывается событие msCdekOnSetTariffCode: плагин по-прежнему может заменить $object->tariffCode.

Дополнительные услуги (с 3.4.0)

Дополнительные услуги СДЭК, которые нужно учесть в стоимости доставки, задаются в настройке mscdek_main_services. Компонент передаёт их массивом services и в calculator/tarifflist, и в calculator/tariff, поэтому услуги влияют и на подбор тарифа, и на итоговую стоимость.

Настройка	Значения	По умолчанию
`mscdek_main_services`	JSON `{"ID способа доставки или *":{"КОД_УСЛУГИ":"параметр"}}`	пусто

Ключ * — услуги для всех способов доставки. Услуги конкретного способа дополняют *, а при совпадении кода переопределяют его. Пример — страховка по стоимости корзины для всех способов и примерка для способа 5:

json

{"*":{"INSURANCE":"{cart_cost}"},"5":{"TRYING_ON":""}}

В параметре доступны плейсхолдеры:

{cart_cost} — стоимость корзины;
{count} — количество товаров;
{weight} — вес посылок (в тех же единицах, что и вес, который уходит в СДЭК).

Пустая строка — услуга без параметра. Пустая настройка — услуги не передаются, расчёт как раньше.

Внимание

Если услуга недоступна для выбранного тарифа, СДЭК вернёт ошибку и доставка не посчитается. Для страховки СДЭК требует объявленную стоимость: INSURANCE без параметра даёт ошибку «Не задан обязательный параметр Объявленная стоимость», поэтому указывайте {cart_cost}.

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

Информация

Ни один из HTML-блоков, которые будут упомянуты ниже, не является обязательным для расчёта стоимости доставки, кроме поля ввода почтового индекса.

После установки компонента ОБЯЗАТЕЛЬНО выполнить первые 6 пунктов из списка ниже:

Перейдите в системные настройки и выберите пространство имён mscdek;
Установите свои значения в поля с ключами mscdek_main_login и mscdek_main_password;
Установите индекс отправителя в поле mscdek_main_sender_index;
Убедитесь, что в поле mscdek_main_deliveries установлены правильные ID способов доставки (door — доставка до двери, pvz — доставка в ПВЗ);
Подробнее
Например ID доставки до двери у вас 2, а до ПВЗ 3, тогда значение этой настройки будет выглядеть так {"door":"2","pvz":"3"}. При установке пакета способы доставки создаются автоматически, а их ID прописываются в эту настройку.
Тарифы подбираются автоматически: самый дешёвый из подходящих по способу доставки. Чтобы ограничить выбор, перечислите коды в mscdek_main_tariffs;
Подробнее
Например ID доставки до двери у вас 2, а до ПВЗ 3, и нужны только тарифы «Посылка» и «Экономичная посылка»: {"2":"137,233","3":"136,234"}. Подробнее — в разделе Подбор тарифа.
Установите номера шаблонов (через запятую) с формой оформления заказа в поле mscdek_main_templates (чтобы скрипты фронтенда подключались только на страницах с этим шаблоном);
Если используете доставку до ПВЗ, то в чанке с формой оформления заказа добавьте код

html

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

Информация

Если отправка будет не из РФ, укажите корректный код страны отправителя в системной настройке mscdek_main_sender_country.

Внимание

Список ПВЗ должен выводиться в элементе select как в чанке mscdekListWrap или не выводиться вовсе.

Информация

Если решили не выводить список ПВЗ, вставляйте вместо

html

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

скрытое поле

html

<input type="hidden" name="point">

Вывод карты со списком ПВЗ

Начиная с версии 3.1.0 поддерживаются два провайдера карт. Выбор задаётся системной настройкой mscdek_main_map_provider:

Значение	Провайдер	Ключ
`osm` (по умолчанию)	OpenStreetMap + Leaflet 1.9.4	не требуется
`yandex`	Яндекс.Карты JS API v3	обязателен

Вариант 1. OpenStreetMap (по умолчанию)

Убедитесь, что mscdek_main_map_provider имеет значение osm (так и стоит после чистой установки).
В шаблон с формой оформления заказа вставьте код:

html

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

Информация

Leaflet и плагин leaflet.markercluster подтягиваются с публичного CDN (cdn.jsdelivr.net) автоматически — никаких дополнительных подключений в шаблоне делать не нужно.

Внимание

Карта рендерится на бесплатных тайлах tile.openstreetmap.org. Согласно OSM Tile Usage Policy, высоконагруженное коммерческое использование с этих тайлов не приветствуется. При росте трафика стоит подключить свой кеш/прокси тайлов или платный тайл-сервис.

Вариант 2. Яндекс.Карты

Получите ключ для JavaScript API и HTTP Геокодер.
В системной настройке mscdek_main_map_provider укажите yandex.
Установите полученный ключ в системную настройку mscdek_main_map_api_key.
В шаблон с формой оформления заказа вставьте тот же код:

html

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

Информация

До версии 3.1.0 ключ Яндекс.Карт хранился в mscdek_main_yandex_map_api_key. При обновлении пакета значение автоматически переносится в mscdek_main_map_api_key, а mscdek_main_map_provider выставляется в yandex. Если до этого ключа не было — mscdek_main_map_provider останется osm. Старая настройка удаляется.

Подсказки при вводе адреса

Получите токен в сервисе DaData;
Установите полученный токен в системную настройку с ключом mscdek_main_dadata_token;
Полю, в которое пользователь будет вводить адрес, добавить атрибут data-mscdek-suggest-field;
В шаблон с формой оформления заказа вставьте код

html

<ul class="hide" data-mscdek-suggest-list></ul>

Вывод информации о сроках доставки

В шаблон с формой оформления заказа вставьте код

html

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

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

Компонент может рассчитывать количество пакетов разными способами. Способ расчёта определяется системной настройкой mscdek_packages_packages_calc_type. Возможные значения:

0 - при этом способе расчёта будет добавлен один пакет (метод по умолчанию);
1 - будет добавлено столько пакетов, сколько уникальных позиций товаров есть в корзине;
2 - будет добавлено столько пакетов, сколько товаров есть в корзине;
3 - количество пакетов будет рассчитано исходя из объема одного пакета, объем одного пакета рассчитывается по значению системной настройки mscdek_packages_default_size; Например, если в корзине лежит товар с размерами 20х30х10 и весом 1 кг в количестве 3 штуки, а mscdek_packages_default_size имеет значение 20х30х20, то будет добавлено два пакета:

php

$packages = [
    [
        'weight' => 2,
        'length' => 20,
        'width' => 30,
        'height' => 20
    ],
    [
        'weight' => 1,
        'length' => 20,
        'width' => 30,
        'height' => 10
    ],
];

4 - количество вообще не рассчитывается, а берётся один пакет с размерами и весом из системных настроек.
5 - будет добавлен один пакет с размерами из системных настроек и весом равным сумме весов всех товаров в корзине.

Отдельными системными настройками можно управлять учётом количества (mscdek_packages_use_product_count), индивидуальных размеров товаров (mscdek_packages_use_individual_sizes) и индивидуального веса товаров (mscdek_packages_use_individual_weight) при расчёте количества пакетов. По умолчанию все настройки имеют значение false, т.е. при расчёте количества пакетов не учитывается ни реальное количество, ни индивидуальные размеры, ни вес, а берутся значения по умолчанию (из системных настроек и количество = 1).

Внимание

Для способов расчёта количества пакетов 0,1,2,3 в системной настройке mscdek_packages_default_size следует указывать размер упаковки одного товара, а для способов 4,5 - размеры всего пакета. Это же касается и настройки mscdek_packages_package_default_weight.

Информация

Для способов расчёта количества пакетов 0,1,3 вес пакета складывается из суммы весов товаров умноженных на их количество, длина и ширина - максимальное значение из всех длин и ширин товаров, высота - сумма высот всех товаров. Это можно представить как складывание маленьких коробок (товаров) в большую коробку (пакет) стопкой (т.е. одна на другую). Для способа 2 размеры пакета соответствуют размерам товара. Для способов 4,5 - размеры пакета берутся из системных настроек.

Расчёт доставки в другие страны

СДЭК поддерживает расчёт доставки в Казахстан и Беларусь. Чтобы это работало на вашем сайте, нужно передать в заказ информацию о стране получателя через поле country.

Если в системных настройках не указан токен сервиса DaData, то код страны получателя следует передавать в формате ISO 3166-1 alpha 2. В противном случае - нужно передавать название страны на русском языке.

msCDEK ​

Требования ​

Возможности ​

Порядок работы ​

Подбор тарифа (с 3.3.0) ​

Дополнительные услуги (с 3.4.0) ​

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

Вывод карты со списком ПВЗ ​

Вариант 1. OpenStreetMap (по умолчанию) ​

Вариант 2. Яндекс.Карты ​

Подсказки при вводе адреса ​

Вывод информации о сроках доставки ​

Расчёт количества пакетов ​

Расчёт доставки в другие страны ​

msCDEK

Требования

Возможности

Порядок работы

Подбор тарифа (с 3.3.0)

Дополнительные услуги (с 3.4.0)

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

Вывод карты со списком ПВЗ

Вариант 1. OpenStreetMap (по умолчанию)

Вариант 2. Яндекс.Карты

Подсказки при вводе адреса

Вывод информации о сроках доставки

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

Расчёт доставки в другие страны