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

1. Описание

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

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

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

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

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

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

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

2. Включить методы доставки и связать их со способами оплаты в настройках Minishop2

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

   • Самовывоз
     Подразумевается способ доставки до пункта выдачи заказа любой доступной транспортной компанией
   • Курьер
     Подразумевается способ доставки курьером любой доступной транспортной компанией
   • Почта России
     Вариант доставки Почтой России, если она включена для вашего сайта
3. В чанк оформления заказа в нужное вам место (например, после блока id="deliveries") добавить некэшируванный вызов сниппета eshoplogistic2Order:
   

   {'!eshoplogistic2Order' | snippet : ['city' => $form.city]}

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

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

   {'!eshoplogistic2Order' | snippet : ['fias' => $fias]}

   Если fias/city не указаны, то населённый пункт будет определён сервисом eShopLogistic автоматически по IP посетителя.

4. В чанк оформления заказа добавьте поле для пункта самовывоза eshoplogistic2Order:
   

   <input type="text" id="terminal" placeholder="Пункт самовывоза (выберите на карте)" name="terminal" value="">

   Обычно поля заказа выводятся в цикле {foreach}, в таком случае вам достаточно добавить элемент 'terminal' в массив полей:

   
       {foreach ['index','region','city','terminal'] as $field}
           // ...
       {/foreach}
       
   

События, генерируемые виджетом

Виджет генерирует несколько событий, которыми можно воспользоваться для реализации логики на странице заказа:
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>
    

Информация, доступная на странице

Скрипт в комплекте модуля при выборе пользователем способа доставки и пункта ПВЗ автоматически заполняет элементы со следующими идентификаторами:
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.service}
        Способ доставки: {$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']}

В настройках виджета необходимо указать обработчик заказа: https://site.ru/assets/components/eshoplogistic2/action.php. См. в документации: «Настройки виджета» -> «Корзина/Заказ», параметр «Скрипт обработки заказа».
Документация

Есть особенность в работе встроенного виджета.
Чтобы избежать автозапуска виджета и соответственно кучи не нужных запросов к серверам при каждом открытии страницы (в т.ч. многочисленными ботами), инициализация виджета происходит по клику на элементе с атрибутом 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. Системные настройки

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

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

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

10. Поддержка

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

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

11. Changelog

0.0.6-pl
01.02.2022
Доработана логика работы с методами доставки ms2 в eshoplogistic2.js

0.0.5-beta
04.09.2021
Доработана логика работы с методами доставки ms2 в eshoplogistic2.js

0.0.4-beta
24.08.2021
Изменена логика работы с методами доставки ms2 в eshoplogistic2.js

0.0.3-beta
24.08.2021
Исправление метода confirm eshoplogistic2.js

0.0.2-beta
18.08.2021
Исправление метода search eshoplogistic2.js

0.0.1-beta
13.08.2021