Корзинный виджет расчета доставки для разработчиков

Виджет предназначен специально для встраивания на страницу оформления заказа.
Используется при интеграции по API. На его основе создаются модули для CMS
Для разработчиков

Этот виджет вы можете встроить в любой сайт, подключить к любой CMS.
Поведение страницы с виджетом можно гибко настроить с через js, а внешний вид - с помощью css под конкретный сайт.

Ниже представлен макет корзины со встроенным виджетом.

Состав корзины

Наименование Цена Количество Сумма
Кроссовки
Вес: 2.5кг
6 400 р 6 400 р
Мягкая игрушка
Вес: 0.5кг
820 р 1 640 р
Набор для путешествий
Вес: 1кг
1 652 р 1 652 р

Вариант доставки

Корзина

Стоимость товаров: 9 692 р.

Выберите вариант доставки

Итого: 9 692р.


Лог событий
Во время работы виджет генерирует события, которые вы можете использовать. Описание событий в документации ниже.

Очистить лог

Настройка и установка виджета расчёта доставки

Порядок подключения:

1. Зарегистрируйтесь в личном кабинете: my.eshoplogistic.ru

2. Создайте ключ доступа и добавьте нужные транспортные компании

3. Для установки виджета воспользуйтесь инструкцией, указанной на вкладке «Установка и принцип работы»

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

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

Параметр Описание
data-key Ключ доступа
data-lazy-load

Установите значение data-lazy-load="true" для того, чтобы вместо автоматического запуска, виджет загружается по событию.

Пример:

<script>
const widget = document.getElementById('eShopLogisticWidgetCart'),
        button = document.getElementById('runWidget')
button.addEventListener('click', event => {
	widget.dispatchEvent(new CustomEvent('eShopLogisticWidgetCart:loadApp'))
})
</script>
data-door-delivery-default

Код службы курьерской доставки по умолчанию

После запуска виджета автоматически будет определён вариант указанной службы (если он доступен)

data-terminal-delivery-default

Код службы доставки до пункта самовывоза по умолчанию

После запуска виджета автоматически будет определён вариант указанной службы (если он доступен)

data-controller

URL контроллера

Если необходимо как-то обрабатывать запросы (например, логгировать), укажите URL своего контроллера.
Контроллер должен принимать запрос от виджета, передавать его на наш сервер через API, получать и возвращать виджету ответ.

Например: data-controller="/assets/delivery/action.php"

Параметры, отмеченные , - обязательны.

Доступно 10 функций обратного вызова для каждого ключевого события или ошибки:

  • onLoadApp - после инициализации виджета;
  • onAllServicesLoaded - получение всех доступных вариантов доставки;
  • onSelectTypeDelivery - выбор типа доставки;
  • onSelectedService - выбор варианта доставки;
  • onInvalidSettlementCode - ошибка определения населённого пункта по его коду;
  • onInvalidName - ошибка определения населённого пункта по его названию;
  • onInvalidServices - нет ни одного варианта доставки в данный населённый пункт;
  • onNotAvailableServices - не получено ни одного варианта доставки;
  • onInvalidPayment - не передан вариант оплаты;
  • onInvalidOffers - не переданы данные товаров.

Пример использования:

<script>
document.addEventListener('DOMContentLoaded', () => {
    const root = document.getElementById('eShopLogisticWidgetCart');

    root.addEventListener('eShopLogisticWidgetCart:onLoadApp', (event) => {
        console.log('Событие onLoadApp', event.detail)
    });

    root.addEventListener('eShopLogisticWidgetCart:onSelectedService', (event) => {
        console.log('Событие onSelectedService', event.detail)
    })

    root.addEventListener('eShopLogisticWidgetCart:onAllServicesLoaded', (event) => {
        console.log('Событие onAllServicesLoaded', event.detail)
    })

    root.addEventListener('eShopLogisticWidgetCart:onSelectTypeDelivery', (event) => {
        console.log('Событие onSelectTypeDelivery', event.detail)
    })

    root.addEventListener('eShopLogisticWidgetCart:onInvalidSettlementCode', () => {
        console.log('Неверный код населенного пункта')
    })

    root.addEventListener('eShopLogisticWidgetCart:onInvalidName', () => {
        console.log('Неверный name города')
    })

    root.addEventListener('eShopLogisticWidgetCart:onInvalidServices', () => {
        console.log('Неверный массив служб')
    })

    root.addEventListener('eShopLogisticWidgetCart:onInvalidPayment', () => {
        console.log('Не передана оплата')
    })

    root.addEventListener('eShopLogisticWidgetCart:onInvalidOffers', () => {
        console.log('Не передан offers')
    })
})

1. Добавьте ключ доступа. Далее к данному ключу можно добавлять любое количество любых виджетов.

Подключение виджета расчёта доставки

2. Выберите нужный тип виджета. После добавления виджета автоматически произойдёт переход к его настройке.

Подключение виджета расчёта доставки

Установка на сайт

Для установки виджета на сайт необходимо вставить в код страницы контейнер для виджета и подключить js-скрипт:

<div id="eShopLogisticWidgetCart" data-lazy-load="false" data-key="000000-0-0"></div>
<script src="https://api.esplc.ru/widgets/cart/app.js"></script>
Параметр data-key должен содержать ключ виджета, указанный в настройках виджета в личном кабинете.

Как использовать виджет на странице оформления заказа

Для включения виджета в работы в состав страницы оформления заказа сайта необходимо передать виджету:

  • Населённый пункт (далее НП) для доставки.

    Определить НП при загрузке страницы оформления заказа:
    если на сайте установлена система определения города посетителя и у вас есть название города, а лучше ФИАС-код, то можно воспользоваться методом /locality/search. В противном случае, можно использовать метод /locality/geo.
    Выбор НП посетителем сайта: используйте метод /locality/search.

  • Состав корзины.

    JSON-представление массива товаров в корзине.

  • Метод оплаты.

    Обратите внимание: необходимо связать варианты оплаты, настроенные на сайте с зарезервированными кодами в нашейм сервисе:
    card (карта)
    cash (наличные)
    cashless (безналичный расчёт)
    prepay (специальный тип: предоплата)
    upon_receipt (специальный тип: оплата при получении).

При обновлении любого из указанных выше параметра необходимо обновлять виджет, перезапуская событие eShopLogisticWidgetCart:updateParamsRequest с новыми данными.

JS-код запуска:

<script>
document.addEventListener('DOMContentLoaded', () => {
    const root = document.getElementById('eShopLogisticWidgetCart'),
    // объект settlement должен содержать массив services, а также один из элементов code или fias
    // данные получаются посредством методов /locality/search или /locality/geo
    settlement = {
        "code": 120935,
        "name": "Тверь",
        "fias": "c52ea942-555e-45c6-9751-58897717b02f",
        "services": [
            "sdek",
            "yandex",
            "boxberry",
            "energija"
        ]
    },
    // массив товаров корзины
    cart = [{
        "article":"001",
        "name":"Товар 1",
        "count":1,
        "price":6400,
        "weight":2.5,
        "dimensions":"15*10*5"
    }, {
        "article":"002",
        "name":"Товар 2",
        "count":2,
        "price":1500,
        "weight":0.5,
        "dimensions":"10*5*5"
    }]

    // собыите onLoadApp запускается только один раз - при первом запуске виджета
    // для того, чтобы передать в виджет новые параметры, используйте только updateParamsRequest
    root.addEventListener('eShopLogisticWidgetCart:onLoadApp', (event) => {
        const params ={
            offers: JSON.stringify(cart),
            payment: 'card'
        }

        root.dispatchEvent(new CustomEvent('eShopLogisticWidgetCart:updateParamsRequest', {
            detail: {
                settlement: settlement,
                from: '', // указанием здесь ФИАС-кода можно изменить город-отправитель, заданный по умолчанию в настройках ключа доступа (в личном кабинете)
                requestParams: params
            }
        }))
    })

})
</script>

В результате работы виджета доступны следующие данные, которые необходимо передать в объект заказа:

  • Выбранная служба доставки, стоимость и срок доставки, комментарий (если указан).

    Используйте функцию обратного вызова eShopLogisticWidgetCart:onSelectedService.
    В event.detail также могут содержаться другие необходимые данные, в зависимости от конкретной службы доставки. Например, «код тарифа» для СДЭКа, который необходим для выгрузки заказа на доставку в кабинет сдека.

  • Метод доставки

    Используйте функцию обратного вызова eShopLogisticWidgetCart:onSelectTypeDelivery.

  • Выбранный пункт самовывоза

    Используйте функцию обратного вызова eShopLogisticWidgetCart:onSelectedPvz.

Пример:

<script>
document.addEventListener('DOMContentLoaded', () => {
    const root = document.getElementById('eShopLogisticWidgetCart')

    // Событие «Выбор варианта доставки»
    root.addEventListener('eShopLogisticWidgetCart:onSelectedService', (event) => {
        console.log('Событие onSelectedService', event.detail)
    })
})
</script>

В случае, если не найдено ни одного варианта доставки, вызывается eShopLogisticWidgetCart:onNotAvailableServices.