Search by 
ddelivery / clientsdk
SDK for quick creation DDelivery client integration
1.4.3
2016-07-02 09:39 UTC
This package is not auto-updated.
Last update: 2025-07-05 21:44:30 UTC
README
Client SDK - SDK для быстрой разработки клиентских решений для сервиса доставки DDelivery.
ПАМ(панель администрирования модулей) - ресурс который организовует работу модуля и взаимодействует с Client SDK и сервисом доставки DDelivery. Client SDK привязывается к ПАМ посредством АПИ ключа, полученном в личном кабинете cabinet.ddelivery.ru. В дальнейшем в ПАМ можно настроить гибкие правила доставки модуля.
SDK ID - индентификатор, получаемый при оформлении доставки через модуль.
DDelivery ID - идентификатор, получаемый при оформлении заявки на доставку сервиса.
Адаптер - класс который организовует выдачу необходимой информации от CMS. От него нужно наследовать свой класс. (для php приложений).
Для разработки решений для систем не использующих PHP, смотрите раздел этой инструкции "Создание модуля через API", а также пункт "5. Вывод модуля доставки на странице оформления доставки"
Структура директорий
application/ Исходники сдк
example/ Пример создания расширения
Создание интеграции
Client SDK содержит все механизмы для работы модуля, необходимо выполнить несколько этапов:
-
Запустить рабочий пример в каталоге example/ .
-
Переопределить методы родительского класса Adapter(пример IntegratorAdapter.php)
-
Учитывая особенность CMS, определить точку входа в модуль, подключить нужные системные скрипты для CMS и вызвать все необходимые методы для работы Client SDK(пример example/ajax.php).
-
Создать локальное хранилище на стороне CMS вызвав метод initStorage класса Business (Далее продумать вызов этого метода при установке модуля в CMS)
-
Привязать апи ключ магазина к ПАМ.
-
Вывести способ доставки на странице оформления заказа CMS(пример index.php). Для этого к этой странице checkout необходимо подключить js файл и вызвать js метод с определенными параметрами и получить SDK ID. При выборе пункта доставки, организовать фильтрацию способов оплаты не поддерживающих наложенны платеж для пунктов доставки, которые его не поддерживают.
-
При окончании оформления заказа (в момент когда цмс вставляет в БД заказ и выбран способ оплаты клиентом) необходимо вызвать метод onCmsOrderFinish класса Business для привязки закза CMS и SDK ID.
-
При сохранении заказа перепроверить валидность данных доставки через метод viewOrder класса Business используя SDK ID.
-
При изменении статуса заказа или по какомуто другому событию вызвать метод для отправки заказа (onCmsChangeStatus или cmsSendOrder соответственно) класса Business.
Запуск рабочего примера
Для запуска примера необходимо загрузить сдк в каталог в котором будет находится модуль.
example/IntegratorAdapter.php - класс в котором необходимо переопрелить указанные методы, является
связующим звеном между Client SDK и CMS.
example/ajax.php - файл который является точкой входа в CMS и запускает на выполнение Client SDK.
example/index.php - пример кнопки для открытия модуля на странице оформления заказа.
example/delivery.php - пример отправки заказа, и вызова дополнительных методов.
example/db.sqlite - хранилище которое использует Client SDK
```
Запустите файл index.php в директории example/, для запуска примера достаточно использовать тестовый апи ключ.
Из коробки пример работы модуля должен запустится корректно, в дальнейшем при разработке
интеграции рекомендуется руководствоватся примером из example/
1. Переопределить методы родительского класса Adapter
-------------------------------------------------------
В первую очередь необходимо унаследовать переопределить абстрактные методы, при необходимости можно переопределить
родительские.
Для начала работы необходимо получить апи ключ на сайте cabinet.ddelivery.ru
Привязка к ПАМ происходит при первом вхождении
через точку входа по ссылке ajax.php?action=admin, при этом происходит проверка
наличия прав администратора CMS и переход в ПАМ где можно проводить гибкую настройку правил доставки
Получить апи ключ из настроек
```
public function getApiKey(){
return 'api_key';
}
```
Проверка пользователя на наличие прав администратора CMS
```
public function isAdmin(){
if($_SESSION['admin'] == 1){
return true;
}
return false;
}
```
Название CMS
```
public function getCmsName(){
return "Joomla";
return "Bitrix";
...
}
```
Версия CMS
```
public function getCmsVersion(){
return '1.1';
}
```
Получить содержание корзины. В зависимости от того где CMS хранит содержимое корзины(сессия, БД, cookies),
ее необходимо преобразовать в массив как в примере IntegratorAdapter.php
```
public function getProductCart(){
return array(
array(
"id"=>12,
"name"=>"Мобильный телефон",
"width"=>10,
"height"=>10,
"length"=>10,
"weight"=>1,
"price"=>1110,
"quantity"=>2,
"sku"=>"app2"
),
array(
...
);
);
}
```
Получить скидку для клиента, для того чтобы отнять ее от общей стоимости заказа
```
public function getDiscount(){
return 50;
}
```
Client SDK предусматривает автоматическую синхронизацию статусов магазина со статусами
DDelivery.ru
При синхронизации статусов заказов необходимо произвести UPDATE полей статуса заказа
в БД заказов. Синхронизация будет проводится 2 раза в сутки
В качестве аргумента передается массив $order
```
array(
'id' => 'status',
'id2' => 'status2',
);
```
, где 'id' - идентификатор заказа CMS, 'status' - значение статуса для CMS(соответствие статусов
настраивается в ПАМ, в разделе Настройки CMS).
```
public function changeStatus(array $orders){
foreach($orders as $key=>$item){
$query = "UPDATE orders_table_cms SET status_cms=$item WHERE order_id=$key"
}
}
```
Получить поля заказа из CMS по идентификатору
Значения ключей:
'city' => город назначения,
'payment' => тип оплаты,
'status' => статус заказа,
'sum' => сумма заказа,
'delivery' => стоимость доставки
```
public function getOrder($id){
return array(
'city' => 'Урюпинск',
'payment' => 22,
'status' => 'Статус',
'sum' => 2200,
'delivery' => 220,
);
}
```
Получить поля списка заказов за период c $from $to заказа из CMS
$from - строка в формате 'Y.m.d'
$to - строка в формате 'Y.m.d'
```
public function getOrders($from, $to){
return array(
array(
'city' => 'Урюпинск',
'payment' => 22,
'status' => 'Статус',
'sum' => 2200,
'delivery' => 220,
),
array(
'city' => 'г. Москва, Московская область',
'payment' => 'Пример оплаты',
'status' => 'Статус 222',
'sum' => 2100,
'delivery' => 120,
)
);
}
```
Получить список полей пользователя в виде массива с предопределенным ключом
Необходимо это для того чтобы при окончании оформления заказа в модуле поля заполнялись автоматически
Если это зарегистрированный пользователь то возможно CMS хранит значения в сессии,
можно взять их оттудова, или передать через URL при инициализации модуля
```
public function getUserParams($request){
return array(
self::USER_FIELD_STREET => 'Цветаевой',
self::USER_FIELD_COMMENT => 'Комментарий',
self::USER_FIELD_HOUSE => '2а',
self::USER_FIELD_FLAT => '123',
self::USER_FIELD_ZIP => '10101'
);
}
```
Получить список статусов заказов из CMS - в дальнейшем они
атоматически подтягиваются в ПАМ и можно настраивать соответствие статусов в разделе Настройки CMS
```
public function getCmsOrderStatusList(){
return array('10' => 'Завершен', '11' => 'Куплен');
}
```
Получить список способов опланы для настройки в ПАМ, для выбора способа оплаты соответствующему
наложенному платежу (раздел Настройки CMS в ПАМ)
```
public function getCmsPaymentList(){
return array('14' => 'Наличными', '17' => 'Карточкой');
}
```
Есть возможность добавлять свои кастомные поля и далее в ПАМ сохранять значения
и потом получать значения локально
self::FIELD_TYPE_TEXT - текстовое поле
self::FIELD_TYPE_CHECKBOX - чекбокс
self::FIELD_TYPE_LIST - список
```
public function getCustomSettingsFields(){
return array(
array(
"title" => "Название (Пример кастомного поля)",
"type" => self::FIELD_TYPE_TEXT,
"name" => "name",
//"items" => getStatusList(),
"default" => 0,
"data_type" => array("string"),
"required" => 1
),
array(
"title" => "Выводить способ доставки(Пример кастомного поля)",
"type" => self::FIELD_TYPE_CHECKBOX,
"name" => "checker",
"default" => true,
"data_type" => array("int"),
"required" => 1
)
);
}
```
Получить настройки БД
```
public function getDbConfig(){
return array(
'pdo' => new \PDO('mysql:host=localhost;dbname=ddelivery', 'root', '0', array(\PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8")),
'prefix' => '',
);
}
```
Для редактирования заказа необходимо переопределить методы получения товаров заказа и скидки в административной
панели CMS
```
public function getAdminDiscount(){
//$this->getDiscount();
}
public function getAdminProductCart(){
//$this->getProductCart();
}
```
2.Определить учитывая особенность CMS точку входа в модуль
-------------------------------------------------------
Пример хранится в файле example/ajax.php
Чтобы запустить обработчик Client SDK, необходимо его получить из контейнера.
Объект DDelivery\Adapter\Container - позволяет получать объекты, а
на вход параметром получает класс Adapter
```
$adapter = new IntegratorAdapter();
$container = new Container(array('adapter' => $adapter));
```
Например точку входа в Client SDK можно получить, вызвав метод render,
$_REQUEST - массив с GET и POST параметрами запроса
```
$container->getUi()->render($_REQUEST);
```
С помощью контейнера можно получать и другие объекты при необходимости
например чтобы выполнить этап 3 или 4, необходимо получить объект Business из контейнера, для этого
создаем контейнер и вызываем соответствующий метод.
```
$adapter = new IntegratorAdapter();
$container = new Container(array('adapter' => $adapter));
$business = $container->getBusiness();
```
Если неоходима более гибкаая настройка объектов или хранилищ, есть возможность
самостоятельно переопределить Container и сконфигурировать все объекты
согласно интерфейсов, ClientSDK будет работать с ними
3.Создание хранилищ
--------------------
Для работы модуля на стороне CMS необходимо создать хранилища.
Для начала необходимо сконфигурировать в адаптере настройки БД и вызвать метод
initStorage() класса Business, возпользовавшись контейнером:
```
$adapter = new IntegratorAdapter();
$container = new Container(array('adapter' => $adapter));
$business = $container->getBusiness();
// Создаем хранилища
$business->initStorage();
```
4.Привязка апи ключа магазина с центральной административной панелью (CAP)
------------------------------------------------------------------------
Для того чтобы осуществить привязку необходимо перейти по ссылке(при условии что привязки
по этому апи ключу ранее не было), у которой url http://точка входа/ajax.php?action=admin .
Например http://site/ddelivery/ajax.php?action=admin
Если привязка по АПИ ключу была проведена, нужно осуществить сброс привязки -
через личный кабинет cabinet.ddelivery.ru
5. Вывод модуля доставки на странице оформления доставки
--------------------------------------------------------
Для этого на страницу оформления заказа нужно подключить скрипт
```
<script src="http://sdk.ddelivery.ru/assets/js/ddelivery_v2.js"></script>
```
Вставить элемент в котором инициализируется модуль
```
<div id="ddelivery_container_place"></div>
```
После подключения будет в js доступен объект DDeliveryModule, он позволяет открывать
окно выбора пункта доставки.
Для начала нужно определить js методы в виде объекта, и объект с параметрами и передать их параметром
в вызов функцию DDeliveryModule.init
```
params{
url: 'ajax.php?action=module',
width: 550,
height: 440,
}
callbacks = {
resize_event:function(data){
// событие при изменению размеров модуля
// в объекте data новые размеры
},
open: function(){
// Хук на открытие окна;
return true;
},
change: function(data){
// Хук на окончание оформления заказа и обработка результата;
},
close_map: function(data){
// Хук на закрытие карты
},
price: function(data){
// хук на получение цены текущей доставки при переключении
// и возможность НПП в этом пункте
}
};
// 'ddelivery_container_place' - идентификатор div-a в котором инициализируется модуль
DDeliveryModule.init(params, callbacks, 'ddelivery_container_place');
```
это позволит получать результат оформления доставки и обрабатывать его
При окончании оформления доставки во время вызова метода change(см. параметр callbacks) присылаются данные
с информацией про доставку в виде js объекта
```
city: "151184" - id города доставки
city_name: "г. Москва" - Город доставки
client_price: 281.49 - Цена доставки
company: "20" - id компании доставки
company_name: "DPD Parcel" - Название компании доставки
id: 1198 - SDK ID (не путать с ID заявки на ddelivery.ru)
info: "Курьерская доставка, ул. Цветаева, 15, кв. 122, ID компании:20, г. Москва" - описание в виде строки
payment_availability: 1 - возможность наложенного платежа
point: 0 - id точки
to_flat: "122" - квартира
to_house: "15" - дом
to_street: "Цветаева" - улица
type: 2 - тип доставки 1 - Самовывоз, 2 - Курьерка, 3 - Почта
```
Важно средствами CMS запомнить id, так как в дальнейшем при вызове метода можно получить информацию о заказе
по этому id(для проверки цены например). Тоесть до вызова метода в пункте 6, необходимо хранить
значение id, например в сессии или передавать между страницами офрмления заказа в полях формы.
6. Проверка валидности данных доставки
----------------------------------------------------------------
Возможно повторно получать информацию о цене и других полях доставки(те поля что приходят в js методе change клиенту)
```
$adapter = new IntegratorAdapter();
$container = new Container(array('adapter' => $adapter));
$business = $container->getBusiness();
// $id - id заказа в сдк
$business->viewOrder($id)
```
7. При окончании оформления заказа
-----------------------------------------
В момент когда цмс вставляет в БД заказ и выбран способ оплаты клиентом
необходимо вызвать метод onCmsOrderFinish класса Business для того чтобы осуществить
привязку заказа CMS к SDK ID .
```
$adapter = new IntegratorAdapter();
$container = new Container(array('adapter' => $adapter));
$business = $container->getBusiness();
//$payment - id способа оплаты
//$status - id статуса заказа
//$id - id заказа в сдк
//$cmsId - id заказа в CMS
//$to_name - имя клиента
//$to_phone - номер телефона
//$to_email - email
//$payment_price - наложенный платеж, по умолчанию берется из значения параметра настроек варианта оплаты,
//но возможно выставлять и вручную
$business->onCmsOrderFinish($sdkId, $cmsId, $payment, $status, $to_name, $to_phone, $to_email, $payment_price = null)
```
9. Отправка заявки на доставку на сервис DDelivery.ru при изменении статуса заказа
----------------------------------------------------------------------------------
При правильной настройке адаптера в ПАМ, в разделе "Настройки CMS" доступны настройки
статуса заказа для отправки заявки. В данном случае при смене статуса необходимо
вызвать метод onCmsChangeStatus класса Business.
```
$adapter = new IntegratorAdapter();
$container = new Container(array('adapter' => $adapter));
$business = $container->getBusiness();
//$id - id заказа в сдк
//$cmsId - id заказа в CMS
//$payment - id способа оплаты
//$status - id статуса заказа
//$to_name - имя клиента
//$to_phone - номер телефона
//$to_email - email
//$payment_price - наложенный платеж, по умолчанию берется из значения параметра настроек варианта оплаты,
//но возможно выставлять и вручную
$business->onCmsChangeStatus($id, $cmsId, $payment, $status, $to_name, $to_phone, $to_email, $payment_price = null);
```
при этом метод сравнит значение $status со значением в настройках ПАМ и в зависимости
от этого отправит заявку
10. Отправка заявки вручную
---------------------------
При вызове метода cmsSendOrder класса Business, отсылается заявка на сервер DDelivery.ru.
```
$adapter = new IntegratorAdapter();
$container = new Container(array('adapter' => $adapter));
$business = $container->getBusiness();
//$id - id заказа в сдк
//$cmsId - id заказа в CMS
//$payment - id способа оплаты
//$status - id статуса заказа
//$to_name - имя клиента
//$to_phone - номер телефона
//$to_email - email
//$payment_price - наложенный платеж, по умолчанию берется из значения параметра настроек варианта оплаты,
//но возможно выставлять и вручную
$business->cmsSendOrder($id, $cmsId, $payment, $status, $to_name, $to_phone, $to_email, $payment_price = null);
```
11. Редактирование заказа
-------------------------
Для реализации функционала редактирования заказа в административной панели CMS необходимо
переопределить методы getAdminProductCart и getAdminDiscount в адаптере для получения корзины
уже из административной панели CMS. Встраивание формы редактирования пункта доставки аналогично
встраиванию модуля выбора доставки, с разницей в js параметрах.
params{
url: 'ajax.php?action=edit',
width: 550,
height: 440,
}
DDeliveryModule.init(params, callbacks, 'ddelivery_container_place');
Что может пригодится
--------------------------
Можно сохранять дополнительные параметры для настроек и использовать в контексте работы модуля,
главное настроить поля в getCustomSettingsFields дочернего класа Adapter. Эти поля будут
показыватся в ПАМ, в разделе "Настройки CMS"
После нажатия кнопки Сохранить в ПАМ, на стороне CMS будет доступен метод
```
$adapter = new IntegratorAdapter();
$container = new Container(array('adapter' => $adapter));
$container->getSettingStorage()->getParam('param_name');
```
Создание модуля посредством API
================================
Раздел в процессе разработки