ms_CDEK2

Внимание

Данная документация актуальна для версии компонента 2.4.1 и выше.

Внимание

Компонент msDeliveryProps больше не нужен.

Требования

Modx 2.8.x
PHP >=7.4
MySQL 5.7

Возможности

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

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

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

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

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

Информация

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

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

Внимание

При использовании SendIt 2.4.0+ на странице оформления заказа должен быть хотя один ЛЮБОЙ html-элемент с атрибутом data-si-form

Информация

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

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

Перейдите в системные настройки и выберите пространство имён ms_cdek2;
Установите свои значения в поля с ключами ms_cdek2_login и ms_cdek2_password;
Установите индекс отправителя в поле ms_cdek2_sender_index;
Убедитесь, что в поле ms_cdek2_deliveries установлены правильные ID способов доставки (door — доставка до двери, pvz — доставка в ПВЗ);
Подробнее
Например ID достаки до двери у вас 9, а до ПВЗ 10, тогда значение этой настройки будет выглядеть так {"door":"9","pvz":"10"}.
Убедитесь, что в поле ms_cdek2_tariffs установлены правильные ID способов доставки и ID тарифов СДЭК (доставка до двери для ИМ тариф 137, доставка в ПВЗ - 136);
Подробнее
Например ID достаки до двери у вас 9, а до ПВЗ 10, тогда значение этой настройки будет выглядеть так {"9":"137","10":"136"}.
Установите номер шаблона с формой оформления заказа в поле ms_cdek2_template (чтобы скрипты фронтэнда подключались только на страницах с этим шаблоном);
Если используете доставку до ПВЗ, то в чанке с формой оформления заказа добавьте код

html

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

Информация

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

Внимание

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

Информация

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

html

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

скрытое поле

html

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

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

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

html

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

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

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

html

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

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

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

html

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

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

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

0 - при этом способе расчёта будет добавлен один пакет (метод по умолчанию);
1 - будет добавлено столько пакетов сколько уникальных позиций товаров есть в корзине;
2 - будет добавлено столько пакетов сколько товаров есть в корзине;
3 - количество пакетов будет рассчитано исходя из объема одного пакета, объем одного пакета рассчитывается по значению системной настройки ms_cdek2_default_size; Например, если в корзине лежит товар с размерами 20х30х10 и весом 1 кг в количестве 3 штуки, а ms_cdek2_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 - будет добавлен один пакет с размерами из системных настроек и весом равным сумме весов всех товаров в корзине.

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

Внимание

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

Информация

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

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

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

Внимание

miniShop2 не поддерживает работу с полями типа select, т.е. если вы хотите сделать выбор страны через такое поле, нужно написать дополнительный код на JavaScript.

const countryField = document.querySelector('select[name="country"]');
countryField && countryField.addEventListener('change', () => {
    miniShop2.Order.add('country', countryField.value);
 });

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

handyShop

Утилиты