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

# Описание


Компонент предназначен для:

  • интеграции вариантов доставки, настроенных в сервисе eShopLogistic в minishop2 (далее MS2)
  • приёма заказов от виджетов eShopLogistic
  • выгрузки заказов в кабинеты транспортных компаний и печати этикеток
    В настоящий момент: СДЭК, Boxberry, Яндекс.Доставка, 5POST
  • редактировании способа доставки в панели управления (виджет строен в интерфейс редактирования заказа MS2)

Чтобы возможно было произвести правильный расчёт доставки, для товаров вашего магазина должен быть указан вес. В настройках можно указать минимальный вес, который будет использоваться для товаров без веса, но этот вариант подходит, если все товары имеют примерно одинаковый вес.

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

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


# Настройки модуля в корзине


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

  1. Разделы «Основные» и «Оформление заказа в корзине».

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

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

    • Самовывоз
      Подразумевается способ доставки до пункта выдачи заказа любой доступной транспортной компанией
    • Курьер
      Подразумевается способ доставки курьером любой доступной транспортной компанией
  3. Есть 2 варианта настройки:

    • 1. Использовать чанк tpl.eshoplogistic3.cart (в комплекте данного модуля)
      Его функционал и вид идентичен примеру корзины на этом сайте: перейти в корзину.
    • 2. Использовать свой чанк

      В нужное место чанка необходимо добавить 2 элемента:

      • Cниппет {'!eshoplogistic3Order' | snippet}

        Выводит виджет расчёта доставки.

      • блок <div id="eShopLogistic3Info"></div>

        Выводит блок с подробной информацией о выбранном способе доставки
        (см. системную настройку «Чанк для вывода информации в корзине»).

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

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


# Редактирование доставки в панели управления


В любой момент возможно изменить данные доставки прямо в панели управления MODX, в интерфейсе редактирования заказа.

Для этого прейдите на вкладку «Доставка» и кликните на кнопке «Изменить данные доставки» .

Выбор нового варианта доставки осуществляется с помощью модального виджета (пример на странице товара), поэтому сначала его нужно создать в кабинете eShopLogistic аналогично созданию обычного виджета.

Важно соблюсти следующие моменты:

  • Виджет должен быть привязан к томуже ключу, который указан в системной настройке «Ключ API eShopLogistic»
  • Ключ этого виджета необходимо указать в системной настройке «Ключ виджета для редактирования в окне заказа Minishop2»

# Выгрузка заказов в кабинеты транспортных компаний


Для выгрузки заказов в кабинет ТК, заполните разделы системных настроек: «Выгрузка заказов (общие)» и «Выгрузка заказов (СДЭК)» (если выгружаете в СДЭК).

Перейдите на вкладку «Доставка» и кликните на кнопке «Выгрузить в кабинет службы доставки» .

В результате успешной выгрузки будет отображён идентификатор заказа в система ТК. Также он будет сохранён в properties msOrder и доступен как $order.properties.esl.order.id.

В результате успешного запроса на выгрузку заказа, срабатывают системные события eshoplogistic3BeforeUnloadOrder и eshoplogistic3UnloadOrder. Подробнее смотрите в разделе Системные события.


# Вывод информации о доставке в письмах MS2 и других чанках


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

Доступные данные (в зависимости от стадии обработки заказа):

ПеременнаяОписание
$order.properties.esl.settlement

Массив данных населённого пункта (куда доставляем).

Содержит:

  • $order.properties.esl.settlement.name - название населённого пункта
  • $order.properties.esl.settlement.fias - ФИАС-код населённого пункта
  • $order.properties.esl.settlement.name - регион
$order.properties.esl.service

Массив данных выбранной ТК.

Содержит:

  • $order.properties.esl.service.code - код службы доставки
  • $order.properties.esl.service.name - название службы доставки
$order.properties.esl.type Способ доставки: door (курьер) или terminal (самовывоз, т.е. доставка до ПВЗ/постамата)
$order.properties.esl.price

Массив данных по стоимости.

Содержит:

  • $order.properties.esl.price.value - стоимость доставки
  • $order.properties.esl.price.unit - единица измерения стоимости доставки
$order.properties.esl.time

Массив данных по стоимости.

Содержит:

  • $order.properties.esl.time.value - срок доставки
  • $order.properties.esl.time.unit - единица измерения срока доставки
  • $order.properties.esl.time.text - расширенное текстовое представление срока доставки (например, «в воскресенье (26 марта)»
$order.properties.esl.comments

Массив данных с комментариями (если заданы в настройках данной ТК в каюинете eShopLogistic).

Содержит:

  • $order.properties.esl.comments.service - комментарий для данной ТК
  • $order.properties.esl.comments.type - комментарий для данного типа доставки
$order.properties.esl.data.tariff

Массив данных о выбранном тарифе ТК (если передаётся данной ТК).

Содержит:

  • $order.properties.esl.tariff.code - код тарифа
  • $order.properties.esl.tariff.name - наименование тарифа
$order.properties.esl.data.terminal

Если доставка до ПВЗ/постамата.

Содержит полную информацию о выбранном ПВЗ/постамате. Обязательно присутствуют:

  • $order.properties.esl.data.terminal.code - код
  • $order.properties.esl.data.terminal.name - название
  • $order.properties.esl.data.terminal.address - адрес
  • $order.properties.esl.data.terminal.phones - телефоны
  • $order.properties.esl.data.terminal.workTime - время работы
  • $order.properties.esl.data.terminal.lon - долгота
  • $order.properties.esl.data.terminal.lat - широта
  • $order.properties.esl.data.terminal.is_postamat - флаг: является ли данный ПВЗ постаматом
$order.properties.esl.order

Содержит общую информацию о заказе на доставку (если заказ выгружен в ЛК перевозчика):

  • $order.properties.esl.order.id - идентификатор заказа в системе ТК (обязательно присутствует)
  • $order.properties.esl.order.cost - фактическая стоимость доставки (на момент текущего статуса заказа, может отличаться от расчётной)
  • $order.properties.esl.order.tracking - ссылка на отслеживание заказа (может отсутствовать)
  • $order.properties.esl.order.print - ссылка на печать этикеток (может отсутствовать)
$order.properties.esl.order.state

Содержит полную информацию о текущем статусе заказа на доставку (если заказ выгружен в ЛК перевозчика). Обязательно присутствуют:

  • $order.properties.esl.order.state.status.code - код статуса в системе eShopLogistic
  • $order.properties.esl.order.state.status.description - описание статуса в системе eShopLogistic
  • $order.properties.esl.order.state.service_status.code - код статуса в системе ТК
  • $order.properties.esl.order.state.service_status.description - описание статуса в системе ТК

Перед выводом проверяйте наличие данных, например:

{if $order.properties.esl.name?}
    Служба доставки: {$order.properties.esl.name}
{/if}

Для просмотра всех данных по доставке распечатайте массив $order.properties.esl:

{$order.properties.esl | print_r}

# Информация об аккаунте, кэширование, логгирование


Интерфейс модуля позволяет:

  • Видеть актуальную информацию о балансе счёта eShopLogistic, подключённых ТК, размере кэша данных .
    Время жизни кэша определяется системной настройкой «Время жизни кэша».
  • Видеть статистику запросов всего и в разреже API/виджеты .
    Это позволяет контролировать количество запросов (например на предмет: нет ли аномально большого количества запросов от виджетов) и понимать, подходит ли текущий тариф.
  • Видеть лог запросов .
    Полезно для отладки: видно какие именно данные уходят на расчёт доставки; включение лога определяется системными настройками «Сохранять лог запросов» и «Режим записи лога».

# Обновление статусов доставки


Обновить статус доставки выгруженного заказа можно двумя способами:

  • По кнопке в интерфейсе редактирования заказа .
  • Необходимо:

    • Разрешить автоматическое обновление данных выгруженных заказов выставив «Да» для системной настройки eshoplogistic3_update_data
    • Указать статусы заказа, для которых следует обновлять данные; системная настройка eshoplogistic3_update_data_statuses
    • Настроить с нужной периодичностью запуск скрипта {core_path}/componemts/eshoplogistic3/cron/run.php с помощью cron.

При любом варианте запуска в результате успешного выполнения запроса на получение данных, срабатывает системное событие eshoplogistic3OnGetOrderStatus. Подробнее смотрите в разделе Системные события.


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


Примеры и настройка виджетов:


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


Символом «*» помечены обязательные настройки.
НаименованиеОписание
Основные настройки
Ключ API eShopLogistic* Ключ, созданный в кабинете eShopLogistic
URL API eShopLogistic* Указан по умолчанию.
Данную настройку нужно изменить, если изменится URL API eShopLogistic или вы подключаетесь к тестовому серверу eShopLogistic.
Путь к внутреннему контроллеру виджета* Указан по умолчанию.
Все запросы пропускаются через контроллер для ведения логов или отладки. Вместо штатного, можно указать свой.
Если пусто, запросы пойдут напрямую к api eShopLogistic.
Ключ виджета для редактирования в окне заказа Minishop2

Для изменения параметров доставки при редактировании заказа, создайте отдельный виджет и укажите здесь его ключ.

  • Добавьте к нужному API-ключу виджет c типом «По кнопке в сплывающем окне» . Домен сайта указывать без «http / https».
  • Ключ виджета находится на вкладке «Подключение на сайте» настройки виджета .
Сохранять лог запросов к eShopLogistic Используйте для отладки. Файл лога хранится тут: core/componemts/eshoplogistic3/log.txt
Режим записи лога

Доступные варианты:

  • 0 - запись всех запросов
  • 1 - только запросы на расчёт стоимости доставки
  • 2 - запросы на расчёт стоимости, без пунктов самовывоза (их может быть очень много)

Максимальный размер файла лога - 1Mb; при превышении автоматически очищается.

СSS-файл для фронта Указан по умолчанию.
Файл css, который будет подключён в корзине сайта при включении модуля.
В случае необходимости внесения изменений в данный файл, создайте новый файл и укажите его здесь. Иначе при обновлении ваши изменения будут затёрты.
JS-файл для фронта* Указан по умолчанию.
Файл js, который будет подключён в корзине сайта при включении модуля.
В случае необходимости внесения изменений в данный файл, создайте новый файл и укажите его здесь. Иначе при обновлении ваши изменения будут затёрты.
Время жизни кэша, часы Указан по умолчанию - 24 часа.
Срок кэширования ответов сервиса расчёта доставки. Снижает количество запросов и уменьшает время расчёта. Оптимально - 24-48 часов. Слишком большой срок увеличивает требуемое место на диске и снижает точность данных.
Оформление заказа в корзине
Ключ виджета*

Создайте отдельный виджет и укажите здесь его ключ.

  • Добавьте к нужному API-ключу виджет c типом «Специальный для корзины» . Домен сайта указывать без «http / https».
  • Ключ виджета находится на вкладке «Подключение на сайте» настройки виджета .
Чанк для вывода информации в корзине

Чанк, который будет использоваться для вывода подробной информации о выбранном способе доставки.

Если используется стандартный чанк оформления заказа (входит в комплект - tpl.eshoplogistic3.cart), этот блок здесь: .

Способ доставки по-умолчанию Указан по умолчанию - 1 (штатный вариант «Самовыовоз»).
Идентификатор способа доставки MS2, если не получено ни одного результата по другим вариантам
Минимальный вес единицы товара, кг Используется в случае отсутствия веса у товара.
Указывать в кг, например 0.01 (т.е. 100гр).
Учитывать способ оплаты Указан по умолчанию - «Нет».
Укажите «Да», если при расчёте стоимости доставки в корректирующих правилах у вас учитывается способ оплаты.
Методы оплаты MS2, ассоциируемые с типом: «Оплата картой», «Оплата наличными», «Безналичный расчёт», «Предоплата», «Оплата при получении»

В случае, если настройка «Учитывать способ оплаты» = «Да».

Указать идентификаторы методов оплаты MS2, через запятую. Например: 2,3,4

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

Единица измерения веса Указан по умолчанию - «килограммы».
Выберите, в каких единицах измерения указан вес товаров на сайте: килограммы или граммы.
Виджеты на страницах
Секретные коды виджетов*

Указать секретные коды виджетов, которые используются для отправки заказа, через запятую.

Виджеты для карточки товара (типы «По кнопке в сплывающем окне» и «Встраиваемый в страницу») могут отправлять заказы с учётом выбранного пользователем варианта доставки (т.е. «заказ в 1 клик», но уже с доставкой).

Создайте нужные виджеты укажите здесь его секретные коды, это необходимо для регистрации заказов из виджета в MS2.

  • Добавьте к нужному API-ключу виджет c типом «По кнопке в сплывающем окне» или «Встраиваемый в страницу» .
    Домен сайта указывать без «http / https».
  • Секретный код виджета находится на вкладке «Подключение на сайте» настройки виджета .
Префикс номера заказа Указан по умолчанию - «ESL-».
Для того, чтобы выделить заказы, полученные из виджетов, можно указать какой-нибудь префикс.
Сообщение при успешном создании заказа Выводится в виджете в случае успешного создания заказа.
Сообщение при ошибке создания заказа Выводится в виджете в случае ошибки.
Выгрузка заказов (общие)
Разрешить выгрузку заказов

Включить выгрузку заказов в кабинет службы оставки.

На вкладке «Доставка» при редактировании заказа появятся кнопки выгрузки заказа и печати этикеток (если выгрузка заказа доступна для данной службы доставки).

Значение ставки НДС Указан по умолчанию - «10».
Возможные варианты: 0, 10, 20, -1 (без НДС)
Регион, Населённый пункт, Улица, Строение, Помещение Для подстановки в поля выгрузки заказа в случае забора груза от отправителя
Название компании, Имя контактного лица, E-mail контактного лица, Телефон контактного лица Для подстановки в поля выгрузки заказа
Определять места по позициям заказа Указан по умолчанию - «Да».

Места для выгрузки заказа в кабинет службы доставки автоматически будут сфомированы из позиций заказа. Но в любом случае места можно будет настроить при создании выгруки конкреного заказа.

Выгрузка заказов (СДЭК)
Тип заказа Указан по умолчанию - «1».

Варианты: «1» - интернет-магазин, «2» - обычная доставка.

Самопривоз на терминал СДЭКа Если вы сами привозите груз на терминал СДЭКа, укажите «Да».
Это просто настройка по умолчанию для удобства, можно изменить в форме выгрузки заказа.
Код терминала приёма грузов Код терминала СДЭК, в случае доставки своими силами до терминала для дальнейшей отправки покупателю.
Узнайте у своего менеджера в СДЭКе.
Формат печати этикеток Указан по умолчанию - «A6».

Варианты: A4, A5, A6; по умолчанию A4.

Выгрузка заказов (Яндекс Доставка)
Самопривоз на терминал Если вы сами привозите груз на терминал Яндекс Доставка, укажите «Да». Можно изменить в форме выгрузки заказа.
Код терминала приёма грузов Код терминала Яндекс Доставка, в случае доставки своими силами до терминала для дальнейшей отправки покупателю.
Узнайте у своего менеджера.
Выгрузка заказов (Boxberry)
Тип заказа по умолчанию Указан по умолчанию - «0». Можно изменить в форме выгрузки заказа.

Варианты: «0» - Посылка, «2» - Курьер Онлайн, «3» - Посылка Онлайн, «5» - Посылка 1й класс.

Самопривоз на терминал Boxberry Если вы сами привозите груз на терминал СДЭКа, укажите «Да».
Это просто настройка по умолчанию для удобства, можно изменить в форме выгрузки заказа.
Код терминала приёма грузов Это значение указать обязательно, даже если вы не привозите груз на терминал своими силами!
Код терминала Boxberry, в случае доставки своими силами до терминала для дальнейшей отправки покупателю.
Узнайте у своего менеджера.
Тип упаковки по умолчанию Указан по умолчанию - «1». Можно изменить в форме выгрузки заказа.

Варианты: «0» - упаковка магазина, «2» - упаковка Boxberry.


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


СобытиеОписание
eshoplogistic3OnGetOffers Выполняется после подготовки массива товаров перед отправкой запроса на рассчёт стоимости доставки.

Доступны:
$offers — массив отправленных товарных позиций.

Необходимо вернуть:
$new_offers — новый массив товарных позиций.

Пример:

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

Доступны:
$order — объект заказа msOrder;
$query_data — массив данных выгружаемого заказа.

Необходимо вернуть изменённый массив данных.

Пример:

switch ($modx->event->name) {
    case 'eshoplogistic3BeforeUnloadOrder':
        $query_data['sender']['company'] = 'Название компании';
        $modx->event->output(['query_data' => $query_data]);
        break;
}
eshoplogistic3UnloadOrder Выполняется после выгрузки заказа в кабинет транспортной компании.

Доступны:
$query_data — массив данных выгружаемого заказа;
$order — объект заказа msOrder;
$response - массив с данными ответа.

Пример:

switch ($modx->event->name) {
    case 'eshoplogistic3UnloadOrder':
        $modx->log(1, print_r($response, 1));
        // в зависимости от ответа можно что-то делать; например изменить статус заказа, отправить уведомление и т.п.
        break;
}
eshoplogistic3OnGetOrderStatus Выполняется после обновления статуса доставки выгрженного заказа.
Доступны:
$status — массив со старым и новым значениями статуса выгрузки;
$order — объект заказа msOrder;
$response - массив с данными ответа.

Пример:

switch ($modx->event->name) {
    case 'eshoplogistic3OnGetOrderStatus':
        //$modx->log(1, print_r($response, 1));
        // в зависимости от ответа можно что-то делать; например изменить статус заказа:
        if(isset($status['new'])) {
            if($status['new'] == 'taken') {
                $miniShop2 = $this->modx->getService('miniShop2');
                $miniShop2->changeOrderStatus($order->id, 5);
            }
        }
        break;
}

Документация по запросу получения заказа на доставку смотрите в официальной документации .


# Частые вопросы


Частые причины:

  • Не указаны обязательные системные настройки.
  • Не настроены способы доставки MS2.
  • Не указан вес для товаров и при этом не указано значение для настройки «Минимальный вес единицы товара».
    При этом в личном кабинете eShopLogistic для включённых служб не указана опция «Использовать стандартную коробку / стандартный вес» .
  • Не правильно указана единица веса у товаров.
    Например, в настройке «Единица измерения веса» указаны килограммы, а у товаров вес хранится в граммах.
  • Не правильно указаны габариты товаров.
    Единица измерения для габаритов - сантиметры. Если указываются миллиметры, то получится превышение по габаритам.
  • Проверьте состояние баланса в кабинете eShopLogistic.

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

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

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

Проще всего добавить габариты / изменить вес товаров можно с помощью плагина на событие eshoplogistic3OnGetOffers:


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

    case 'eshoplogistic3OnGetOffers':
        foreach($offers as $k => $offer) {

            # Например, в поле weight_packing msProductData у нас хранятся параметры веса упаковки: возьмём её вес вместо штатного поля weight
            if($productData = $modx->getObject('msProductData', $offer['article'])) {
                $offers[$k]['weight'] = (int)$productData->get('weight_packing') ?? 5;
            }

            # Например, в поле dimensions msProductData у нас хранятся габариты товар, формат Д*Ш*В (25*15*10), в сантиметрах
            if($productData = $modx->getObject('msProductData', $offer['article'])) {
                $offers[$k]['dimensions'] = $productData->get('dimensions');
            }
        }
        $modx->event->output(['offers' => $offers]);
        break;

}

Наш модуль ждёт ответа от всех транспортных компаний (ТК), которые вы выбрали. Сервера ТК отвечают с разной скоростью, а также иногда не отвечают совсем. Поэтому модуль должен подождать пока будут получены все данные или выйдет таймаут запроса к не отвечающей ТК.

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

Как снизить время ожидания и риск отказа от заказа? Рекомендации:

  • Ограничить количество ТК в корзине
  • Убрать явно медленные ТК (среднюю скорось ответа серверов по каждой ТК можно можно посмотреть здесь)
  • Чтобы пользователь понимал, что именно он ожидает, используйте осмысленное сообщение лоадера (настройка словаря eshoplogistic3_loading_message

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

Создадим скрипт, который будет слушать и реагировать на события выбора варианта доставки в виджете. В приведённом ниже примере при выборе варианта "Самовывоз" блокируется кнопка отправки заказа и выводится стандартное сообщение браузера, если пункт самовывоза не выбран.


document.addEventListener('DOMContentLoaded', () => {

    const eslWidget = document.getElementById('eShopLogisticWidgetCart'),
        btnOrder = document.querySelector('button[value="order/submit"]')
     
    if(eslWidget && btnOrder) {
        
        eslWidget.addEventListener('eShopLogisticWidgetCart:onSelectedService', (event) => {
        
            //console.log('Событие onSelectedService', event.detail)
            
            if(event.detail.typeDelivery === 'terminal') {
            
                if(typeof event.detail.terminal === 'object') {
                    btnOrder.disabled = false
                }
                else {
                    btnOrder.disabled = true
                    alert('Не забудьте выбрать пункт самовывоза')
                }
            
                
            } else {
                btnOrder.disabled = false
            }
        })
    }
})
                

Для этого нужно внести небольшое дополнение в код процессора core/components/minishop2/processors/mgr/orders/getlist.class.php.

В начало кода метода prepareArray добавьте следующие строки:


if(isset($data['delivery']) && !empty($data['properties'])) {
    if($properties = json_decode($data['properties'],1)) {
        if(is_array($properties)) {
            if(!empty($properties['esl']['service']['name'])) {
                $data['delivery'] = $properties['esl']['service']['name'].', '.$data['delivery']; // добавит название выбранной ТК перед названием способа доставки
            }
        }
    }
}
                

# Поддержка


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

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

# Changelog


0.0.1-beta
13.03.2023

© 2024 Модуль расчёта стоимости доставок для MODX Revolution

Bootstrap