На вашу почту отправлено письмо с дальнейшими инструкциями.
Корзинный виджет DDelivery можно встраивать в любые веб-сайты, написанные на любых PHP-фреймворках и с использованием любых CMS.
Виджет позволяет выбрать оптимальный способ доставки при оформлении заказа, а также отправляет информацию о заказе в Личный кабинет DDelivery.
1. Разместите следующий код внутри тега <head>
:<script src="https://ddelivery.ru/front/widget-cart/public/api.js"></script>
2. Разместите следующий код в том месте страницы, где должен располагаться виджет:<div id="dd-widget"></div>
// Инициализация виджета
var widget = new DDeliveryWidgetCart("dd-widget", { apiScript: "/dd-widget-api.php",
products: [ { name: "Плюшевый мишка", count: 1 } ] });
// Обработчики событий
widget.on("change", function (data) {
// Вызовется при изменении выбранного способа доставки
// или любого другого значения в виджете });
widget.on("afterSubmit", function (response) {
// Вызовется при получении ответа от сервера DDelivery });
widget.on("error", function (errors) {
// Вызовется при возникновении ошибок при обработке запроса,
// при передаче в виджет некорректных или неполных данных
console.error(errors); });
Конструктор DDeliveryWidgetCart()
принимает 2 аргумента:
Список параметров и данных, которые можно передавать конструктору:
Параметр | Обязат. | Описание |
---|---|---|
apiScript | Путь к API-скрипту (скачать API-скрипт). Если не указать, по умолчанию виджет будет обращаться по адресу "/dd-widget-api.php" . | |
lang | Язык интерфейса виджета. Всего доступно 3 языка интерфейса: русский ( ru , задан по умолчанию), английский (en ) и китайский (zh ). | |
city | ID города пользователя в базе DDelivery. Если передан, в виджете изначально будет выбран соответствующий город. Если не передан, виджет попытается определить город пользователя автоматически или попросит его выбрать нужный город самостоятельно. | |
stopSubmit | Если установлено true , после нажатия кнопки подтверждения в виджете данные на сервер отправлены не будут (будет вызван лишь обработчик события "beforeSubmit" ).В случае использования этого параметра данные на сервер можно отправить вручную при помощи метода widget.submit() . | |
userFullName | ФИО клиента, которое будет изначально содержаться в поле «ФИО». | |
userPhone | Номер телефона клиента, который будет изначально содержаться в поле «Телефон». | |
itemCount | Количество мест в заказе. Если не задано, берется значение по умолчанию из панели настройки виджета. Допустимые значения: 1 – 99. | |
width | Ширина в см. Дробные значения округляются. Допустимые значения: 0 – 999 999. Если не задана, берется значение по умолчанию из панели настройки виджета. | |
height | Высота в см. Дробные значения округляются. Допустимые значения: 0 – 999 999. Если не задана, берется значение по умолчанию из панели настройки виджета. | |
length | Длина в см. Дробные значения округляются. Допустимые значения: 0 – 999 999. Если не задана, берется значение по умолчанию из панели настройки виджета. | |
weight | Вес в кг. Может быть дробным, не может быть меньше 0. Если не задан, берется значение по умолчанию из панели настройки виджета. | |
priceDeclared | Оценочная стоимость (в рублях). По умолчанию равна стоимости всего заказа (в случаях, когда значение не передано, либо передан 0). Не может быть меньше 0. | |
discount | Общий размер скидки на все товары (в рублях). Дробные значения округляются, не может быть меньше 0. | |
nppOption | Считать ли наложенный платеж (true / false ).Если для выбранного пользователем способа доставки оплата наложенным платежом запрещена, переданное данному параметру значение проигнорируется и будет заменено на false . | |
products | Массив товаров. Должен быть задан и содержать хотя бы один товар (в случае, если не было передано ни одного комплекта, см. ниже). | |
products.name | Название товара. | |
products.vendorCode | Артикул. | |
products.barcode | Штрих-код. | |
products.nds | НДС. Возможные значения: 0, 10, 20. По умолчанию: 0. | |
products.price | Да | Стоимость единицы товара. Дробные значения не округляются. Допустимые значения: 0 – 999 999. |
products.discount | Размер скидки на товар (в рублях). Дробные значения округляются, не может быть меньше 0. | |
products.count | Да | Количество товаров. Допустимые значения: 1 – 999. |
productGroups | Массив комплектов товаров. Если содержит хотя бы один комплект, отдельные товары в виджет можно не передавать. | |
productGroups.vendorCode | Да | Артикул комплекта. |
productGroups.count | Количество комплектов. Допустимые значения: 1 – 999. По умолчанию: 1. | |
productGroups.price | Стоимость комплекта. Дробные значения не округляются. Допустимые значения: 0 – 999 999. |
Если какие-то из обязательных параметров окажутся не заданы, либо значение какого-либо параметра окажется некорректным, будет вызван обработчик события "error"
с информацией об ошибках.
Метод widget.on()
навешивает обработчики на те или иные события:
Имя события | Описание |
---|---|
start | Вызовется сразу после запуска виджета, как только в него будут прогружены все необходимые для работы данные. |
beforeSubmit | Вызовется после нажатия кнопки подтверждения в виджете в случае, когда никаких ошибок нет и все данные корректны. Обработчик получит объект со всеми текущими значениями виджета. |
afterSubmit | Вызовется при получении ответа от сервера DDelivery после нажатия кнопки подтверждения в виджете (либо после вызова метода widget.submit() вручную).Обработчик получит объект с результатом ответа, имеющий следующие свойства:
|
change | Вызовется при изменении выбранного способа доставки или любого другого значения в виджете (город, адрес и т.д.). Обработчик получит объект со всеми текущими значениями виджета. |
back | Вызовется при переходе от экрана подтверждения данных назад к форме с выбором способа доставки. |
error | Вызовется при возникновении ошибок при обработке запроса или при передаче в виджет некорректных или неполных данных. Обработчик получит массив с текстовым описанием ошибок. |
В случае, если отправлять данные о заказе на сервер DDelivery автоматически после нажатия кнопки подтверждения в виджете не нужно, можно воспользоваться параметром stopSubmit
.
В этом случае можно инициировать отправку заказа на сервер DDelivery вручную, вызвав метод widget.submit()
. Вызов этого метода не вызывает обработчик события "beforeSubmit"
, однако он вызовет "afterSubmit"
с результатом обработки запроса.
Внимание: widget.submit()
срабатывает лишь на экране подтверждения введенных данных, поэтому оптимальным вариантом будет вызывать его только после наступления события "beforeSubmit"
, означающего, что пользователь подтвердил все введенные параметры.
Виджет появится на странице сразу же после вызова конструктора DDeliveryWidgetCart()
. В объекте с параметрами виджета должен быть передан как минимум 1 параметр: products
хотя бы с одним товаром. При его отсутствии будет вызван обработчик события "error"
, а сам виджет на странице не отобразится.
Для удаления виджета со страницы используйте метод widget.destruct()
. Этот метод следует вызывать и при перезапуске виджета (например, если вам потребовалось запустить виджет повторно с новыми параметрами).
Обработчики событий "beforeSubmit"
и "change"
получают объект со всеми внутренними значениями виджета, которые будут использованы для создания заказа.
Ниже представлено описание наиболее важных из этих параметров.
Параметр | Описание |
---|---|
city.id | ID выбранного в виджете города в системе DDelivery. |
city.name | Название выбранного города. |
contacts.address.street | Улица. |
contacts.address.house | Дом. |
contacts.address.flat | Квартира. |
contacts.address.index | Индекс. |
contacts.fullName | ФИО. |
contacts.phone | Телефон. |
delivery.delivery_company_name delivery.point.delivery_company_name | Название выбранной компании доставки. |
delivery.delivery_date delivery.point.delivery_date | Дата доставки. |
delivery.delivery_days delivery.point.delivery_days | Количество дней, через которое заказ будет доставлен. |
delivery.is_cash delivery.point.is_cash | Возможна ли оплата наличными. |
delivery.total_price delivery.point.price_delivery | Стоимость доставки. |
delivery.is_my_delivery delivery.point.is_my_delivery | Появляется и содержит true , если выбран «собственный» вариант доставки. |
delivery.npp_disabled | Если присутствует и содержит true , оплата наложенным платежом запрещена. |
delivery.point.id | ID выбранной точки самовывоза в системе DDelivery. |
delivery.point.address | Адрес выбранной точки самовывоза. |
По умолчанию заказы, переданные виджетом, появляются в Личном кабинете DDelivery сразу же, как только будет задано значение для npp_option
или payment_method
при помощи метода update-order.json
(см. ниже).
Однако если при запуске виджету был передан параметр nppOption
, вызывать update-order.json
не потребуется – заказ появится в Личном кабинете моментально после отправки данных через виджет. Признаком передачи в Личный кабинет в этом случае будет являться значение true
параметра confirmed
(см. событие "afterSubmit"
).
При необходимости вы можете настроить отправку заказов в Личный кабинет лишь после присвоения заказам определенного статуса (Панель управления виджетом > Раздел «Настройки CMS» > Селект «Статус CMS для передачи заказов в Личный кабинет DDelivery») или после совершения оплаты клиентом (Панель управления виджетом > Раздел «Настройки CMS» > «Передать заказ в Личный кабинет при получении статуса предварительной оплаты»).
Заказы, которые ещё не были переданы в Личный кабинет, находятся во временном хранилище на сервере DDelivery и получают временный уникальный ID. Используя этот ID, можно изменять следующие параметры заказа:
Если вы не передали в виджет значение nppOption
, то для отправки заказа в Личный кабинет вы обязательно должны либо присвоить этому заказу способ оплаты, либо задать значение для флага наложенного платежа.
Пока для заказа не определен один из этих параметров, он не появится в Личном кабинете.
Каждый заказ может находиться во временном хранилище не более месяца. Если в течение месяца заказ так и не будет переведен в Личный кабинет, он будет удален.
Заказы, для которых выбирается один из ваших собственных вариантов доставки (создаются в Панели управления виджетом), не попадают ни в Личный кабинет, ни во временное хранилище заказов DDelivery. Вы должны обрабатывать их самостоятельно.
Признаком такого заказа является наличие флага delivery.is_my_delivery
(для курьерской доставки) или delivery.point.is_my_delivery
(для самовывоза) в объекте с данными виджета, который получают обработчики событий "change"
и "beforeSubmit"
.
Кроме того, поскольку данные заказы не сохраняются на сервере DDelivery, параметр id
, получаемый обработчиком "afterSubmit"
, будет содержать вместо идентификатора null
.
Чтобы попасть в Панель управления виджетом, зайдите в Личный кабинет DDelivery, затем перейдите в раздел «Настройки» > «Магазины». Откройте тот магазин из списка, для которого требуется настроить виджет. На странице магазина нажмите кнопку «Панель настроек виджетов».
POST https://ddelivery.ru/api/{KEY}/sdk/update-order.json
Где {KEY} – API-ключ интернет-магазина (находится в Личном кабинете на странице магазина).
Параметр | Обязат. | Описание |
---|---|---|
id | Да | ID заказа. Отдается виджетом после создания заказа, либо текущим API (параметр cabinet_id ), если после запроса заказ был отправлен в Личный кабинет и его ID сменился с временного на постоянный.Важно: пока заказ не был отправлен в Личный кабинет, в этот параметр следует передавать его временный ID, полученный из виджета. Однако после отправки заказа в Личный кабинет доступ по временному ID будет невозможен и в параметр нужно будет передавать уже постоянный ID ( cabinet_id ). |
status | Статус заказа. | |
payment | Флаг оплаты (true / false ). | |
cms_id | ID (или номер) заказа в CMS магазина. Может быть как числом, так и произвольной строкой. | |
payment_method | Способ оплаты. Можно передать лишь до переноса заказа в Личный кабинет. | |
npp_option | Считать ли наложенный платеж ( Внимание: если для выбранного способа доставки оплата наложенным платежом запрещена, этот параметр сразу будет иметь значение |
Параметр | Описание |
---|---|
status | Статус выполнения запроса ("ok" или "error"). |
data.cabinet_id | ID заказа в Личном кабинете DDelivery. Значение появится сразу передачи заказа в Личный кабинет. Если заказ ещё не был отправлен в Личный кабинет, параметр будет содержать значение null . |
message | Текст сообщения об ошибке (в случае ошибки). |
Для использования настроек из раздела «Настройки CMS» Панели управления виджетом требуется:
Например, в настройках вы задали следующий путь к API: https://example.com/ddelivery-api/
Система будет ожидать списки по следующим адресам: // Список статусов заказа
https://example.com/ddelivery-api/statuses.json
// Список способов оплаты
https://example.com/ddelivery-api/payment-methods.json
При запросе к данным API будет передаваться GET-параметр k
, содержащий API-ключ магазина.
Оба API должны возвращать списки в следующем формате:
{
"status_1": "Статус 1",
"status_2": "Статус 2",
"status_3": "Статус 3"
}
В случае, если в основных настройках виджета вы указали путь к API (см. выше), при изменении статуса заказа в Личном кабинете DDelivery будет отправляться POST-запрос на адрес:
https://example.com/ddelivery-api/traffic-orders.json
При запросе к данному API будет передан GET-параметр k
, содержащий API-ключ магазина, а также POST-параметры:
id
– ID заказа в Личном кабинете DDelivery;status_dd
– статус заказа в DDelivery;status_dd_name
– название статуса заказа в DDelivery;status_cms
– статус заказа в CMS, которому соответствует статус заказа в DDelivery;track_number
– трек-номер заказа.Для работы виджета вам необходимо установить на своем сервере наш API-скрипт и прописать путь к этому скрипту в параметре apiScript
виджета.
Скрипт необходим для взаимодействия виджета с сервером DDelivery и не требует никаких дополнительных настроек, кроме указания в нем API-ключа вашего магазина.
Откройте файл dd-widget-api.php
и в строке $widgetApi->setApiKey('');
вставьте API-ключ, взятый со страницы вашего магазина в Личном кабинете DDelivery.
Трекинг-виджет позволит вашим покупателям получить следующую информацию о доставке их заказа:
Отслеживать заказ можно как по его ID в системе DDelivery, так и по ID в CMS вашего интернет-магазина и трек-номеру службы доставки.
1. Разместите следующий код внутри тега <head>
:<script src="https://ddelivery.ru/front/widget-tracking/public/api.js"></script>
2. Разместите следующий код в том месте страницы, где должен располагаться виджет:<div id="dd-widget-tracking"></div>
// Инициализация виджета
new DDeliveryWidgetTracking("dd-widget-tracking", { apiScript: "/dd-widget-api.php" });
Конструктор DDeliveryWidgetTracking()
принимает 2 аргумента:
Список параметров, которые можно передавать конструктору:
Параметр | Описание |
---|---|
apiScript | Путь к API-скрипту (скачать API-скрипт). Если не указать, по умолчанию виджет будет обращаться по адресу "/dd-widget-api.php" . |
lang | Язык интерфейса виджета. Всего доступно 3 языка интерфейса: русский ( ru , задан по умолчанию), английский (en ) и китайский (zh ). |
autofocus | Автоматический перевод фокуса в поле ввода номера заказа сразу после появления виджета на странице. По умолчанию true . |
Чтобы попасть в Панель управления виджетом, зайдите в Личный кабинет DDelivery, затем перейдите в раздел «Настройки» > «Магазины». Откройте тот магазин из списка, для которого требуется настроить виджет. На странице магазина нажмите кнопку «Панель настроек виджетов». В панели перейдите в раздел «Трекинг-виджет».
Для работы виджета вам необходимо установить на своем сервере наш API-скрипт и прописать путь к этому скрипту в параметре apiScript
виджета.
Скрипт необходим для взаимодействия виджета с сервером DDelivery и не требует никаких дополнительных настроек, кроме указания в нем API-ключа вашего магазина.
Откройте файл dd-widget-api.php
и в строке $widgetApi->setApiKey('');
вставьте API-ключ, взятый со страницы вашего магазина в Личном кабинете DDelivery.
Карточный виджет предназначен для отображения доступных вариантов доставки во время оформления клиентом покупок на вашем сайте. Виджет покажет самые доступные варианты доставки и их сроки. Завершить оформление доставки клиент сможет в корзине.
1. Разместите следующий код внутри тега <head>
:<script src="https://ddelivery.ru/front/widget-card/public/api.js"></script>
2. Разместите следующий код в том месте страницы, где должен располагаться виджет:<div id="dd-widget-card"></div>
// Инициализация виджета
new DDeliveryWidgetCard("dd-widget-card", { apiScript: "/dd-widget-api.php" });
Конструктор DDeliveryWidgetCard()
принимает 2 аргумента:
Список параметров, которые можно передавать конструктору:
Параметр | Описание |
---|---|
apiScript | Путь к API-скрипту (скачать API-скрипт). Если не указать, по умолчанию виджет будет обращаться по адресу "/dd-widget-api.php" . |
lang | Язык интерфейса виджета. Всего доступно 3 языка интерфейса: русский ( ru , задан по умолчанию), английский (en ) и китайский (zh ). |
city | ID города пользователя в базе DDelivery. Если передан, в виджете сразу будет выбран соответствующий город. Если не передан, виджет отобразит селект для выбора города доставки. |
priceDeclared | Оценочная стоимость (в рублях). По умолчанию 0. |
pricePayment | Наложенный платеж (в рублях). По умолчанию 0. |
weight | Вес в кг. Может быть дробным, не может быть меньше 0. |
Габариты (и вес, если не передан) для вычисления стоимости доставки берутся из значений по умолчанию для корзинного виджета, которые можно изменить в панели управления виджетом.
Чтобы попасть в Панель управления виджетом, зайдите в Личный кабинет DDelivery, затем перейдите в раздел «Настройки» > «Магазины». Откройте тот магазин из списка, для которого требуется настроить виджет. На странице магазина нажмите кнопку «Панель настроек виджетов».
Для работы виджета вам необходимо установить на своем сервере наш API-скрипт и прописать путь к этому скрипту в параметре apiScript
виджета.
Скрипт необходим для взаимодействия виджета с сервером DDelivery и не требует никаких дополнительных настроек, кроме указания в нем API-ключа вашего магазина.
Откройте файл dd-widget-api.php
и в строке $widgetApi->setApiKey('');
вставьте API-ключ, взятый со страницы вашего магазина в Личном кабинете DDelivery.