Документация к корзинному виджету
- 1 Назначение виджета.
- 2 Установка на сайт.
- 3 Запуск виджета.
- 4 Порядок учёта габаритов.
- 5 Обработка событий.
- 6 Значения, которые можно получить из виджета.
- 7 Правила отправки заказов в Личный кабинет.
- 8 Заказы с вашими собственными вариантами доставки.
- 9 Расположение настроек виджета.
- 10 Изменение параметров заказа после его создания.
- 11 Передача списка статусов и способов оплаты из CMS.
- 12 Передача в CMS данных об изменениях статусов заказов.
- 13 Встроенный эквайринг.
- 14 Упрощённый режим работы виджета, только выбор способа доставки.
- 15 Использование API-скрипта saferoute-widget-api.php.
Назначение виджета.
Корзинный виджет SafeRoute можно встраивать в любые веб-сайты, написанные на любых PHP-фреймворках и с использованием любых CMS.
Виджет позволяет выбрать оптимальный способ доставки при оформлении заказа, отправляя информацию о доставке в Личный кабинет SafeRoute.
Установка на сайт.
Разместите код внутри тега <head>
:
1
<script src="https://widgets.saferoute.ru/cart/api.js"></script>
Затем разместите код в том месте страницы, где должен располагаться виджет:
1
<div id="saferoute-cart-widget"></div>
Запуск виджета.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Инициализация виджета
const widget = new SafeRouteCartWidget("saferoute-cart-widget", {
apiScript: "/saferoute-widget-api.php",
products: [
{ name: "Плюшевый мишка", count: 1, price: 1250 },
],
});
// Обработчики событий
widget.on("change", (data) => {
// Вызовется при изменении выбранного способа доставки
// или любого другого значения в виджете
});
widget.on("done", (response) => {
// Вызовется при успешном оформлении заказа
// и получении ответа от сервера SafeRoute
});
widget.on("error", (errors) => {
// Вызовется при возникновении ошибок при обработке запроса,
// при передаче в виджет некорректных или неполных данных
});
Конструктор SafeRouteCartWidget()
принимает 2 аргумента:
ID DOM-элемента, внутри которого должен инициализироваться виджет;
Объект с параметрами виджета и данными заказа.
Список параметров и данных, которые можно передавать конструктору.
| string | – | Путь к API-скрипту (скачать API-скрипт). |
| string |
| Язык интерфейса виджета: русский (по умолчанию), английский. |
| boolean | – | По умолчанию виджет загружает данные о доступных доставках, отправляя на сервер сразу несколько запросов, и выводя доставки в списке по мере получения ответов. В некоторых случаях это может затормозить работу виджета. Передайте параметру |
| boolean | – | Если передано |
| number |
| Вывод доставки только определённого типа:
По умолчанию выводится доставка всех доступных типов. |
| array | – | Вывод только определённых компаний доставки. Передаётся в виде массива ID нужных компаний. По умолчанию выводятся все доступные компании без ограничений. |
| boolean | – | Скрывает все варианты доставки и ПВЗ без возможности наложенного платежа. |
| string | – | ФИАС населенного пункта пользователя. Если передан, в виджете сразу будет выбран соответствующий населенный пункт. |
| string | – | КЛАДР населенного пункта пользователя. Если передан, в виджете сразу будет выбран соответствующий населенный пункт. |
| string | – | Название населенного пункта пользователя (например, «Москва», «Казань»). Наименее предпочтительный способ, рекомендуется использовать КЛАДР и ФИАС. |
| number | >= 0 | Общий размер скидки на все товары (в же той валюте, в которой переданы цены товаров). |
| string |
| Валюта, в которой будут выведены цены, и будет происходить оплата при использовании встроенного эквайринга: рубль (по умолчанию), доллар США, евро. Также определяет валюту, в которой передаются |
| number | 1 – 999 | Ширина в см. Дробные значения округляются. Если не задана, берется значение по умолчанию из настроек виджета в Личном кабинете. |
| number | 1 – 999 | Высота в см. Дробные значения округляются. Если не задана, берется значение по умолчанию из настроек виджета в Личном кабинете. |
| number | 1 – 999 | Длина в см. Дробные значения округляются. Если не задана, берется значение по умолчанию из настроек виджета в Личном кабинете. |
| number | >= 0,01 | Вес в кг. Может быть дробным. Если не задан, берется значение по умолчанию из настроек виджета в Личном кабинете. |
| number | >= 0,0001 | Общий объём заказа в м3. Может быть дробным. |
| string | – | Значение для поля «ФИО». |
| string | – | Значение для поля «Мобильный телефон». |
| string | – | Значение для поля «Дополнительный телефон». |
| string | – | Значение для поля «E-mail». |
| string | – | Название компании. |
| string | – | ИНН компании. |
| string | – | Значение для поля «Улица». |
| string | – | Значение для поля «Дом». |
| string | – | Значение для поля «Корпус». |
| string | – | Значение для поля «Квартира/офис». |
| number | 1 – 99 | Количество мест в заказе. Если не задано, берется значение по умолчанию из настроек виджета в Личном кабинете. |
| boolean | – | Считать ли наложенный платеж. Если для выбранного пользователем способа доставки оплата наложенным платежом запрещена, переданное данному параметру значение проигнорируется и будет заменено на |
| array | – | Товары. Обязательный параметр, массив должен содержать хотя бы 1 товар. |
| boolean | – | Использовать виджет только для выбора способа доставки (см. раздел “Упрощённый режим работы виджета“). |
| boolean | – | Используется только совместно с параметром |
| boolean | – | Отключает все настройки виджета (в том числе правила), влияющие на формирование списка вариантов доставки. Список доставок, ПВЗ, сроки и стоимость будут выведены без каких-либо изменений со стороны виджета. |
| array | – | Коды стран, которыми необходимо ограничить выбор доставки в виджете. Передаются в формате ISO 3166-1 alpha-2. Данный параметр лишь ограничивает возможные зоны доставки, с его помощью нельзя добавить зону, доставка в которую запрещена правилами виджета. |
| object | – | Объект, позволяющий переопределить некоторые из настроек виджета в Личном кабинете. |
Формат передачи товаров.
Товары передаются в виде объектов со следующими свойствами:
| string | – | Название товара. |
| string | – | Название товара на английском. Необходимо для международной доставки. |
| string | – | Артикул. |
| number |
| НДС. По умолчанию 0. |
| string | – | Штрих-код. |
| number | >= 0 | Стоимость единицы товара. Обязательный параметр. |
| number | >= 0 | Размер скидки на товар (в той же валюте, в которой передана стоимость товара). |
| number | >= 1 | Количество товаров. Обязательный параметр. |
| number | 1 – 999 | Ширина единицы товара в см. Дробные значения округляются. |
| number | 1 – 999 | Высота единицы товара в см. Дробные значения округляются. |
| number | 1 – 999 | Длина единицы товара в см. Дробные значения округляются. |
| number | >= 0,0001 | Объём товара в м3. Может быть дробным. |
| string | – | Код товара. Необходим для международной доставки. |
| string | – | Бренд. |
| string | ISO 3166-1 alpha-2 | Код страны-производителя. |
Если виджету не был передан ни kladr
, ни fias
, ни regionName
, он попытается определить населенный пункт по IP-адресу пользователя. В случае, если определить населенный пункт не удалось, пользователю будет предложено указать его самостоятельно.
Если какие-либо из обязательных параметров не заданы или значение параметра окажется некорректным, будет вызван обработчик события 'error'
с информацией об ошибках.
Если переданные вес, габариты, стоимость или скидка больше или меньше допустимых значений, значения автоматически будут изменены на максимально или минимально допустимые соответственно, не вызывая ошибку.
Настройки, которые можно переопределить при запуске виджета.
| string | – | Кастомные стили виджета. Передайте пустую строку, чтобы отключить при запуске виджета все стили, прописанные в его настройках в Личном кабинете. |
| boolean | – | Скрытие информации о возможности наложенного платежа. |
| boolean | – | Скрытие сроков доставки. |
| string |
| Дополнительная валюта. |
| boolean | – | Использование встроенного эквайринга. |
| number | – | Время ожидания финализации заказа до отмены транзакции (в минутах). |
| boolean | – | Включить комиссию за эквайринг. |
| number | – | Размер комиссии за эквайринг в процентах. |
| number | – | Курс доллара. |
| number | – | Курс евро. |
| boolean | – | Обязательность поля E-mail. |
| boolean | – | Скрыть блок выбора даты и времени курьерской доставки. |
| array | – | Массив ID дополнительных услуг, с которыми будет создаваться заказ. |
| string | – | Ссылка на политику конфиденциальности. |
| boolean | – | Скрыть шаг подтверждения. |
| boolean | – | Скрыть блок шагов. |
| boolean | – | Сохранение данных виджета после оформления заказа. |
| boolean | – | Разделение поля ФИО на 3 отдельных поля. |
| string |
| Тип кнопки подтверждения на последнем шаге ("Подтвердить" / "Далее"). |
| boolean | – | Добавление варианта "Другой способ оплаты". |
| boolean | – | Показывать только бесплатные варианты. |
| boolean | – | Автоматическое перемещение карты после фильтрации точек. |
| boolean | – | Скрытие логотипа SafeRoute. |
Порядок учёта габаритов.
Наивысший приоритет имеют габариты отдельных товаров. Если габариты товаров не заданы, учитывается объём товаров. Если не задан объём товаров, будут использованы общие габариты и общий объём заказа.
В случае, когда в виджет не передан даже общий объём заказа, берутся значения по умолчанию из настроек виджета в Личном кабинете.
Обработка событий.
Метод widget.on()
навешивает обработчики на следующие события:
| Вызовется сразу после запуска виджета, как только в него будут прогружены все необходимые для работы данные. |
| Вызовется при изменении выбранного способа доставки или любого другого значения в виджете (город, адрес, вариант оплаты и т.д.). |
| Вызывается при переходе от одного шага к другому внутри виджета. |
| Действует только при включённом эквайринге. Вызывается при автоматическом перезапуске виджета, когда время ожидания оформления заказа в CMS истекает. |
| Вызовется при получении ответа от сервера SafeRoute после оформления заказа в виджете.
|
| Вызовется при возникновении ошибок при обработке запроса или при передаче в виджет некорректных или неполных данных. |
| Вызывается в упрощённом режиме работы виджета, когда виджет используется лишь для выбора варианта доставки. Обработчик получает объект со свойствами |
Виджет появится на странице после вызова конструктора SafeRouteCartWidget()
. В объекте с параметрами виджета должен быть передан как минимум 1 параметр: products
хотя бы с одним товаром. При его отсутствии будет вызван обработчик события 'error'
, а сам виджет на странице не отобразится.
Для удаления виджета со страницы используйте метод widget.destruct()
. Этот метод следует вызывать и при перезапуске виджета (например, если вам потребовалось запустить виджет повторно с новыми параметрами).
Значения, которые можно получить из виджета.
Обработчик события 'change'
получает объект со всеми внутренними значениями виджета, которые будут использованы для создания заказа:
Параметр | Описание |
| Название выбранного города или населённого пункта. |
| КЛАДР выбранного населённого пункта (если есть). |
| ФИАС выбранного населённого пункта (если есть). |
| ISO-код страны выбранного населённого пункта. |
| Регион населённого пункта. |
| Тип населённого пункта ( |
| ФИО. |
| Телефон. |
| Доп. телефон. |
| E-mail. |
| Название компании. |
| ИНН компании. |
| Улица. |
| Дом. |
| Корпус. |
| Квартира/офис. |
| Индекс. |
| Комментарий для курьера. |
| Тип выбранной доставки.
|
| ID выбранной компании доставки. |
| Название выбранной компании доставки. |
| Дата доставки в формате YYYY-MM-DD. |
| Количество дней, через которое заказ будет доставлен. |
| Возможна ли оплата наличными. |
| Возможна ли оплата картой на точке самовывоза. |
| Возможна ли оплата наложенным платежом. |
| Стоимость доставки в той валюте, которая передана в виджет (без учёта комиссий за наложенный платёж и эквайринг). |
| Комиссия за наложенный платёж наличными в той валюте, которая передана в виджет (только при выключенном эквайринге). |
| Комиссия за наложенный платёж картой в той валюте, которая передана в виджет (только при выключенном эквайринге). |
| Если присутствует и содержит |
| Является ли почтой выбранный способ доставки. |
| Массив ID услуг, которые поддерживает доставка. |
| ID выбранной точки самовывоза. |
| Адрес выбранной точки самовывоза. |
| Число дней, которые заказ будет храниться в пункте самовывоза. |
| Почтовый индекс ПВЗ. |
| Дата (в формате YYYY-MM-DD) и временной интервал, которые выбрал пользователь для доставки курьером. |
| Выбранный тип оплаты (только при включённом эквайринге).
|
| Комиссия для выбранного способа оплаты (налож. платёж / эквайринг) в той валюте, которая передана в виджет (только при включённом эквайринге). |
| Общая стоимость к оплате (стоимость товаров + доставка + комиссии) в той валюте, которая передана в виджет (только при включённом эквайринге). |
| Полный адрес доставки заказа одной строкой (в случае самовывоза - адрес самовывоза). |
| Общая информация о заказе одной строкой: тип доставки, компания доставки, адрес доставки, дата. |
| Общая информация о заказе с HTML-разметкой для вывода её на странице в отформатированном виде. |
| Способ оплаты (чаще всего, его ID) с оплатой наложенным платежом наличными. Берётся из настройки “Способ оплаты (в чекауте) для оплаты заказа наличными при получении“ (Настройки виджета => Настройки CMS). |
| Способ оплаты (чаще всего, его ID) с оплатой наложенным платежом картой. Берётся из настройки “Способ оплаты (в чекауте) для оплаты заказа картой при получении“ (Настройки виджета => Настройки CMS). |
| Массив ID услуг, включённых в настройках виджета, с которыми будет создаваться заказ. |
| Содержит |
Правила отправки заказов в Личный кабинет.
По умолчанию заказы, переданные виджетом, появляются в Личном кабинете SafeRoute сразу же, как только будет задано значение для nppOption
или paymentMethod
при помощи API /v2/widgets/update-order
(см. ниже).
Однако если при запуске виджету был передан параметр nppOption
, посылать запрос к /v2/widgets/update-order
не потребуется – заказ появится в Личном кабинете моментально после отправки данных через виджет. Признаком передачи в Личный кабинет в этом случае будет являться значение true
параметра confirmed
(см. событие 'done'
).
Также nppOption
задаётся автоматически при включённом в виджете эквайринге и при выборе способа доставки с запрещённым наложенным платежом.
По необходимости вы можете настроить отправку заказов в Личный кабинет лишь после присвоения заказам определенного статуса (Настройки виджета > Раздел «Настройки CMS» > Селект «Статус CMS для передачи заказов в Личный кабинет SafeRoute») или после совершения оплаты клиентом (Настройки виджета > Раздел «Настройки CMS» > «Передать заказ в Личный кабинет при получении статуса предварительной оплаты»).
Заказы, которые ещё не были переданы в Личный кабинет, находятся во временном хранилище на сервере SafeRoute и получают временный уникальный ID. Используя этот ID, можно изменять следующие параметры заказа:
Статус (в случае, если заказ в Личный кабинет передается по определенному статусу);
Флаг оплаты (в случае, если заказ в Личный кабинет передается по факту оплаты);
ID заказа в CMS;
Флаг наложенного платежа;
Способ оплаты.
Если вы не передали в виджет значение nppOption
и виджет не смог определить его автоматически, то для отправки заказа в Личный кабинет вы обязательно должны либо присвоить ему способ оплаты, либо задать значение для флага наложенного платежа.
Пока для заказа не определен один из этих параметров, он не появится в Личном кабинете.
Каждый заказ может находиться во временном хранилище не более месяца. Если в течение месяца заказ так и не будет переведен в Личный кабинет, он будет удален.
Заказы с вашими собственными вариантами доставки.
Заказы, для которых выбирается один из ваших собственных вариантов доставки (создаются в настройках виджета в кабинете), не передаются в систему SafeRoute. Вы должны обрабатывать их самостоятельно.
Признаком такого заказа является наличие флага delivery.isMyDelivery
в объекте с данными, который получает обработчик события 'change'
.
Кроме того, поскольку данные заказы не сохраняются на сервере SafeRoute, параметр id
, получаемый обработчиком события 'done'
, будет содержать null
.
Расположение настроек виджета.
Чтобы открыть настройки виджета, зайдите в Личный кабинет SafeRoute и перейдите в раздел «Настройки» > «Магазины». Откройте тот магазин из списка, для которого требуется настроить виджет. На странице магазина нажмите кнопку «Настройки виджетов».
Изменение параметров заказа после его создания.
POST https://api.saferoute.ru/v2/widgets/update-order
Заголовки запроса, необходимые для авторизации:
Заголовок | Описание |
|
|
|
|
Параметры запроса:
Параметр | Тип | Описание |
| number | string | ID заказа. Обязательный параметр. Важно: пока заказ не был отправлен в Личный кабинет, в этот параметр следует передавать его временный ID, полученный из виджета. Однако после отправки заказа в Личный кабинет доступ по временному ID будет невозможен и в параметр потребуется передавать уже постоянный ID ( |
| string | Статус заказа. |
| boolean | Флаг совершения оплаты. |
| number | string | ID (или номер) заказа в CMS магазина. |
| string | Способ оплаты. Можно передать только до переноса заказа в Личный кабинет. |
| boolean | Считать ли наложенный платеж. Можно передать только до переноса заказа в Личный кабинет. Важно: при включённом в виджете эквайринге задавать вручную этот параметр не требуется. |
Варианты ответа (данные в JSON):
HTTP-статус | Описание |
200 | Запрос прошёл успешно. Параметр |
400 | Ошибка. Параметр
|
401 | Ошибка авторизации. В заголовках запроса передан неправильный токен. |
500 | Ошибка на сервере SafeRoute. Обратитесь в техподдержку. |
Передача списка статусов и способов оплаты из CMS.
Для использования настроек из раздела «Настройки CMS» настроек виджета требуется:
Задать путь к API CMS магазина во вкладке «Основные настройки» в настройках виджета.
Предоставить в CMS магазина API, выводящие списки статусов и способов оплаты.
Например, в вы задали следующий путь к API CMS:https://example.com/saferoute-api/
Система будет ожидать списки по адресам:https://example.com/saferoute-api/statuses.json
https://example.com/saferoute-api/payment-methods.json
Оба API должны возвращать списки в следующем формате:
1
2
3
4
5
{
"status_1": "Статус 1",
"status_2": "Статус 2",
"status_3": "Статус 3"
}
Передача в CMS данных об изменениях статусов заказов.
В случае, если в основных настройках виджета вы указали путь к API (см. выше), при изменении статуса заказа в Личном кабинете SafeRoute будет отправляться POST-запрос на адрес:https://example.com/saferoute-api/order-status-update
В запросе будут переданы POST-параметры:
| ID заказа в Личном кабинете SafeRoute. |
| Статус заказа в SafeRoute. |
| Текстовое название статуса заказа в SafeRoute. |
| Статус заказа в CMS, которому соответствует статус заказа в SafeRoute. |
| Трек-номер заказа. |
| URL для трекинга заказа в службе доставки. |
А также заголовки:
| Токен аккаунта. |
| ID магазина. |
| API-ключ. |
Встроенный эквайринг.
Виджет SafeRoute позволяет не только выбрать доставку, но и оплатить заказ посредством банковской карты или Google Pay. Эквайринг включается через настройки виджета в Личном кабинете. Оплата производится через сервис CloudPayments.
После выбора доставки и оплаты заказа через виджет SafeRoute система будет ожидать подтверждения оформления заказа на сайте интернет-магазина. По умолчанию время ожидания составляет 60 минут (можно изменить в настройках виджета). Если в течение этого времени финализация заказа не подтвердится, деньги вернутся покупателю, заказ в Личном кабинете SafeRoute отменится, а виджет на странице покупателя (если страница открыта) перезапустится (вызвав обработчик события restart
), сбросив доставку и оплату.
Данный механизм необходим для возврата денежных средств в случаях, когда оплата через виджет произведена, но по каким-либо причинам оформление заказа на сайте не было завершено.
Деньги также возвращаются покупателю, если после оплаты виджет SafeRoute был запущен заново до завершения оформления заказа (например, при изменении содержимого корзины или при обновлении страницы браузера).
Для подтверждение оформления заказа на сайте отправьте POST-запрос на адрес:https://api.saferoute.ru/v2/widgets/confirm-order
Заголовки запроса, необходимые для авторизации:
Заголовок | Описание |
|
|
|
|
Параметры запроса:
Параметр | Тип | Описание |
| string | ID сессии чекаута. Обязательный параметр. |
Варианты ответа (данные в JSON):
HTTP-статус | Описание |
200 | Запрос прошёл успешно, заказ подтверждён. |
400 | Ошибка. Параметр
|
401 | Ошибка авторизации. В заголовках запроса передан неправильный токен. |
500 | Ошибка на сервере SafeRoute. Обратитесь в техподдержку. |
Упрощённый режим работы виджета, только выбор способа доставки.
В этом режиме виджет служит только для выбора доставки, заказы в Личном кабинете он не создаёт. CMS сама должна создать/изменить заказ в SafeRoute, используя API.
Без параметра inputAddress
в этом режиме в интерфейсе виджета остаются лишь выбор населённого пункта и блок выбора доставки. С переданной опцией inputAddress: true
виджет также будет запрашивать адрес получателя (только для доставки курьером и Почтой России).
После выбора доставки вызывается событие 'select'
, обработчику которого передаётся объект со свойствами city
, delivery
, deliveryDate
, _meta
(а также contacts.address
и comment
, если был передан параметр inputAddress: true
и была выбрана курьерская доставка или доставка Почтой России).
Использование API-скрипта saferoute-widget-api.php.
Для работы виджета вам необходимо установить на своем сервере наш API-скрипт и прописать путь к этому скрипту в параметре apiScript
виджета.
Скрипт необходим для взаимодействия виджета с сервером SafeRoute и не требует никаких дополнительных настроек, кроме указания в нем вашего токена и ID магазина.
Откройте файл saferoute-widget-api.php
и в строке
1
$widgetApi->setToken('');
вставьте токен, который выводится на странице вашего профиля в Личном кабинете SafeRoute.
А в строке
1
$widgetApi->setShopId('');
вставьте ID магазина со страницы вашего магазина в Личном кабинете SafeRoute.