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

Описание

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

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

Чанки компонента рассчитаны на работу c pdoTools и шаблонизатором fenom.

Настройка вариантов доставки MS2

Необходима стандартная настройка нужных вам способов доставки в разделе «Пакеты / miniShop2 / Настройки».

Включите нужный вариант, активируйте нужные способы оплаты. Можно добавить логотип (варианты идут с компонентом в папке assets/components/eshoplogistic/logos/)

Настройка способов доставки MS2

Возможна ситуация, когда ни одного варианта доставки от eShopLogistic не будет получено (например в указанный населённый пункт просто никто не доставвляет или в данный момент по каким-то причинам система расчёта доставок будет недоступна).
Для такого случая рекомендуем создать отдельный способ доставки и указать его затем в системной настройке «Способ доставки по-умолчанию». Например такой:

Системные настройки компонента eShopLogistic

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

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

Настройка оформления заказа

  1. В системных настройках MS2 указать ms2_order_handler_class равным eslOrderHandler
    Внимание!
    Компонент реализует расширение класса msOrderHandler с переопределением метода getCost.
    Поэтому, если у вас уже есть кастомизации или расширение msOrderHandler, необходимо будет добавить в файл core/components/minishop2/custom/order/eslhandler.class.php ваши методы. Если кастомизаций нет, ничего делать не нужно.
  2. Вверху страницы корзины (например, внутри head) разместить сниппет {'eShopLogisticInit' | snippet}
  3. Скопировать чанк tpl.eShopLogistic.order, и чтобы ваша вёрстка не была затёрта при обновлении.
    В новом чанке настройте свою вёрстку. Важно оставить все элементы с классами и идентификаторами, начинающимися на esl-.
  4. Запустить сниппет msOrder с параметром tpl, равным вашему чанку:
    {'!msOrder' | snippet : ['tpl' => 'eShopLogistic.order']}

Если на вашем сайте работает какая-либо система определения местополождения, то для автоматического включения населённого пункта в расчёт доставки можно добавить в запуск сниппета eShopLogisticOrder параметры (на выбор): fias (ФИАС-код населённого пункта) или city (название населённого пункта).
Например: {set $services = '!eShopLogisticOrder' | snippet : ['fias' => $fias]}.
Если fias/city не указаны, то населённый пункт будет определён сервисом eShopLogistic автоматически по IP посетителя.

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

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

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;

}

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

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

Время доставки и выбранный ПВЗ

До версии 0.1.4 время доставки не сохранялось, выбранный пункт выдачи заказа (ПВЗ) добавлялся в комментарий к заказу.

В версии 0.1.4 добавлено сохранение времени доставки и выбранного ПВЗ в поле properties объекта msOrder.
Доступ к полю через fenom (например для вывода в письмах): $order.properties.esl.time , $order.properties.esl.pvz .

Лексикон

В словарях для параметров, содержащих eshoplogistic_frontend_ можно указать нужное вам значение, вместо штатного.

Для параметров, содержащих eshoplogistic_frontend_service_ можно использовать placeholder «services».
Например: Курьер до адреса [[+service]]


~~~~~~~~~~

Простой запуск виджета

Запуск виджета производится согласно документации.

Для запуска виджета в карточке товара достаточни указать data-атрибуты, например:

<button type="button" data-widget-button class="btn button-default"
    data-article="{$product.id}"
    data-name="{$pagetitle | replace : '"' : ''}"
    data-price="{$price | replace : ' ' : ''}"
    data-unit="шт."
    data-weight="{$product.weight ?: 1}">
        Рассчитать доставку ONLINE
</button>
<div id="eShopLogisticApp" data-key="[KEY]"></div>
<script src="https://api.eshoplogistic.ru/widget/modal/v1/app.js"></script>

Однако, вы можете настроить запуск виджета на странице, где нет товара или даже на странице корзины. Т.к. виджет может принимать вместо data-атрибутов одного товара данные сразу для группы товаров через параметр data-offers, то можно передать в него что угодно, вплоть до состава корзины текущего пользователя.
Для простой реализации подобных задач в составе компонента есть соответствующий сниппет eShopLogisticWidgetModal и чанк tpl.eShopLogistic.widgetModal.

Например, вставим прямо в контент страницы кнопку рассчёта доставки для коризины текущего пользователя: [[!eShopLogisticWidgetModal?product=`61`&offers_mode=`cart-or-product`]]


Сниппет принимает все глобальные параметры виджета (документация) + собственные (см. параметры запуска сниппета) и имеет 3 режима формирования списка товаров (параметр offers_mode):

  • корзина - берутся товары из корзины текущего пользователя;
  • товар - берётся конкретный товар (требуется указать id товара в параметре product);
  • корзина или товар - совмещает указанные выше: берутся товары из корзины текущего пользователя, но если корзина пуста - используется указанный товар.


~~~~~~~~~~

Поддержка

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

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

Что делать, если что-то пошло не так

Если вдруг работа компонента или сервиса eShopLogistic вас перестала устраивать.
Чтобы ваш сайт при этом не постардал, я рекомендую делать так:

  • Обязательно настраивайте работу страницы заказа сначала без модуля в отдельном шаблоне или чанке;
  • Уже потом настраивайте работу корзины с использованием компонента в отдельном чанке/шаблоне.

Смысл в том, чтобы если нужно - просто переключить шаблон страницы оформления заказа и процесс оформления заказа пойдёт по ветке без компонента.

Чтобы «отфильтровать» способы доставки ваши от способов доставки, которые установит компонент, можно использовать проверку на наличие класса eslHandler:

{foreach $deliveries as $delivery}
    {if $delivery.class == 'eslHandler'} {continue} {/if}
    //some code
{foreach}

В таком случае даже выключать не нужные способы доставки экстренно не потребуется.

Changelog

0.1.0-beta
Добавлен чанк и сниппет запуска виджета

0.0.13-beta
Добавлен тип оплаты "Предоплата"

0.0.12-beta
Длина описания ПВЗ ограничена 500 символами

0.0.11-beta
Мелкие исправления

0.0.10-beta
Добавлена ТК Байкал Сервис
Мелкие изменения в js и eslOrderHandler (добьавлен параметр deliveryTime)

0.0.9-beta
Добавлена ТК GTD

0.0.8-beta
Исправлена ошибка в конфиге способа доставки "Своя служба" при установке компонента

0.0.7-beta
Изменён js - модальное окно отвязано от bootstrap

0.0.6-beta
Убрана подстановка дефолтного веса, если не указан на товар.
Настраивать дефолтные габариты и вес нужно в личном кабинете eshoplogistic.ru

0.0.5-beta
Исправлен файл eshoplogistic.min.js

0.0.4-beta
Исправлена ошибка с расчётом веса для нескольких товаров

0.0.3-beta
Исправлены мелкие ошибки

0.0.2-beta
Добавлена служба доставки DPD

0.0.1-beta
==============