Документация

1. Описание

Компонент предназначен для:
- интеграции вариантов доставки, настройенных в сервисе eShopLogistic в Minishop2 (далее MS2);
- приёма заказов от виджетов eShopLogistic.

Для работы компонента для товаров вашего магазина должен быть указан вес.
Если вес товаров в вашем магазине не указан, но все заказы имеют примерно одинаковый вес, можно настроить дефолтный вес для каждой службы в кабинете eShopLogistic.ru (документация).

Данные о стоимости, сроке и способе доставки записываются в заказ и выводятся на .


2. Базовая настройки модуля

Настройка модуля предельно проста и состоит из 4 простых пунктов:

    • Ключ API eShopLogistic
    • Ключ виджета
    • Секретные коды виджетов
    • Способ доставки по-умолчанию
    • Методы оплаты MS2, ассоциируемые с типом «Оплата картой»
    • Методы оплаты MS2, ассоциируемые с типом «Оплата наличными»
    • Методы оплаты MS2, ассоциируемые с типом «Безналичный расчёт»
    • Методы оплаты MS2, ассоциируемые с типом «Предоплата»
    • Учитывать способ оплаты

    Подробнее о системных настройках смотрите в пункте 6 данной документации.

  1. При установке модуль создаёт 3 новых способа доставки:

    • Самовывоз
      Подразумевается способ доставки до пункта выдачи заказа любой доступной транспортной компанией
    • Курьер
      Подразумевается способ доставки курьером любой доступной транспортной компанией
    • Почта России
      Вариант доставки Почтой России, если она включена для вашего сайта
  2. В чанк оформления заказа в нужное вам место (например, после блока id="deliveries") добавить некэшируванный вызов сниппета eshoplogistic2Order:
    {'!eshoplogistic2Order' | snippet : ['city' => $form.city]}

    Если всё сделано верно, то на странице оформления заказа будет загружен виджет расчёта доставки.

    Если на вашем сайте работает какая-либо система определения местополождения, то для автоматического включения населённого пункта в расчёт доставки можно добавить в запуск сниппета eShopLogisticOrder параметры (на выбор): fias (ФИАС-код населённого пункта) или city (название населённого пункта). Например:

    {'!eshoplogistic2Order' | snippet : ['fias' => $fias]}
    Если fias/city не указаны, то населённый пункт будет определён сервисом eShopLogistic автоматически по IP посетителя.

  3. В чанк оформления заказа добавьте поле для пункта самовывоза eshoplogistic2Order:
    <input type="text" id="terminal" placeholder="Пункт самовывоза (выберите на карте)" name="terminal" value="">
    Обычно поля заказа выводятся в цикле {foreach}, в таком случае вам достаточно добавить элемент 'terminal' в массив полей:
    
        {foreach ['index','region','city','terminal'] as $field}
            // ...
        {/foreach}
        
    

1. Виджет генерирует несколько событий, которыми можно воспользоваться для реализации логики на странице заказа:
esl2onSelectedService - выбор варианта доставки;
esl2onError - ошибка (по какой-то причине ни одного варианта не получено).

Например можно скрыть/показать поля «Пункт самовывоза», «Улица», «Дом», «Квартира» в зависимости от выбранного пользователем варианта доставки:


    <script>
        document.addEventListener('esl2onSelectedService', function(event) {
            // console.log(event.detail)
            const terminal = document.getElementById('terminal')
            if (event.detail.keyDelivery === 'terminal') {
                terminal.style.display = 'block' 
            } else {
                terminal.style.display = 'none' 
            }
        })
    </script>
    

2. Скрипт в комплекте модуля при выборе пользователем способа доставки и пункта ПВЗ автоматически заполняет элементы со следующими идентификаторами:
id="esl-info-service" - название службы доставки
id="esl-info-time" - срок доставки
id="esl-info-address" - адрес пункта самовыовза
id="esl-info-comment" - комментарии (которые указаны в кабинете eShopLogistic для выбранного способа доставки/оплаты.

Вы можете использовать этот функционал для вывода информации в нужное место страницы оформления заказа.


3. Вывод информации о доставке в письмах MS2

Данные о доставке записываются в поле properties объекта msOrder.
Соответственно доступ к ним в чанках писем (и других, где есть доступ в объекту заказа) происходит следующим образом:


    {if $order.properties.esl?}
        Служба: {$order.properties.esl.serice}
        Способ доставки: {$order.properties.esl.mode}
        Срок: {$order.properties.esl.time}
        {if $order.properties.esl.address}
            Пункт самовывоза: {$order.properties.esl.address}
        {/if}
    {/if}
    

4. Настройка виджетов

Доступно 2 типа виджетов: во всплывающем окне и встраиваемый на страницу.

Оба виджета могут быть легко запущены вручную, следуя документации; для максимального упрощения в комплекте модуля есть универсальный сниппет eshoplogistic2Widget.

Запуск виджета в модальном окне:

{'eShopLogistic2Widget' | snippet}

Запуск встроенного виджета:

{'eShopLogistic2Widget' | snippet : ['tpl' => 'tpl.eshoplogistic2.widgetStatic']}

В работе встроенного виджета есть нюанс.
Чтобы избежать автозапуска виджета и соответственно кучи не нужных запросов к серверам при каждом открытии страницы (в т.ч. многочисленными ботами), инициализация виджета происходит по клику на элементе с атрибутом data-widget-load.
Вы можете настроить любую логику запуска на странице (например клик по кнопке или вкладке), а также назначить иное событие, например - скролл до определённого места:


        <script>
            window.addEventListener('scroll', event => {
                const root = document.getElementById('eShopLogisticStatic');
                if(document.documentElement.scrollTop > 300) {
                    root.dispatchEvent(new CustomEvent('eShopLogistic:load'));
                }
            })
        </script>
    

соответствуют параметрам запуска виджетов.


12. Автоматизация ввода адреса

Для того, чтобы посетители вашего сайта могли легко (а главное правильно) вы можете подключить сервис подсказок от Dadata.ru.

В личном кабинете eShopLogistic в окне настройки виджета нужно из личного кабинета Dadata.ru.


5. Стилизация виджетов

Встраиваемый виджет, а также виджет на странице заказа можно стилизовать через CSS.

Для стилизации используйте классы, на -style.


6. Указание габаритов

Для максимально верного расчёта стоимости доставки большинство служб требует указания габаритов груза. Соответственно, желательно учитывать габариты товаров.

1) Если у товаров вашего магазина не указаны габариты в упаковке, можно воспользоваться параметром «Стандартная коробка / стандартный вес» в настройках службы доставки личного кабинета сервиса eShopLogistic.

2) Если у товаров вашего магазина указаны габариты в упаковке, то их необходимо добавить в объект корзины MS2.
Т.к. стандартных полей под габариты MS2 не имеет, очевидно, что данные у вас содержатся либо в полях объекта msProductData, либо в свойствах товара (объект msProductOption).
Проще всего добавить габариты можно с помощью плагина на событие msOnAddToCart:


switch ($modx->event->name) {

    case 'msOnAddToCart':
        $tmp = $cart->get();
        
        /**
        * Например, габариты у нас в dimensions_packing объекта msProductData. 
        * Формат значения dimensions Д*Ш*В, в сантиметрах
        */
        if($product = $modx->getObject('msProductData', $tmp[$key]['id'])) {
            $tmp[$key]['dimensions'] = $product->get('dimensions_packing');
            $cart->set($tmp);	
        }
        break;

}

7. Системные настройки

НастройкаОписание
Ключ API eShopLogistic Обязательно. Доступен после регистрации в сервисе и необходимой минимальной настройки в панели управления. Документация
Ключ виджета Укажите для запуска виджета с помощью сниппета eShopLogisticWidgetModal
Способ доставки по-умолчанию Укажите id варианта доставки по умолчанию, для случая, если не получено расчётных вариантов от сервисе eShopLogistic.
Учитывать способ оплаты Укажите «Да», если при расчёте стоимости доставки в ваших корректирующих правилах учитывается способ оплаты. В противном случае настройка должна быть выключена для снижения нагрузки, т.к. нет необходимости отслеживать способ оплаты. Что такое правила, смотрите в документации.
Методы оплаты MS2, ассоциируемые с типами: «Оплата картой», «Оплата наличными», «Безналичный расчёт», «Предоплата» Для каждой службы доставки у вас могут быть настроены свои способы оплаты, кроме того в системе eShopLogistic способы оплаты имеют свою кодировку, которую нужно связать с идентификаторами способов оплаты на вашем сайте.
Указать id методов, через запятую.
Секретные коды виджетов Укажите секретные коды виджетов, от которых вы хотите принимать заказы на данном сайте.

В настройках виджета необходимо указать обработчик заказа: https://site.ru/assets/components/eshoplogistic/action.php. См. в документации: «Настройки виджета» -> «Корзина/Заказ», параметр «Скрипт обработки заказа».
Документация.
Сообщения при успешном создании заказа / ошибке Если настроен приём заказов от виджета, то данные сообщения будут показаны при соответствующем результате.
Префикс номера заказа Добавляется к номеру заказа MS2.
СSS-файл для фронта Файл css, который будет подключён в корзине сайта при включении модуля.
В случае необходимости внесения изменений в данный файл, создайте новый файл и укажите его здесь. Иначе при обновлении ваши изменения будут затёрты.
JS-файл для фронта Файл js, который будет подключён в корзине сайта при включении модуля.
В случае необходимости внесения изменений в данный файл, создайте новый файл и укажите его здесь. Иначе при обновлении ваши изменения будут затёрты.

8. Системные события

Событие Описание
eShopLogisticOnGetOffers Выполняется после подготовки массива товаров перед отправкой запроса на рассчёт стоимости доставки.
Доступны:
$offers — массив отправленных товарных позиций.
Необходимо вернуть:
$new_offers — новый массив товарных позиций.
Пример:
switch ($modx->event->name) {
    case 'eShopLogisticOnGetOffers':
        if(!empty($offers)) {
            foreach($offers as $offer) {
                // можно изменить при необходимости:
                // цену/количество/вес/габариты
                // ...
            }
        }
        $modx->event->output(['new_offers' => $offers]);
        break;
}

9. Частые вопросы

  • Наиболее частая причина: у товаров на сайте не указан вес.
    При этом в личном кабинете для включённых служб не указана опция «Использовать стандартную коробку / стандартный вес». Соответственно сервис не может рассчитать доставку без веса.
  • Не верно указаны системные настройки или не настроены способы оплаты/доставки в minisop2.
    Проверьте правильность указаний системных настроек, а также связсь способов доставки со способами оплаты.

10. Поддержка

Если у вас возникли какие-либо проблемы с подключением модуля или что-то не устраивает в работе сервиса eShopLogistic, вы всегда можете обратиться за поддержкой:

  • написав обращение в соответствующем разделе личного кабинета eShopLogistic;
  • написав в поддержку модуля через форму modstore.pro;
  • отправив письмо на адрес support@eshoplogistic.ru.

11. Changelog

0.1.0-beta
12.08.2021 публикация