Интеграция

Посмотреть, как работает виджет, можно здесь.

Установка виджета

Для установки виджета необходимо подключить файл по ссылке https://widget.shiptor.ru/embed/widget.js.

Не копируйте и не сохраняйте файл! Это может привести к нарушению работоспособности виджета в дальнейшем.

Сделать это можно в теге body желаемой страницы следующим образом

<script type="text/javascript" src="https://widget.shiptor.ru/embed/widget.js"></script>

По умолчанию виджет в полноэкранном режиме считает доставку в Москву для отправления весом 1 кг, с габаритами 10×10×10 см³, стоимостью 3 000 рублей, с включенным наложенным платежом и объявленной ценностью. Возможно указание своих собственных начальных параметров и режима отображения.

Внешний вид виджета (режим всплывающего окна)

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

Задание контейнера виджета явным образом

Виджет опирается на HTML-контейнер вида 

<div id="shiptor_widget_delivery" class="_shiptor_widget"></div>

Через него передаются все изначальные параметры.

Параметр	Описание	Пример
data-weight	Расчетный вес в кг, указывается числом.	data-weight= "2"  По умолчанию: 1
data-dimensions	Расчетные габариты в см, указываются в виде json-объекта.	data-dimensions= '{"length":25, "width":10, "height":20}' По умолчанию: 10 х 10 х 10 см3
data-price	Расчетная стоимость в рублях, указывается числом.	data-price= "5000" По умолчанию: 3000
data-cod	Флаг учета наложенного платежа. Задается целым числом, где 0 - нет, 1 - да.	data-cod= "0" По умолчанию: 1
data-card	Флаг учета оплаты наложенного платежа картой для ПВЗ. Задается целым числом, где 1 - да, 0 - нет.	data-card="1" По умолчанию: отсутствует
data-declaredCost	Объявленная стоимость для расчета доставки. Не может быть меньше 10. Если параметр data-cod равен 1 или отсутствует, data-declaredCost игнорируется и в качестве объявленной стоимости берется значение из data-price.	data-declaredCost= "1500"
data-mode	Режим отображения. Может быть задан строкой вида: popup, frame или inline. Значение popup соответствует полноэкранному всплывающему окну, frame - небольшому всплывающему окну у границ экрана, inline - блоку, встраиваемому в тело страницы.	data-mode= "frame" По умолчанию: popup
data-pos	Позиционирование относительно краев экрана, если значение data-mode равно frame. В любом другом случае параметр игнорируется. Задается строкой, которая может иметь следующие значения: topleft, bottomleft, topright или bottomright.	data-pos= "bottomleft" По умолчанию: bottomleft
data-pvzPicker	Способ вывода точек ПВЗ по умолчанию: list (список) или map (карта). Задается строкой.	data-pvzPicker= "map" По умолчанию: list
data-kladr	КЛАДР-код местоположения, задается строкой.	data-kladr= "36000001000" По умолчанию: 77000000000 (КЛАДР Москвы)
data-kladrFrom	КЛАДР-код отправного населенного пункта для сквозной доставки, задается строкой.	data-kladrFrom= "66000001000" По умолчанию: отсутствует
data-country	Название страны, соответствующей населенному пункту с КЛАДР-кодом, заданным в data-kladr. Если он не задан, data-country игнорируется. Обязательно указывайте страну, если населенный пункт по умолчанию находится не в России. Это необходимо для того, чтобы все расчеты выполнялись верно.	data-country= "Беларусь"
data-city	Название населенного пункта, соответствующего кладр коду из параметра data-kladr. Если он не задан, data-city игнорируется.	data-city= "Воронеж" По умолчанию: Москва
data-detail	Показ детальной информации о стоимости доставки. Задается целым числом, где 0 - нет, 1 - да.	data-detail= "1" По умолчанию: 0
data-courier	Фильтр для отображения информации по конкретному перевозчику (ТК). Возможное значение: shiptor, boxberry, dpd, iml, russian-post, pickpoint, cdek, shiptor-one-day, sberlogistics или sber_courier. Чтобы задать составной фильтр из способов доставки, укажите их через запятую, пользуясь списком ниже: shiptor_today — Shiptor Today shiptor_courier — Shiptor Курьер shiptor_courier_za_mkad — Shiptor Курьер за МКАД shiptor_pvz — Shiptor Самовывоз dpd_auto — DPD Курьер (Авто) dpd_avia — DPD Курьер (Авиа) dpd_pvz — DPD Самовывоз dpd_pvz_c — DPD Самовывоз cdek_courier — СДЭК Курьер cdek_pvz — СДЭК Самовывоз cdek_pvz_e — CDEK ПВЗ Эконом iml_courier — IML Курьер iml_pvz — IML Самовывоз pickpoint — Pickpoint boxberry_courier — BoxBerry Курьер boxberry_pvz — BoxBerry Самовывоз dpd_courier_dd — Сквозной DPD Дверь-Дверь dpd_courier_td — Сквозной DPD ПВЗ-Дверь dpd_pvz_dt — Сквозной DPD Дверь-ПВЗ dpd_pvz_tt — Сквозной DPD ПВЗ-ПВЗ cdek_courier_dd — Сквозной СДЭК Дверь-Дверь cdek_courier_td — Сквозной СДЭК ПВЗ-Дверь cdek_pvz_dt — Сквозной СДЭК Дверь-ПВЗ cdek_pvz_tt — Сквозной СДЭК ПВЗ-ПВЗ sberlogistics_pvz — Сберпосылка sberlogistics_dd — Сберкурьер Дверь-Дверь sberlogistics_td — Сберкурьер ПВЗ-Дверь sberlogistics_pvz_dp — Сберпосылка Дверь-ПВЗ sber_courier — Сберкурьер post — Shiptor Почта russian_post_main — Shiptor Почта russian_post_courier_online — Почта «Курьер онлайн» russian_post_parcel_online — Почта «Посылка онлайн»	data-courier= "dpd"  data-courier= "dpd_auto,post,iml_courier"
data-closeText	Текст кнопки закрытия виджета, задается строкой.	data-closeText= "Сохранить" По умолчанию: Закрыть
data-fixedDeliveryPrice	Фиксированная цена доставки в рублях, задается числом. Позволяет указать единую стоимость доставки для всех точек на карте.	data-fixedDeliveryPrice= "125" По умолчанию: отсутствует
data-markup	Наценка на стоимость доставки в процентах или в абсолютном исчислении. Существует два алгоритма её задания: прямой и составной. Доступны следующие правила: ключ all задает наценку для всех служб доставки. Например, data-markup='{"all": 50}' увеличит стоимость доставки на 50 руб. Такая запись идентична data-markup='50'. ключи courier (доставки курьером), pvz (самовывоз) и post (Почта России) позволяют задавать наценки отдельно для каждого типа служб доставки. Например, если data-markup='{"courier": 50, "pvz": 30, "post": '50%'}', то наценка составит 50 руб для всех курьерских служб, 30 руб для всех служб с самовывозом и 50% для Почты России. При необходимости ключи можно комбинировать. Например, data-markup='{"all": "30%", "post": "50%"}' — наценка для всех служб 30%, а для Почты России 50%.	data-markup= "10%" простое правило data-markup= '{"all": 50, "post": 80}' составное правило
data-round	Округление стоимости доставки, задается строкой. Возможны значения: math (математическое округление), floor (всегда в меньшую сторону) и ceil (всегда в большую сторону). Если задана фиксированная цена доставки, параметр игнорируется.	data-round= "ceil" По умолчанию: отсутствует
data-addDays	Увеличение сроков доставки на заданное число дней, число.	data-addDays= "5" По умолчанию: 0
data-hideClose	Режим отображения кнопки «Закрыть». Задается числом, где 0 - демонстрировать, 1 - скрывать.	data-hideClose= "1" По умолчанию: 0
data-linkYmaps	Подключение Яндекс.Карт в виджете. Если на странице с ним сервис уже подключён, то можно его заблокировать, чтобы избежать ошибок с отображением карты с ПВЗ. Задается числом 0 (не подключать) или 1 (подключать).	data-linkYmaps= "0" По умолчанию: 1
data-yk	API-ключ Яндекс.Карт для подключения поисковой строки по карте. Получить его можно в «Кабинете разработчика»: нажмите «Получить ключ», выберите JavaScript API и HTTP Геокодер.	data-yk = "XXXXX"
data-wk	Виджет ключ для авторизованной работы через сервис Чекаута Shiptor.	data-wk= "ASDFGHJQWEXCVBNM"
data-pk	Публичный ключ API Shiptor для авторизованной работы.	data-pk="XNABHSSAYGASYSDG"
data-basket	Состав корзины, который указывается в виде json-объекта. Для каждой позиции в качестве ключа используется shopArticle, а значение - число шт. в ней.	data-basket= '{"xma2":1, "236":2}'
data-pvz	Выбор ПВЗ с указанным идентификатором уже на старте виджета. При этом должны соблюдаться следующие условия: Выбранный ПВЗ присутствует в списке виджета. В противном случае настройка настройка будет проигнорирована. Вместе с data-pvz указывается идентификатор службы доставки, к которой относится ПВЗ, в формате data-shipping-method="идентификатор".	data-pvz = "идентификатор ПВЗ"
data-shipping-method	Выбор метода доставки с указанным идентификатором уже на старте виджета.	data-shipping-method="идентификатор службы доставки"

Пример заданных параметров в контейнере:

<div id="shiptor_widget_delivery" class="_shiptor_widget" data-weight="2" 
data-mode="frame" data-pos="bottomright"></div>

Здесь: вес – 2 кг, режим отображения – окно у границы экрана, позиция – правый нижний угол.

Отложенная инициализация

По умолчанию виджет начинает рисоваться сразу же при загрузке страницы, а это не всегда удобно. Есть возможность настроить показ виджета по клику на какой-либо элемент. Подойдёт любой, на котором корректно срабатывает событие click.

<a href="#" data-role="shiptor_widget_show">Показать виджет</a>

Задайте у своей ссылки параметр data-role равным shiptor_widget_show и тогда виджет отобразится только после нажатия на эту кнопку.

События

Виджет вызывает 6 специальных событий на каждое характерное действие пользователя. Для каждого из них можно назначать обработчики как на стандартные браузерные события типа click или change. Контейнером, на котором срабатывают эти события, выступает сам контейнер виджета. В качестве аргумента в обработчик события передается объект CustomEvent. Все данные, получаемые виджетом в результате запроса к API Shiptor, возвращаются в поле detail этого объекта.

• onLocationSearch — срабатывает, когда происходит поиск вариантов населенного пункта по введенной пользователем части названия. В поле detail возвращаются варианты подходящих населенных пунктов в виде массива.
• onLocationSelect — срабатывает, когда пользователь выбирает один из предложенных вариантов населенного пункта и происходит расчет доступных способов доставки. В поле detail возвращается объект с двумя полями: city и methods. В поле city – объект местоположения, в поле methods – список доступных способов доставки для заданного населённого пункта.
• onMethodSelect — срабатывает, когда пользователь выбирает конкретный вариант доставки: курьерские службы, службы с ПВЗ или Почта России. В поле detail возвращается список доступных способов.
• onCourierSelect — срабатывает, когда пользователь выбирает один из курьерских вариантов доставки. В поле detail он возвращается со стоимостью и сроком.
• onPvzSelect — срабатывает, когда пользователь выбирает конкретный ПВЗ. В поле detail возвращается информация о нём.
• onWidgetClose — срабатывает, когда пользователь нажимает на кнопку закрытия виджета внизу или на крестик в правом верхнем углу.
• onWidgetSuccess — срабатывает, когда пользователь нажимает на кнопку закрытия виджета внизу.

Пример назначения обработчика события: 

var elemShiptorWidget = document.querySelector("#shiptor_widget_delivery");
elemShiptorWidget.addEventListener ("onLocationSearch", function(ce){ console.log(ce.detail)});

Управление виджетом программно

Для этого существует объект window.ShiptorWidget. В нем содержатся все исходные данные и методы для работы с ними. Чтобы прятать или показывать виджет, используются window.ShiptorWidget.hide() и window.ShiptorWidget.show(). Чтобы уничтожить контейнер виджета полностью — window.ShiptorWidget.destroy().

Чтобы переопределить исходные данные для расчета, нужны методы window.ShiptorWidget.setParams() и window.ShiptorWidget.refresh(). window.ShiptorWidget.setParams() переопределяет исходные данные и требует входного параметра в виде простого объекта с определенным набором полей:

• location — объект с полями kladr_id (КЛАДР-код нужного местоположения) и city (строка с названием населённого пункта, соответствующего kladr_id).
• dimensions — объект с полями length, width и height, содержащими длину, ширину и высоту отправления.
• cod — признак наложенного платежа. Допустимые значения: true или false.
• card — признак оплаты по карте при выборе ПВЗ. Допустимые значения: true или false.
• detail — признак показа детальной информации о стоимости доставки. Допустимые значения: true или false.
• mode — внешний вид виджета. Допустимые значения: popup, inline или frame.
• pos — положение виджета. Значение поля учитывается, если mode имеет значение frame. Допустимые значения: topleft, topright, bottomleft или bottomright.
• courier — ограничение методов доставки конкретной логистической службой. Допустимые значения: shiptor, boxberry, dpd, iml, russian-post, pickpoint, cdek, shiptor-one-day.
• price — число, означающее стоимость отправления в рублях.
• weight — число, означающее вес отправления в кг.
• declaredCost — число, означающее объявленную стоимость отправления в рублях. Если наложенный платёж включен, declaredCost игнорируется.
• closeText — текст на кнопке, закрывающей виджет.
• fixedDeliveryPrice — число, определяющее общую стоимость доставки (руб.) для всех точек самовывоза.
• round — способ округления стоимости доставки. Если здля неё задана фиксированная цена, этот параметр будет игнорироваться. Возможные варианты указаны в описании к параметру data-round.
• markup — наценка в процентах или абсолютном исчислении на стоимость доставки.
• addDays — число в днях, на которое будет увеличены все показываемые сроки доставки.
• hideClose — управление скрытием кнопки «Закрыть» в нижней части окна виджета. Допустимые значения: true (скрывать) или false (демонстрировать).
• pvz — идентификатор ПВЗ. Должен быть задан вместе с shipping_method.
• shipping_method — идентификатор службы доставки.

window.ShiptorWidget.refresh() используется для полной перерисовки виджета с теми параметрами, которые в нем были на момент вызова этого метода. Таким образом, чтобы обновить виджет без перезагрузки страницы, нужно:

window.ShiptorWidget.setParams({location:{kladr_id: "36000001000", city: "Воронеж"}, cod: false});
window.ShiptorWidget.refresh();

Виджет будет перерисован с расчетом доставки в Воронеж без наложенного платежа. Чтобы в строке поиска отображался полный адрес, нужно добавить в инициализацию параметр location.parents, куда передать регион и страну населенного пункта в виде массива:

window.ShiptorWidget.setParams({location:{kladr_id: "36000001000", city: "Воронеж", 
parents: ["Воронежская обл","Россия"]}, cod: false});
window.ShiptorWidget.refresh();