--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.ru/support/delivery-profile/ru/modules/widgets.md - href: ru/modules/widgets.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support/delivery-profile/ru/llms.txt # Виджет ПВЗ Виджет с пунктами выдачи заказов позволяет пользователям вашего сайта: * выбрать на карте пункты с нужным способом оплаты; * воспользоваться поиском пункта выдачи по адресу. {% note info %} Виджет ПВЗ поддерживает только доставку по России. {% endnote %} ## Какую информацию отправляет виджет {#info} Виджет вызывает callback-функцию в момент использования. В зависимости от настроек пользователь видит пункты выдачи заказов (ПВЗ), постаматы и их характеристики в заданном радиусе. Сallback-функция передает на ваш сайт следующие параметры: - `address.street+house` — адрес; - `type` — тип доставки; - `payment_methods` — способы оплаты; - `id` — идентификатор; - `position` — точку на карте. ## Установка виджета на сайт {#install} Для подключения виджета выполните следующие действия: 1. Скопируйте загрузочный код (см. ниже). 2. Настройте необходимые параметры. Подробнее в разделе [Настройка виджета](#widget-setup). 3. Добавьте настроенный код на нужную страницу. Рекомендуем расположить его внутри тега ` … `. #### Загрузочный код {#widget-install-code} ```javascript
``` ## Виджет ПВЗ v2 {#widget-v2} Доступна новая версия виджета ПВЗ. Для перехода на новую версию измените ссылку на подключение скрипта: ```javascript // Старая версия // Новая версия ``` ### Функциональности в новом виджете {#functionality-new-widget} #### Скрытие стоимости доставки {#hide-delivery-price} В новом виджете можно скрыть стоимость доставки. Для этого закомментируйте один из параметров: - `source_platform_station` - `physical_dims_weight_gross` - `delivery_term` - `delivery_price` #### Фильтрация ПВЗ по операторам {#operator-filter} Новый фильтр в `filter`: ```javascript operator_ids: [ "market_l4g", // ПВЗ Яндекса "5post" // ПВЗ 5post ], ``` Параметр `is_yandex_branded` заменен на `operator_ids`: - `is_yandex_branded = true` соответствует `operator_ids = market_l4g`; - `is_yandex_branded = false` соответствует `operator_ids = null`. #### Измененные способы оплаты {#payment-methods-changes} В новом виджете изменился набор доступных способов оплаты в `filter`: ```javascript payment_methods: [ "postpay", // Оплата по ссылке "already_paid" // Картой онлайн ] ``` #### Скрытие кнопки выбора ПВЗ {#hide-select-button} В новой версии для скрытия кнопки выбора ПВЗ используйте параметр: ```javascript show_select_button: true, // true — показывать кнопку выбора ПВЗ, false — скрыть кнопку ``` ## Настройка виджета {#widget-setup} Для настройки доступны следующие параметры: #| || **Параметр** | **Описание** || || `city` | Город, который будет показан на карте при загрузке. По умолчанию карта настроена на г. Москва. Если вы или ваш пользователь разрешаете определение геолокации, карта покажет город местонахождения. {% note info %} Задайте значение города на русском языке. Для одноименных городов или большей детализации укажите область. Чтобы избежать ошибок, скопируйте название города из [Яндекс Карт](https://yandex.ru/maps/). {% endnote %} || || `type` | Фильтрация по типу способа доставки: - `pickup_point` — пункт выдачи заказов; - `terminal` — постамат. Чтобы на карте были показаны пункты выдачи заказов и постаматы, выберите оба значения. || || `is_yandex_branded`| Необязательный параметр. Фильтрация по типу пунктов выдачи заказов: - `true` — брендированные; - `false` — небрендировананые (партнерские). Чтобы на карте были показаны оба типа, оставьте параметр пустым. || || `payment_methods` | Необязательный параметр. Фильтрация пунктов выдачи заказа по доступным способам оплаты: - `already_paid` — доставка предоплаченных заказов; - `cash_on_receipt` — оплата наличными при получении; - `card_on_receipt` — оплата картой при получении. Одновременно можно выбрать несколько значений. || || `payment_methods_filter` | Необязательный параметр. Выбор оператора при фильтрации ПВЗ по способам оплаты: - `or` — при выборе нескольких типов оплаты будут отображены все ПВЗ, которыми поддерживается хотя бы один из выбранных; - `and` — при выборе нескольких типов оплаты будут отображены все ПВЗ, которыми поддерживаются все выбранные одновременно. Если отсутствует в загрузочном коде, по умолчанию будет применена фильтрация `or` (ИЛИ) для всех возможных способов оплаты. Например, если вы укажите значения `already_paid` и `cash_on_receipt`, на карте будут показаны точки получения заказа, в которых доступен хотя бы один из указанных способов оплаты. || || `show_select_button` | Отображение кнопки выбора ПВЗ: - `false` — скрыть кнопку «Продолжить»; - `true` — показывать кнопку «Продолжить». Если настроена активная кнопка, то событие передается в момент нажатия кнопки «Продолжить». Если кнопка неактивна, то событие передается при выборе пункта выдачи. При повторном выборе будет передано новое значение. || || `size` | Размеры виджета на странице: - `height` — высота, задается только в пикселях; - `width` — ширина, может быть задана в пикселях или процентах. || |# Если не используется расчет стоимости и сроков доставки, можно также задать значения для следующих параметров: #| || **Параметр** | **Описание** || || `delivery_price` | Стоимость доставки для пользователя в рублях. Если цена нефиксированная, укажите значение в формате: «от 100». Чтобы скрыть отображение стоимости, проставьте « ». Обозначение валюты подставляется автоматически. || || `delivery_term` | Срок доставки для пользователя в днях. Рекомендуем указывать в формате: «от 1 дня». || |# ### Фильтрация ПВЗ по доступным услугам {#filter-pvz} Виджет ПВЗ поддерживает фильтрацию пунктов выдачи заказов (ПВЗ) по доступным услугам забора товара. Функциональность доступна начиная с **Виджета ПВЗ v2**. Доступные фильтры: #| || **Параметр** | **Описание** || || `is_fitting_allowed` | Разрешена ли примерка на ПВЗ || || `is_paperless_pickup_allowed` | Разрешена ли сдача без бумаг на ПВЗ || || `is_partial_refuse_allowed` | Разрешён ли частичный выкуп на ПВЗ || || `is_unboxing_allowed` | Разрешено ли вскрытие транспортной упаковки || |# ### Как воспользоваться {#how-to-use} Для использования фильтров передайте узел `pickup_services` внутри узла `filter` при вызове `createWidget` или `setParams`. #### Инициализация через `createWidget` {#createWidget-init} Передайте `pickup_services` внутри `filter` при инициализации виджета. Узел можно использовать вместе со всеми существующими фильтрами, например `type`, `payment_methods` и `payment_methods_filter`. ```javascript YaDelivery.createWidget({ containerId: 'delivery-widget', params: { filter: { type: ["pickup_point", "terminal"], payment_methods: ["already_paid", "card_on_receipt"], payment_methods_filter: "or", pickup_services: { is_fitting_allowed: true, // Фильтр: разрешена ли примерка на ПВЗ is_unboxing_allowed: true // Фильтр: разрешено ли вскрытие транспортной упаковки } } } }); ``` #### Динамическое обновление через `setParams` {#setParams-renew} Чтобы изменить фильтры после инициализации, передайте новый узел `pickup_services` через `YaDelivery.setParams`. ```javascript YaDelivery.setParams({ filter: { pickup_services: { is_fitting_allowed: true, // Фильтр: разрешена ли примерка на ПВЗ is_partial_refuse_allowed: true // Фильтр: разрешен ли частичный выкуп на ПВЗ } } }); ``` **Важно:** при вызове `setParams` узел `pickup_services`, указанный при инициализации, полностью перезаписывается новым значением и не объединяется с предыдущими параметрами. ## Расчет стоимости и сроков доставки {#delivery-cost} Виджет поддерживает расчет стоимости и сроков доставки. Для этого используйте параметры: #| || **Параметр** | **Тип данных** | **Описание** || || `source_platform_station` | GUID | Станция отгрузки. Значение параметра можно: - получить через API с помощью [метода 2.02]( https://yandex.ru/support/delivery-profile/ru/api/other-day/ref/2.-Tochki-samoprivoza-i-PVZ/apib2bplatformpickup-pointslist-post) — выберите ближайшую к вам точку; - запросить у своего коммерческого представителя. || || `physical_dims_weight_gross` | `integer` | Вес отправления, передается в граммах. Максимально допустимый вес отправления: - для большинства ПВЗ — 30 000 г, для некоторых ПВЗ — 10 000 г. Всего 90 штук. - для постамата — 11 000 г. Точки, не подходящие для данного отправления, автоматически скроются при передаче веса отправления. || || `delivery_term` | `integer` | Срок доставки: - `delivery_term: 0,` — означает, что отгрузка будет произведена сегодня; - `delivery_term: 1,` — означает, что отгрузка будет произведена завтра. Отвечает за отображение срока доставки и указывается в днях. Виджет при запросе возможных дат доставки определяет дату границы нижнего интервала по формуле `tommorow + delivery_term`. Используется для того, чтобы заложить необходимое количество дней на отгрузку заказа в сторону логистического оператора. Если параметр не передан, подставляется значение по умолчанию `0`. || || `delivery_price` | `function` | Стоимость доставки: - `delivery_price: (price) => price + " руб"` — цена доставки, полученная от Яндекса; - `delivery_price: (price) => price*0.5 + " руб"` — цена доставки с 50% скидкой. Отвечает за отображение стоимости доставки в рублях. Обозначение валюты необходимо указывать вручную. Также можно проводить математические операции с полученной ценой доставки, например, во время акционных предложений. || |# ## Модификация виджета после запуска {#widget-modify} ### Изменение параметров загрузочного кода в запущенном виджете {#widget-code-modify} Для внесения правок в настройки виджета не обязательно загружать его снова, можно изменить настройки в уже запущенном виджете. Процесс изменения параметров работает следующим образом: 1. На сайт добавляется функция `YaDelivery.setParams`, содержащая изменяемые параметры. 2. Сайт вызывает функцию виджета `YaDelivery.setParams` и передает в нее один или несколько параметров из загрузочного кода, которые необходимо изменить. 3. Список доступных параметров: * Город (`city`) * Типы способа доставки (`type`) * Типы пунктов выдачи заказов (`is_yandex_branded`) * Доступные способы оплаты (`payment_methods`) * Фильтр по способам оплаты (`payment_methods_filter`) * Отображать кнопку выбора ПВЗ(`show_select_button`) * Стоимость доставки (`delivery_price`) * Срок доставки (`delivery_term`) 4. Виджет валидирует передаваемые изменения на допустимость заданных значений. 5. Виджет обновляет переданные параметры и начинает работать так, как будто в загруженном коде были указаны значения с изменениями. {% note warning %} Изменение параметра `size` (размеры виджета) не предусмотрено. {% endnote %} Пример функции `YaDelivery.setParams`: ```javascript YaDelivery.setParams({ city: "Санкт-Петербург", delivery_price: "от 200", show_select_button: false }) ``` - Важно предусмотреть расширяемость данной функции, то есть при добавлении новых параметров загрузочного кода они автоматически будут получать возможность изменения. - Функция принимает параметры в таком же формате, как и при создании виджета. ### Рестарт уже запущенного виджета {#widget-restart} Принцип работы: * Сайт повторно обращается к функции `createWidget`. * Виджет делает рестарт. Существует несколько способов рестарта виджета: * Реализовать повторный перезапуск/исполнение всего загрузочного кода. * Убрать оберточную функцию `function(w)`, тогда функция `createWidget` станет глобальной и ее можно вызывать и таким образом перезапускать виджет. Пример глобальной функции `createWidget`: ```javascript function startWidget() { YaDelivery.createWidget({ containerId: 'delivery-widget', params: { city: "Москва", // Размеры виджета size:{ "height": "450px", "width": "100%" }, delivery_price: "от 100", delivery_term: "от 1 дня", show_select_button: true, filter: { // Тип способа доставки type: [ "pickup_point", "terminal" ], is_yandex_branded: false, payment_methods_filter: "or", // Способ оплаты payment_methods: [ "already_paid", "card_on_receipt" ] } }, }); } YaDelivery ? startWidget() : document.addEventListener('YaNddWidgetLoad', startWidget); ``` ## Получение данных из виджета {#widget-data} 1. Чтобы получать данные о точке, которую выбрал пользователь, нужно подписаться на событие `YaNddWidgetPointSelected`. Подписка на событие внесена в загрузочный код. 2. Событие `YaNddWidgetPointSelected` будет отправляться: - `show_select_button = false` — при каждом выборе пользователем точки ПВЗ или постамата в виджете; - `show_select_button = true` — при выборе любым из доступных способов нужного ПВЗ или постамата и только при нажатии на кнопку выбора ПВЗ. Данные, передаваемые с событием: - `id` — id; - `address.country` — cтрана; - `address.locality` — город; - `address.street` — улица; - `address.house` — дом; - `address.full_address` — полный адрес; - `address.comment` — комментарий. Код подписки на событие: ```javascript // Подписка на событие document.addEventListener('YaNddWidgetPointSelected', function (data){ // Обработка выбранных данных // Данные о выбранной точке содержатся в параметре data console.log(data.detail.id); console.log(data.detail.address.full_address); console.log(data.detail.address.country); console.log(data.detail.address.locality); console.log(data.detail.address.street); console.log(data.detail.address.house); console.log(data.detail.address.comment); }); ``` ## Примеры {#widget-examples} ### Со всеми настройками {#example-all-settings} ```javascript
``` ### Без расчета сроков и стоимости доставки {#example-no-estimations} ```javascript ``` ### С расчетом сроков и стоимости доставки {#example-estimations} ```javascript ```