ddelivery/clientsdk

SDK for quick creation DDelivery client integration

Client SDK DDelivery

Client SDK - SDK для быстрой разработки клиентских решений для сервиса доставки DDelivery., _(*1)

ПАМ(панель администрирования модулей) - ресурс который организовует работу модуля и взаимодействует с Client SDK и сервисом доставки DDelivery. Client SDK привязывается к ПАМ посредством АПИ ключа, полученном в личном кабинете cabinet.ddelivery.ru. В дальнейшем в ПАМ можно настроить гибкие правила доставки модуля., _(*2)

SDK ID - индентификатор, получаемый при оформлении доставки через модуль., _(*3)

DDelivery ID - идентификатор, получаемый при оформлении заявки на доставку сервиса., _(*4)

Адаптер - класс который организовует выдачу необходимой информации от CMS. От него нужно наследовать свой класс. (для php приложений)., _(*5)

Для разработки решений для систем не использующих PHP, смотрите раздел этой инструкции "Создание модуля через API", а также пункт "5. Вывод модуля доставки на странице оформления доставки", _(*6)

Структура директорий

  application/        Исходники сдк
  example/            Пример создания расширения

Создание интеграции

Client SDK содержит все механизмы для работы модуля, необходимо выполнить несколько этапов:, _(*7)

1. Запустить рабочий пример в каталоге example/ ., _(*8)

2. Переопределить методы родительского класса Adapter(пример IntegratorAdapter.php), _(*9)

3. Учитывая особенность CMS, определить точку входа в модуль, подключить нужные системные скрипты для CMS и вызвать все необходимые методы для работы Client SDK(пример example/ajax.php)., _(*10)

4. Создать локальное хранилище на стороне CMS вызвав метод initStorage класса Business (Далее продумать вызов этого метода при установке модуля в CMS), _(*11)

5. Привязать апи ключ магазина к ПАМ., _(*12)

6. Вывести способ доставки на странице оформления заказа CMS(пример index.php). Для этого к этой странице checkout необходимо подключить js файл и вызвать js метод с определенными параметрами и получить SDK ID. При выборе пункта доставки, организовать фильтрацию способов оплаты не поддерживающих наложенны платеж для пунктов доставки, которые его не поддерживают., _(*13)

7. При окончании оформления заказа (в момент когда цмс вставляет в БД заказ и выбран способ оплаты клиентом) необходимо вызвать метод onCmsOrderFinish класса Business для привязки закза CMS и SDK ID., _(*14)

8. При сохранении заказа перепроверить валидность данных доставки через метод viewOrder класса Business используя SDK ID., _(*15)

9. При изменении статуса заказа или по какомуто другому событию вызвать метод для отправки заказа (onCmsChangeStatus или cmsSendOrder соответственно) класса Business., _(*16)

Запуск рабочего примера

Для запуска примера необходимо загрузить сдк в каталог в котором будет находится модуль. `````` example/IntegratorAdapter.php - класс в котором необходимо переопрелить указанные методы, является связующим звеном между Client SDK и CMS. example/ajax.php - файл который является точкой входа в CMS и запускает на выполнение Client SDK. example/index.php - пример кнопки для открытия модуля на странице оформления заказа. example/delivery.php - пример отправки заказа, и вызова дополнительных методов. example/db.sqlite - хранилище которое использует Client SDK, _(*17)

Запустите файл index.php в директории example/, для запуска примера достаточно использовать тестовый апи ключ.
Из коробки пример работы модуля должен запустится корректно, в дальнейшем при разработке
интеграции рекомендуется руководствоватся примером из example/


1. Переопределить методы родительского  класса Adapter
-------------------------------------------------------
В первую очередь необходимо унаследовать переопределить абстрактные методы, при необходимости можно  переопределить
родительские.
Для начала работы необходимо получить апи ключ на сайте cabinet.ddelivery.ru


Привязка к ПАМ происходит при первом вхождении
через точку входа по ссылке ajax.php?action=admin, при этом происходит проверка
наличия прав администратора CMS и переход в ПАМ где можно проводить гибкую настройку правил доставки

Получить апи ключ из настроек

public function getApiKey(){ return 'api_key'; }, _(*18)

Проверка пользователя на наличие прав администратора CMS

public function isAdmin(){ if($_SESSION['admin'] == 1){ return true; } return false; }, _(*19)

Название CMS

public function getCmsName(){ return "Joomla"; return "Bitrix"; ... }, _(*20)

Версия CMS

public function getCmsVersion(){ return '1.1'; }, _(*21)

Получить содержание корзины. В зависимости от того  где 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( ... ); ); }, _(*22)

Получить скидку для клиента, для того чтобы отнять ее от общей стоимости заказа

public function getDiscount(){ return 50; }, _(*23)

Client SDK предусматривает автоматическую синхронизацию статусов магазина со статусами
DDelivery.ru
При синхронизации статусов заказов необходимо произвести UPDATE полей статуса заказа
в БД заказов. Синхронизация будет проводится 2 раза в сутки

В качестве аргумента передается массив $order

array( 'id' => 'status', 'id2' => 'status2', );, _(*24)

, где '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" } }, _(*25)

Получить поля заказа из CMS по идентификатору
Значения ключей:

'city' => город назначения,
'payment' => тип оплаты,
'status' => статус заказа,
'sum' => сумма заказа,
'delivery' => стоимость доставки

public function getOrder($id){ return array( 'city' => 'Урюпинск', 'payment' => 22, 'status' => 'Статус', 'sum' => 2200, 'delivery' => 220, ); }, _(*26)

Получить поля списка заказов за период 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, ) ); }, _(*27)

Получить список полей пользователя в виде массива с предопределенным ключом
Необходимо это для того чтобы при окончании оформления заказа в модуле поля заполнялись автоматически

Если это зарегистрированный пользователь то возможно 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' ); }, _(*28)

Получить список статусов заказов из CMS - в дальнейшем они
атоматически подтягиваются в ПАМ  и можно настраивать соответствие  статусов в разделе Настройки CMS

public function getCmsOrderStatusList(){ return array('10' => 'Завершен', '11' => 'Куплен'); }, _(*29)

Получить список способов опланы для настройки  в ПАМ, для выбора  способа оплаты соответствующему
наложенному платежу (раздел Настройки CMS в ПАМ)

public function getCmsPaymentList(){ return array('14' => 'Наличными', '17' => 'Карточкой'); }, _(*30)

Есть возможность добавлять свои кастомные поля и далее в ПАМ сохранять значения
и потом получать значения локально
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 ) ); }, _(*31)

Получить настройки БД

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));, _(*32)

Например точку входа в Client SDK можно получить, вызвав метод render,
$_REQUEST - массив с GET и POST параметрами запроса

$container->getUi()->render($_REQUEST);, _(*33)

С помощью контейнера можно  получать и другие объекты при необходимости
например чтобы выполнить этап 3 или 4, необходимо получить объект Business из контейнера, для этого
создаем контейнер и вызываем соответствующий метод.

$adapter = new IntegratorAdapter(); $container = new Container(array('adapter' => $adapter)); $business = $container->getBusiness();, _(*34)

Если неоходима более гибкаая настройка объектов или хранилищ, есть возможность
самостоятельно переопределить Container и сконфигурировать все объекты 
согласно интерфейсов,  ClientSDK будет работать с ними

3.Создание хранилищ
--------------------
Для работы модуля на стороне CMS необходимо создать хранилища.
Для начала необходимо сконфигурировать в адаптере настройки БД и вызвать метод
initStorage() класса Business, возпользовавшись контейнером:

$adapter = new IntegratorAdapter(); $container = new Container(array('adapter' => $adapter)); $business = $container->getBusiness();, _(*35)

// Создаем хранилища $business->initStorage();, _(*36)

4.Привязка апи ключа магазина с центральной административной панелью (CAP)
------------------------------------------------------------------------
Для того чтобы осуществить привязку необходимо перейти по ссылке(при условии что привязки
по этому апи ключу ранее не было), у которой url http://точка входа/ajax.php?action=admin .
Например http://site/ddelivery/ajax.php?action=admin
Если привязка по АПИ ключу была проведена, нужно осуществить сброс привязки -
через личный кабинет cabinet.ddelivery.ru


5. Вывод модуля доставки на странице оформления доставки
--------------------------------------------------------
Для этого на страницу оформления заказа нужно подключить скрипт

, _(*37)

Вставить элемент в котором инициализируется модуль

, _(*38)

После подключения будет в 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');, _(*39)

это позволит получать результат оформления доставки и обрабатывать его

При окончании оформления доставки во время вызова метода 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 - Почта, _(*40)

Важно  средствами 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), _(*41)

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), _(*42)

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);, _(*43)

при этом метод сравнит значение $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);, _(*44)

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'); ```, _(*45)

Создание модуля посредством API

Раздел в процессе разработки, _(*46)