Документация к корзинному виджету

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>:

<script src="https://widgets.saferoute.ru/cart/api.js"></script>

Затем разместите код в том месте страницы, где должен располагаться виджет:

<div id="saferoute-cart-widget"></div>

Запуск виджета.

// Инициализация виджета 
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-элемента, внутри которого должен инициализироваться виджет;
Объект с параметрами виджета и данными заказа.

Список параметров и данных, которые можно передавать конструктору.

Параметр	Тип	Допустимые значения	Описание

Параметр	Тип	Допустимые значения	Описание
`apiScript`	string	–	Путь к API-скрипту (скачать API-скрипт). Если не указать, по умолчанию виджет будет обращаться по адресу `"/saferoute-widget-api.php"`.
`lang`	string	`'ru'`, `'en'`	Язык интерфейса виджета: русский (по умолчанию), английский.
`disableMultiRequests`	boolean	–	По умолчанию виджет загружает данные о доступных доставках, отправляя на сервер сразу несколько запросов, и выводя доставки в списке по мере получения ответов. В некоторых случаях это может затормозить работу виджета. Передайте параметру `true`, чтобы данные о доставках загружались единым запросом.
`lockPickupFilters`	boolean	–	Если передано `true`, при достаточной ширине виджета панель фильтров ПВЗ будет открыта всегда, когда не выбрана точка ПВЗ.
`deliveryType`	number	`1`, `2`, `3`	Вывод доставки только определённого типа: `1` – Самовывоз; `2` – Курьерская; `3` – Почта. По умолчанию выводится доставка всех доступных типов.
`deliveryCompanies`	array	–	Вывод только определённых компаний доставки. Передаётся в виде массива ID нужных компаний. По умолчанию выводятся все доступные компании без ограничений.
`hideDeliveriesWithoutCOD`	boolean	–	Скрывает все варианты доставки и ПВЗ без возможности наложенного платежа.
`fias`	string	–	ФИАС населенного пункта пользователя. Если передан, в виджете сразу будет выбран соответствующий населенный пункт.
`kladr`	string	–	КЛАДР населенного пункта пользователя. Если передан, в виджете сразу будет выбран соответствующий населенный пункт.
`regionName`	string	–	Название населенного пункта пользователя (например, «Москва», «Казань»). Наименее предпочтительный способ, рекомендуется использовать КЛАДР и ФИАС.
`discount`	number	>= 0	Общий размер скидки на все товары (в же той валюте, в которой переданы цены товаров).
`currency`	string	`'rub'`, `'usd'`, `'euro'`	Валюта, в которой будут выведены цены, и будет происходить оплата при использовании встроенного эквайринга: рубль (по умолчанию), доллар США, евро. Также определяет валюту, в которой передаются `discount`, `products.price`, `products.discount`.
`width`	number	1 – 999	Ширина в см. Дробные значения округляются. Если не задана, берется значение по умолчанию из настроек виджета в Личном кабинете.
`height`	number	1 – 999	Высота в см. Дробные значения округляются. Если не задана, берется значение по умолчанию из настроек виджета в Личном кабинете.
`length`	number	1 – 999	Длина в см. Дробные значения округляются. Если не задана, берется значение по умолчанию из настроек виджета в Личном кабинете.
`weight`	number	>= 0,01	Вес в кг. Может быть дробным. Если не задан, берется значение по умолчанию из настроек виджета в Личном кабинете.
`volume`	number	>= 0,0001	Общий объём заказа в м³. Может быть дробным.
`userFullName`	string	–	Значение для поля «ФИО».
`userPhone`	string	–	Значение для поля «Мобильный телефон».
`userAdditPhone`	string	–	Значение для поля «Дополнительный телефон».
`userEmail`	string	–	Значение для поля «E-mail».
`userCompanyName`	string	–	Название компании.
`userCompanyTIN`	string	–	ИНН компании.
`userAddressStreet`	string	–	Значение для поля «Улица».
`userAddressBuilding`	string	–	Значение для поля «Дом».
`userAddressBulk`	string	–	Значение для поля «Корпус».
`userAddressApartment`	string	–	Значение для поля «Квартира/офис».
`itemCount`	number	1 – 99	Количество мест в заказе. Если не задано, берется значение по умолчанию из настроек виджета в Личном кабинете.
`nppOption`	boolean	–	Считать ли наложенный платеж. Если для выбранного пользователем способа доставки оплата наложенным платежом запрещена, переданное данному параметру значение проигнорируется и будет заменено на `false`.
`products`	array	–	Товары. Обязательный параметр, массив должен содержать хотя бы 1 товар.
`onlyDeliverySelect`	boolean	–	Использовать виджет только для выбора способа доставки (см. раздел “Упрощённый режим работы виджета“).
`inputAddress`	boolean	–	Используется только совместно с параметром `onlyDeliverySelect`. Добавляет в упрощённый режим работы виджета ввод адреса для курьерской доставки и доставки Почтой России.
`disableWidgetDeliverySettings`	boolean	–	Отключает все настройки виджета (в том числе правила), влияющие на формирование списка вариантов доставки. Список доставок, ПВЗ, сроки и стоимость будут выведены без каких-либо изменений со стороны виджета.
`onlyCountries`	array	–	Коды стран, которыми необходимо ограничить выбор доставки в виджете. Передаются в формате ISO 3166-1 alpha-2. Данный параметр лишь ограничивает возможные зоны доставки, с его помощью нельзя добавить зону, доставка в которую запрещена правилами виджета.
`overrideSettings`	object	–	Объект, позволяющий переопределить некоторые из настроек виджета в Личном кабинете. Описание возможных параметров.

Формат передачи товаров.

Товары передаются в виде объектов со следующими свойствами:

Параметр	Тип	Допустимые значения	Описание

Параметр	Тип	Допустимые значения	Описание
`name`	string	–	Название товара.
`nameEn`	string	–	Название товара на английском. Необходимо для международной доставки.
`vendorCode`	string	–	Артикул.
`vat`	number	`0`, `10`, `20`	НДС. По умолчанию 0.
`barcode`	string	–	Штрих-код.
`price`	number	>= 0	Стоимость единицы товара. Обязательный параметр.
`discount`	number	>= 0	Размер скидки на товар (в той же валюте, в которой передана стоимость товара).
`count`	number	>= 1	Количество товаров. Обязательный параметр.
`width`	number	1 – 999	Ширина единицы товара в см. Дробные значения округляются.
`height`	number	1 – 999	Высота единицы товара в см. Дробные значения округляются.
`length`	number	1 – 999	Длина единицы товара в см. Дробные значения округляются.
`volume`	number	>= 0,0001	Объём товара в м³. Может быть дробным.
`tnved`	string	–	Код товара. Необходим для международной доставки.
`brand`	string	–	Бренд.
`producingCountry`	string	ISO 3166-1 alpha-2	Код страны-производителя.

Если виджету не был передан ни kladr, ни fias, ни regionName, он попытается определить населенный пункт по IP-адресу пользователя. В случае, если определить населенный пункт не удалось, пользователю будет предложено указать его самостоятельно.

Если какие-либо из обязательных параметров не заданы или значение параметра окажется некорректным, будет вызван обработчик события 'error' с информацией об ошибках.

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

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

Параметр	Тип	Допустимые значения	Описание переопределяемой настройки

Параметр	Тип	Допустимые значения	Описание переопределяемой настройки
`styles`	string	–	Кастомные стили виджета. Передайте пустую строку, чтобы отключить при запуске виджета все стили, прописанные в его настройках в Личном кабинете.
`hideCODInfo`	boolean	–	Скрытие информации о возможности наложенного платежа.
`hideDeliveryDate`	boolean	–	Скрытие сроков доставки.
`alternativeCurrency`	string	`'usd'`, `'euro'`, `'rub'`	Дополнительная валюта.
`enableAcquiring`	boolean	–	Использование встроенного эквайринга.
`acquiringTimeout`	number	–	Время ожидания финализации заказа до отмены транзакции (в минутах).
`enableAcquiringCommission`	boolean	–	Включить комиссию за эквайринг.
`acquiringCommissionValue`	number	–	Размер комиссии за эквайринг в процентах.
`usdExchangeRate`	number	–	Курс доллара.
`euroExchangeRate`	number	–	Курс евро.
`emailRequired`	boolean	–	Обязательность поля E-mail.
`hideCourierTimeSelect`	boolean	–	Скрыть блок выбора даты и времени курьерской доставки.
`enabledServices`	array	–	Массив ID дополнительных услуг, с которыми будет создаваться заказ.
`privacyPolicyLink`	string	–	Ссылка на политику конфиденциальности.
`hideConfirmationStep`	boolean	–	Скрыть шаг подтверждения.
`hideSteps`	boolean	–	Скрыть блок шагов.
`storeWidgetData`	boolean	–	Сохранение данных виджета после оформления заказа.
`splitFullnameInput`	boolean	–	Разделение поля ФИО на 3 отдельных поля.
`doneBtnType`	string	`'confirm'`, `'next'`	Тип кнопки подтверждения на последнем шаге ("Подтвердить" / "Далее").
`addOtherPayMethodVariant`	boolean	–	Добавление варианта "Другой способ оплаты".
`displayOnlyFree`	boolean	–	Показывать только бесплатные варианты.
`moveMapAfterFiltration`	boolean	–	Автоматическое перемещение карты после фильтрации точек.
`hideSRLogo`	boolean	–	Скрытие логотипа SafeRoute.

Порядок учёта габаритов.

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

Обработка событий.

Метод widget.on() навешивает обработчики на следующие события:

Имя события	Описание

Имя события	Описание
`start`	Вызовется сразу после запуска виджета, как только в него будут прогружены все необходимые для работы данные.
`change`	Вызовется при изменении выбранного способа доставки или любого другого значения в виджете (город, адрес, вариант оплаты и т.д.). Обработчик получит объект со всеми текущими значениями виджета.
`stepChange`	Вызывается при переходе от одного шага к другому внутри виджета. Обработчик получает строку с идентификатором шага.
`restart`	Действует только при включённом эквайринге. Вызывается при автоматическом перезапуске виджета, когда время ожидания оформления заказа в CMS истекает.
`done`	Вызовется при получении ответа от сервера SafeRoute после оформления заказа в виджете. Обработчик получит объект со свойствами: `id` – ID созданного заказа на сервере SafeRoute. Это может быть как финальный ID заказа в Личном кабинете SafeRoute, так и временный ID (в случае, если заказ ещё не был отправлен в Личный кабинет). Данный ID может использоваться для редактирования некоторых параметров заказа уже после его создания, а также для обновления статуса заказа и установки флага оплаты. `confirmed` – флаг, принимающий значение `true`, если заказ был сразу отправлен в Личный кабинет. `checkoutSessId` – ID сессии чекаута, присутствует только при оплате через встроенный эквайринг.
`error`	Вызовется при возникновении ошибок при обработке запроса или при передаче в виджет некорректных или неполных данных. Обработчик получит массив с текстовым описанием ошибок.
`select`	Вызывается в упрощённом режиме работы виджета, когда виджет используется лишь для выбора варианта доставки. Обработчик получает объект со свойствами `city`, `delivery` и `deliveryDate`.

Виджет появится на странице после вызова конструктора SafeRouteCartWidget(). В объекте с параметрами виджета должен быть передан как минимум 1 параметр: products хотя бы с одним товаром. При его отсутствии будет вызван обработчик события 'error', а сам виджет на странице не отобразится.

Для удаления виджета со страницы используйте метод widget.destruct(). Этот метод следует вызывать и при перезапуске виджета (например, если вам потребовалось запустить виджет повторно с новыми параметрами).

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

Обработчик события 'change' получает объект со всеми внутренними значениями виджета, которые будут использованы для создания заказа:

Параметр	Описание
`city.name`	Название выбранного города или населённого пункта.
`city.kladr`	КЛАДР выбранного населённого пункта (если есть).
`city.fias`	ФИАС выбранного населённого пункта (если есть).
`city.countryIsoCode`	ISO-код страны выбранного населённого пункта.
`city.region`	Регион населённого пункта.
`city.type`	Тип населённого пункта (`'г'`, `'д'`, `'пос'` и т.п.).
`contacts.fullName`	ФИО.
`contacts.phone`	Телефон.
`contacts.additPhone`	Доп. телефон.
`contacts.email`	E-mail.
`contacts.companyName`	Название компании.
`contacts.companyTIN`	ИНН компании.
`contacts.address.street`	Улица.
`contacts.address.building`	Дом.
`contacts.address.bulk`	Корпус.
`contacts.address.apartment`	Квартира/офис.
`contacts.address.zipCode`	Индекс.
`comment`	Комментарий для курьера.
`delivery.type`	Тип выбранной доставки. `1` - самовывоз из пункта выдачи; `2` - курьерская; `3` - почта.
`delivery.deliveryCompanyId`	ID выбранной компании доставки.
`delivery.deliveryCompanyName`	Название выбранной компании доставки.
`delivery.deliveryDate` `delivery.maxDeliveryDate`	Дата доставки в формате YYYY-MM-DD.
`delivery.deliveryDays` `delivery.maxDeliveryDays`	Количество дней, через которое заказ будет доставлен.
`delivery.cashPaymentAvailable` `delivery.point.cashPaymentAvailable`	Возможна ли оплата наличными.
`delivery.point.cardPaymentAvailable`	Возможна ли оплата картой на точке самовывоза.
`delivery.CODAvailable`	Возможна ли оплата наложенным платежом.
`delivery.totalPrice`	Стоимость доставки в той валюте, которая передана в виджет (без учёта комиссий за наложенный платёж и эквайринг).
`delivery.priceCommissionCod`	Комиссия за наложенный платёж наличными в той валюте, которая передана в виджет (только при выключенном эквайринге).
`delivery.priceCommissionCodCard`	Комиссия за наложенный платёж картой в той валюте, которая передана в виджет (только при выключенном эквайринге).
`delivery.isMyDelivery`	Если присутствует и содержит `true`, выбран «собственный» вариант доставки.
`delivery.isPost`	Является ли почтой выбранный способ доставки.
`delivery.services`	Массив ID услуг, которые поддерживает доставка.
`delivery.point.id`	ID выбранной точки самовывоза.
`delivery.point.address`	Адрес выбранной точки самовывоза.
`delivery.point.deliveryHoldDays`	Число дней, которые заказ будет храниться в пункте самовывоза.
`delivery.point.zipCode`	Почтовый индекс ПВЗ.
`deliveryDate.date` `deliveryDate.time.timeFrom` `deliveryDate.time.timeTo` `deliveryDate.time.id`	Дата (в формате YYYY-MM-DD) и временной интервал, которые выбрал пользователь для доставки курьером.
`payType`	Выбранный тип оплаты (только при включённом эквайринге). `1` – оплата при получении; `2` – оплата он-лайн через виджет; `3` – оплата другим способом оплаты (только при включённой в настройках опции “Добавить вариант «Другой способ оплаты»“).
`payTypeCommission`	Комиссия для выбранного способа оплаты (налож. платёж / эквайринг) в той валюте, которая передана в виджет (только при включённом эквайринге).
`totalOrderPrice`	Общая стоимость к оплате (стоимость товаров + доставка + комиссии) в той валюте, которая передана в виджет (только при включённом эквайринге).
`_meta.fullDeliveryAddress`	Полный адрес доставки заказа одной строкой (в случае самовывоза - адрес самовывоза).
`_meta.commonDeliveryData`	Общая информация о заказе одной строкой: тип доставки, компания доставки, адрес доставки, дата.
`_meta.commonDeliveryDataHTML`	Общая информация о заказе с HTML-разметкой для вывода её на странице в отформатированном виде.
`_meta.widgetSettings.payMethodWithCOD`	Способ оплаты (чаще всего, его ID) с оплатой наложенным платежом наличными. Берётся из настройки “Способ оплаты (в чекауте) для оплаты заказа наличными при получении“ (Настройки виджета => Настройки CMS).
`_meta.widgetSettings.cardPayMethodWithCOD`	Способ оплаты (чаще всего, его ID) с оплатой наложенным платежом картой. Берётся из настройки “Способ оплаты (в чекауте) для оплаты заказа картой при получении“ (Настройки виджета => Настройки CMS).
`_meta.widgetSettings.enabledServices`	Массив ID услуг, включённых в настройках виджета, с которыми будет создаваться заказ.
`_meta.widgetSettings.addServicesAlways`	Содержит `true`, если в настройках виджета в блоке выбора услуг отмечено “Всегда создавать с этими услугами“.

Правила отправки заказов в Личный кабинет.

По умолчанию заказы, переданные виджетом, появляются в Личном кабинете 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

Заголовки запроса, необходимые для авторизации:

Заголовок	Описание
`Authorization:Bearer {TOKEN}`	`{TOKEN}` – токен, который выводится на странице вашего профиля в Личном кабинете SafeRoute.
`shop-id:{SHOP_ID}`	`{SHOP_ID}` – ID магазина со страницы вашего магазина в Личном кабинете SafeRoute.

Параметры запроса:

Параметр	Тип	Описание
`id`	number \| string	ID заказа. Обязательный параметр. Отдается виджетом после создания заказа, либо данным API (параметр `cabinetId`), если после запроса заказ был отправлен в Личный кабинет и его ID сменился с временного на постоянный. Важно: пока заказ не был отправлен в Личный кабинет, в этот параметр следует передавать его временный ID, полученный из виджета. Однако после отправки заказа в Личный кабинет доступ по временному ID будет невозможен и в параметр потребуется передавать уже постоянный ID (`cabinetId`).
`status`	string	Статус заказа.
`payment`	boolean	Флаг совершения оплаты.
`cmsId`	number \| string	ID (или номер) заказа в CMS магазина.
`paymentMethod`	string	Способ оплаты. Можно передать только до переноса заказа в Личный кабинет.
`nppOption`	boolean	Считать ли наложенный платеж. Можно передать только до переноса заказа в Личный кабинет. Важно: при включённом в виджете эквайринге задавать вручную этот параметр не требуется.

Варианты ответа (данные в JSON):

HTTP-статус	Описание
200	Запрос прошёл успешно. Параметр `cabinetId` содержит ID заказа в Личном кабинете SafeRoute. Значение появится сразу после передачи заказа в Личный кабинет. Если заказ ещё не был отправлен в Личный кабинет, `cabinetId` будет содержать `null`.
400	Ошибка. Параметр `code` содержит код ошибки: `0` – не передан ID заказа; `1001` – заказ с переданным ID не найден; `2001` – передан неправильный ID магазина; `1002` – ошибка при создании заказа в Личном кабинете (детали ошибки находятся в параметре `message`), обратитесь в техподдержку; `1003` – ошибка при обновлении заказа в Личном кабинете, обратитесь в техподдержку.
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 должны возвращать списки в следующем формате:

{
  "status_1": "Статус 1",
  "status_2": "Статус 2",
  "status_3": "Статус 3"
}

Передача в CMS данных об изменениях статусов заказов.

В случае, если в основных настройках виджета вы указали путь к API (см. выше), при изменении статуса заказа в Личном кабинете SafeRoute будет отправляться POST-запрос на адрес:
https://example.com/saferoute-api/order-status-update

В запросе будут переданы POST-параметры:

Параметр	Описание

Параметр	Описание
`id`	ID заказа в Личном кабинете SafeRoute.
`statusSR`	Статус заказа в SafeRoute.
`statusSRName`	Текстовое название статуса заказа в SafeRoute.
`statusCMS`	Статус заказа в CMS, которому соответствует статус заказа в SafeRoute.
`trackNumber`	Трек-номер заказа.
`trackUrl`	URL для трекинга заказа в службе доставки.

А также заголовки:

Заголовок	Описание

Заголовок	Описание
`Token`	Токен аккаунта.
`Shop-Id`	ID магазина.
`Api-Key`	API-ключ.

Встроенный эквайринг.

Виджет SafeRoute позволяет не только выбрать доставку, но и оплатить заказ посредством банковской карты или Google Pay. Эквайринг включается через настройки виджета в Личном кабинете. Оплата производится через сервис CloudPayments.

После выбора доставки и оплаты заказа через виджет SafeRoute система будет ожидать подтверждения оформления заказа на сайте интернет-магазина. По умолчанию время ожидания составляет 60 минут (можно изменить в настройках виджета). Если в течение этого времени финализация заказа не подтвердится, деньги вернутся покупателю, заказ в Личном кабинете SafeRoute отменится, а виджет на странице покупателя (если страница открыта) перезапустится (вызвав обработчик события restart), сбросив доставку и оплату.

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

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

Для подтверждение оформления заказа на сайте отправьте POST-запрос на адрес:
https://api.saferoute.ru/v2/widgets/confirm-order

Заголовки запроса, необходимые для авторизации:

Заголовок	Описание
`Authorization:Bearer {TOKEN}`	`{TOKEN}` – токен, который выводится на странице вашего профиля в Личном кабинете SafeRoute.
`shop-id:{SHOP_ID}`	`{SHOP_ID}` – ID магазина со страницы вашего магазина в Личном кабинете SafeRoute.

Параметры запроса:

Параметр	Тип	Описание
`checkoutSessId`	string	ID сессии чекаута. Обязательный параметр. Отдается виджетом обработчику события `done` после создания заказа, а также хранится в Cookie с именем `SR_checkoutSessId`.

Варианты ответа (данные в JSON):

HTTP-статус	Описание
200	Запрос прошёл успешно, заказ подтверждён.
400	Ошибка. Параметр `code` содержит код ошибки: `2001` – передан неправильный ID магазина; `7001` – ошибка подтверждения транзакции в платёжной системе; `7003` – неправильный ID сессии (ID не существует, либо заказ уже был отменён или подтвержден).
401	Ошибка авторизации. В заголовках запроса передан неправильный токен.
500	Ошибка на сервере SafeRoute. Обратитесь в техподдержку.

Упрощённый режим работы виджета, только выбор способа доставки.

В этом режиме виджет служит только для выбора доставки, заказы в Личном кабинете он не создаёт. CMS сама должна создать/изменить заказ в SafeRoute, используя API.

Без параметра inputAddress в этом режиме в интерфейсе виджета остаются лишь выбор населённого пункта и блок выбора доставки. С переданной опцией inputAddress: true виджет также будет запрашивать адрес получателя (только для доставки курьером и Почтой России).

После выбора доставки вызывается событие 'select', обработчику которого передаётся объект со свойствами city, delivery, deliveryDate, _meta (а также contacts.address и comment, если был передан параметр inputAddress: true и была выбрана курьерская доставка или доставка Почтой России).

Для работы виджета вам необходимо установить на своем сервере наш API-скрипт и прописать путь к этому скрипту в параметре apiScript виджета.

Скрипт необходим для взаимодействия виджета с сервером SafeRoute и не требует никаких дополнительных настроек, кроме указания в нем вашего токена и ID магазина.

Откройте файл saferoute-widget-api.php и в строке

$widgetApi->setToken('');

вставьте токен, который выводится на странице вашего профиля в Личном кабинете SafeRoute.

А в строке

$widgetApi->setShopId('');

вставьте ID магазина со страницы вашего магазина в Личном кабинете SafeRoute.