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

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 – Почта.

По умолчанию выводится доставка всех доступных типов.

kladr

string

–

КЛАДР населенного пункта пользователя.

Если передан, в виджете сразу будет выбран соответствующий населенный пункт.

fias

string

–

ФИАС населенного пункта пользователя.

Если передан, в виджете сразу будет выбран соответствующий населенный пункт.

regionName

string

–

Название населенного пункта пользователя (например, «Москва», «Казань»).

Наименее предпочтительный способ, рекомендуется использовать КЛАДР и ФИАС.

discount

number

>= 0

Общий размер скидки на все товары (в же той валюте, в которой переданы цены товаров).

currency

number

'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».

userAddressStreet

string

–

Значение для поля «Улица».

userAddressBuilding

string

–

Значение для поля «Дом».

userAddressBulk

string

–

Значение для поля «Корпус».

userAddressApartment

string

–

Значение для поля «Квартира/офис».

itemCount

number

1 – 99

Количество мест в заказе.

Если не задано, берется значение по умолчанию из настроек виджета в Личном кабинете.

nppOption

boolean

–

Считать ли наложенный платеж.

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

hideCODInfo

boolean

–

Используйте, если требуется переопределить значение параметра «Скрыть информацию возможности наложенного платежа» из настроек виджета в Личном кабинете.

products

array

–

Товары. Обязательный параметр, массив должен содержать хотя бы 1 товар.

onlyDeliverySelect

boolean

–

Использовать виджет только для выбора способа доставки (см. раздел “Упрощённый режим работы виджета“).

acquiringEnabled

boolean

–

Переопределяет значение настройки «Использовать встроенный в виджет эквайринг» в Личном кабинете.

Если передано true, виджет будет запущен с шагом оплаты, если передано false, виджет будет запущен без шага оплаты (независимо от настроек в Личном кабинете). Если параметр не задан, используется значение из Личного кабинета.

disableWidgetDeliverySettings

boolean

–

Отключает все настройки виджета (в том числе правила), влияющие на формирование списка вариантов доставки. Список доставок, ПВЗ, сроки и стоимость будут выведены без каких-либо изменений со стороны виджета.

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

Код страны-производителя.

start

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

change

Вызовется при изменении выбранного способа доставки или любого другого значения в виджете (город, адрес, вариант оплаты и т.д.).
Обработчик получит объект со всеми текущими значениями виджета.

stepChange

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

restart

Действует только при включённом эквайринге.

Вызывается при автоматическом перезапуске виджета, когда время ожидания оформления заказа в CMS истекает.

done

Вызовется при получении ответа от сервера SafeRoute после оформления заказа в виджете.
Обработчик получит объект со свойствами:

• id – ID созданного заказа на сервере SafeRoute. Это может быть как финальный ID заказа в Личном кабинете SafeRoute, так и временный ID (в случае, если заказ ещё не был отправлен в Личный кабинет). Данный ID может использоваться для редактирования некоторых параметров заказа уже после его создания, а также для обновления статуса заказа и установки флага оплаты.

• confirmed – флаг, принимающий значение true, если заказ был сразу отправлен в Личный кабинет.

• checkoutSessId – ID сессии чекаута, присутствует только при оплате через встроенный эквайринг.

error

Вызовется при возникновении ошибок при обработке запроса или при передаче в виджет некорректных или неполных данных.
Обработчик получит массив с текстовым описанием ошибок.

select

Вызывается в упрощённом режиме работы виджета, когда виджет используется лишь для выбора варианта доставки.

Обработчик получает объект со свойствами city, delivery и deliveryDate.

Параметр

Описание

city.name

Название выбранного города или населённого пункта.

city.kladr

КЛАДР выбранного населённого пункта (если есть).

city.fias

ФИАС выбранного населённого пункта (если есть).

city.countryIsoCode

ISO-код страны выбранного населённого пункта.

city.region

Регион населённого пункта.

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.totalPrice

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

delivery.priceCommissionCod

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

delivery.priceCommissionCodCard

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

delivery.isMyDelivery

Если присутствует и содержит true, выбран «собственный» вариант доставки.

delivery.nppDisabled

Если присутствует и содержит true, оплата наложенным платежом запрещена.

delivery.isPost

Является ли почтой выбранный способ доставки.

delivery.point.id

ID выбранной точки самовывоза.

delivery.point.address

Адрес выбранной точки самовывоза.

delivery.point.deliveryHoldDays

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

deliveryDate.date
deliveryDate.time.timeFrom
deliveryDate.time.timeTo

Дата (в формате YYYY-MM-DD) и временной интервал, которые выбрал пользователь для доставки курьером.

payType

Выбранный тип оплаты (только при включённом эквайринге).

1 – оплата при получении;
2 – оплата он-лайн через виджет;
3 – оплата другим способом оплаты (только при включённой в настройках опции “Добавить вариант «Другой способ оплаты»“).

payTypeCommission

Комиссия для выбранного способа оплаты (налож. платёж / эквайринг) в той валюте, которая передана в виджет (только при включённом эквайринге).

totalOrderPrice

Общая стоимость к оплате (стоимость товаров + доставка + комиссии) в той валюте, которая передана в виджет (только при включённом эквайринге).

_meta.fullDeliveryAddress

Полный адрес доставки заказа одной строкой (в случае самовывоза - адрес самовывоза).

_meta.commonDeliveryData

Общая информация о заказе одной строкой: тип доставки, компания доставки, адрес доставки, дата.

_meta.widgetSettings.payMethodWithCOD

Способ оплаты (чаще всего, его ID) с оплатой наложенным платежом наличными.

Берётся из настройки “Способ оплаты (в чекауте) для оплаты заказа наличными при получении“ (Настройки виджета => Настройки CMS).

_meta.widgetSettings.cardPayMethodWithCOD

Способ оплаты (чаще всего, его ID) с оплатой наложенным платежом картой.

Берётся из настройки “Способ оплаты (в чекауте) для оплаты заказа картой при получении“ (Настройки виджета => Настройки CMS).

Заголовок

Описание

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

Считать ли наложенный платеж. Можно передать только до переноса заказа в Личный кабинет.

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

HTTP-статус

Описание

200

Запрос прошёл успешно.

Параметр cabinetId содержит ID заказа в Личном кабинете SafeRoute. Значение появится сразу после передачи заказа в Личный кабинет. Если заказ ещё не был отправлен в Личный кабинет, cabinetId будет содержать null.

400

Ошибка. Параметр code содержит код ошибки:

• 0 – не передан ID заказа;

• 1001 – заказ с переданным ID не найден;

• 2001 – передан неправильный ID магазина;

• 1002 – ошибка при создании заказа в Личном кабинете (детали ошибки находятся в параметре message), обратитесь в техподдержку;

• 1003 – ошибка при обновлении заказа в Личном кабинете, обратитесь в техподдержку.

401

Ошибка авторизации. В заголовках запроса передан неправильный токен.

500

Ошибка на сервере SafeRoute. Обратитесь в техподдержку.

id

ID заказа в Личном кабинете SafeRoute.

statusSR

Статус заказа в SafeRoute.

statusSRName

Текстовое название статуса заказа в SafeRoute.

statusCMS

Статус заказа в CMS, которому соответствует статус заказа в SafeRoute.

trackNumber

Трек-номер заказа.

Token

Токен аккаунта.

Shop-Id

ID магазина.

Api-Key

API-ключ.

Заголовок

Описание

Authorization:Bearer {TOKEN}

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

shop-id:{SHOP_ID}

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

Параметр

Тип

Описание

checkoutSessId

string

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

HTTP-статус

Описание

200

Запрос прошёл успешно, заказ подтверждён.

400

Ошибка. Параметр code содержит код ошибки:

• 2001 – передан неправильный ID магазина;

• 7001 – ошибка подтверждения транзакции в платёжной системе;

• 7003 – неправильный ID сессии (ID не существует, либо заказ уже был отменён или подтвержден).

401

Ошибка авторизации. В заголовках запроса передан неправильный токен.

500

Ошибка на сервере SafeRoute. Обратитесь в техподдержку.