[modRetailCRM 2.0] - глобальное обновление

Представляю крупное обновление компонента для связи вашего сайта с RetailCRM — modRetailCRM 2.0.
Это одно большое изменение, так как компонент по сути написан с нуля. Это связано с тем, что разработчики RetailCRM сменили версию API и полностью переписали библиотеку, которая используется в компоненте.

Внимание!

Обновление с версии 1.x.x до версии 2.0 невозможно и скорее всего сломает ваши наработки, так как, компонент работает совсем по другому, за что приношу свои извинения.
Если вы использовали стандартный функционал, правильнее будет удалить старую версию, и заново настроить новую. Если вы использовали нестандартный функционал, работающий через API ядра — вам лучше проконсультироваться с автором компонента и программистом.

Что нового в modRetailCRM версии 2.0

1. Компонент переведен на с 4 на 5 версию API RetailCRM и использует обновленную библиотеку
2. В связи с новой библиотекой изменен вызов всех методов, используемых в старых версиях компонента
3. Полностью переписан плагин, отвечающий за передачу заказа из Minishop2 в RetailCRM. Код стал более чистым, гибким и быстрым
4. Исправлена куча багов
5. Плагин дополнен множеством функциональных возможностей, учтены пожелания всех обратившихся за техподдержкой пользователей

Что нового в обновленной версии API RetailCRM

Главное изменение — возможность создавать задачи, а не только заказы и клиентов.
Теперь вы можете создавать задачи прямо через сайт.
Например, популярная форма обратного звонка при добавлении обработчика создаст в CRM задачу Перезвонить клиенту по указанному номеру, присвоит исполнителя и назначит дату выполнения.
Пример кода смотрите ниже

Установка и первоначальная настройка

1. Компонент доступен для установки в репозитарии ModStore
2. После установки Вам нужно заполнить в системных настройках следующие поля:


3. Опционально, если вы хотите чтобы в CRM передавались способы оплаты и доставки вам нужно сходить в соответствующие разделы справочника RetailCRM, скопировать оттуда символьные коды способов доставки и оплаты


Эти символьные коды я предлагаю вставить в описание соответсвующих способов доставки и оплаты minishop2


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

После этого плагин по идее уже может передавать заказы в RetailCRM

Какие данные передаются в RetailCRM из корзины при оформлении заказа

1. Товары (Наименование, стоимость, количество товара, все используемые в заказе опции товара)
2. Имя, телефон, email клиента и его id по которому (в том числе) CRM умеет группировать заказы
3. Адрес, в его классическом оформлении (Индекс, Область, город, Улица, дом, квартира), а также любые другие поля сохраняемые в таблице адрес заказа.
4. Комментарий клиента
5. Способ и сумма доставки, способ оплаты (если вы указали соответствие справочников)

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

Также плагин при создании нового заказа создает и нового клиента в RetailCRM (если конечно такого клиента еще нет) — это осталось без изменений со старой версии компонента

Пример быстрого заказа

Все вышеописанное касается работы minishop2.
Если же вы хотите быстро создать заказ, минуя корзину, например посредством формы быстрого заказа
я предлагаю следующее решение.
Скорее всего вы используете форму работающую через связку formIt + ajaxForm. Клиент заполняет имя, email, телефон, вы получаете через скрытое поле адрес страницы или название продукта и заявка падает вам на почту.
Я написал хук для formIt, который одновременно с отправкой на почту заявки, создает заказ в RetailCRM (собственно это никак не привязано к отправке заказа на email и может работать отдельным решением)

Итак создаем сниппет RetailCRM_QuickOrder_Hook примерно следующего содержания

<?php
if (!$modx->getService('modretailcrm','modRetailCrm', MODX_CORE_PATH.'components/modretailcrm/model/modretailcrm/')) {  
    $modx->log(1, '[RetailCrm] - Not found class RetailCrm');
    return;
}

$pdo = $modx->getService('pdoFetch');

$site = $modx->getOption('modretailcrm_siteCode');
$apiKey = $modx->getOption('modretailcrm_apiKey');
$crmUrl = $modx->getOption('modretailcrm_url');

$modRetailCrm = new modRetailCrm($modx, $apiKey, $crmUrl, $site);

//Принимаю необходимый массив полей из формы
$allFormFields = $hook->getValues();
$order = array();
//Небольшая валидация по вкусу
foreach($allFormFields as $key => $field){
    if(empty($field)) continue;
    switch($key){
        case 'externalId':
        case 'quantity':
            $order[$key] = trim(filter_var($field, FILTER_VALIDATE_INT));
            break;
        case 'email':
            $order[$key] = trim(filter_var($field, FILTER_VALIDATE_EMAIL));
            break;
        case 'pageId':
            break;
        default:
            $order[$key] = trim(filter_var($field, FILTER_SANITIZE_STRING));
    }
    
}
//Отметка Требуется перезвонить
$order['call'] = 1;
$order['orderMethod'] = 'one-click';
$product = $pdo->getArray('msProduct', array("class_key" => 'msProduct', 'id' => $order['externalId']), 
    array("limit" => 1, "offset" => 0,
    'innerJoin' => array(
        'Data' => array(
            'class' => 'msProductData',
            'on' => 'msProduct.id = Data.id'
        )
    ),
    'select' => array(
        'msProduct' => '*',
        'Data' => '*'
    ),
    ));
$order['items'][] = array(
    'initialPrice' => $product['price'],
    'purchasePrice' => $product['price'],
    'productName' => $product['pagetitle'],
    'quantity' => $order['quantity'],
    'offer' => array('externalId' => $product['id'])
);
$response = $modRetailCrm->request->ordersCreate($order, $site);

Данный сниппет принимает несколько полей из формы быстрого заказа, и отправляет эти данные в CRM
Обязательные поля, которые должны быть в форме:

• firstName
• phone
• externalId — id товара

Необязательные поля, которые могут быть форме и передаются в CRM:

• lastName
• email
• quantity — кол-во товара
• customerComment — комментарий клиента

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

Создав сниппет, вы можете добавить его как хук к вызову ajaxForm

{'ajaxForm' | snippet : [
   'form' => '@INLINE
        <form>
            <input class="form-control" type="text" name="firstName" value="" placehoder="Имя">
            <input class="form-control" type="text" name="lastName" value="" placehoder="Фамилия">
            <input class="form-control" type="text" name="phone" value="" placehoder="Телефон">
            <input class="form-control" type="text" name="email" value="" placehoder="Email">
            <input class="form-control" type="text" name="quantity" value="1" placehoder="Количество товара">
            <textarea class="form-control" name="customerComment"></textarea>
            <button type="submit" class="button">Заказ в один клик</button>
            <input type="hidden" name="externalId" value="[[*id]]">
        </form>
   ',
    'hooks' => 'RetailCRM_QuickOrder_Hook',
    'validate' => 'firstName:required,phone:required,externalId:required',
    
]}

Данный пример легко переписать под собственные нужды и совсем не обязательно использовать для этого formIt. Вы можете немного адаптировать прием данных от клиента в свой собственный сниппет и дальше передавать их по назначению используя пример.

Создание задачи в RetailCRM

Ситуация аналогичная быстрому заказу.
Пишем сниппет RetailCRM_Callback_Hook, который будет являться хуком для formIt
Принимает данные из формы, и отправляем в CRM

<?php
if (!$modx->getService('modretailcrm','modRetailCrm', MODX_CORE_PATH.'components/modretailcrm/model/modretailcrm/')) {  
    $modx->log(1, '[RetailCrm] - Not found class RetailCrm');
    return;
}

$pdo = $modx->getService('pdoFetch');

$site = $modx->getOption('modretailcrm_siteCode');
$apiKey = $modx->getOption('modretailcrm_apiKey');
$crmUrl = $modx->getOption('modretailcrm_url');

$modRetailCrm = new modRetailCrm($modx, $apiKey, $crmUrl, $site);

//Принимаю необходимый массив полей из формы
$task = array();
$name = trim(filter_var($hook->getValue('name'), FILTER_SANITIZE_STRING));
$task['phone'] = trim(filter_var($hook->getValue('phone'), FILTER_SANITIZE_STRING));
$task['text'] = 'Требуется позвонить клиенту по имени '.$name;
$task['performerId'] = 5;
$response = $modRetailCrm->request->tasksCreate($task, $site);

В данном случае есть один нюанс, который важно понимать.
Если при создании заказа в CRM ответственное лицо назначать необязательно, то в задаче это важно.
Без указания ответственного — задача просто не создастся.
За это отвечает параметр performerId которому мы присваиваем Номер менеджера в системе CRM
Я указываю его прямо в сниппете, подразумевая что менеджер в системе один, вы можете указать его по своей логике.
Навскидку
1. Указать в вызове сниппета
2. Указать в скрытом поле в форме
3. Указать менеджера по расписанию или еще как то, в зависимости от дня недели, товара. страницы и т.п.

Полный перечень полей, которые можно передать для создания заказа можно посмотреть здесь

Кастомизация и индивидуальные решения

Ядро компонента довольно гибкое и имеет много возможностей, нужду в которых я на практике пока не встречал.
Но если в вашем магазине нужно передавать в CRM какие то нестандартные данные или передавать их нестандартным способом — все довольно легко настраивается, собственно не обязательно использовать minishop2 или вообще не обязательно иметь интернет-магазин. Вы можете управлять клиентами, задачами, расходами а также интегрировать сайт с различными службами доставок, телефонией, учетными системами вроде 1С и т.п.
Основа для всего этого заложена, а дальше требуются лишь умелые руки и немного фантазии.

Оплата

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

$response = $modRetailCrm->request->ordersCreate($orderData, $site);

$modx->log(1, '[modRetailCRM]  Order Response '.print_r($response, true));

$orderData['payments'][0]['type'] = $order['payment']['description'];

$orderData['items'][$key]['properties'][] = array('name' => 'Артикул', 'value' => '06512');

[21-Mar-2018 21:51:25 Europe/Moscow] PHP Fatal error:  Uncaught RetailCrm\Exception\CurlException: Couldn't resolve host 'tivoli-market.retailcrm.ru' in /web/core/components/modretailcrm/model/modretailcrm/retailcrm/api-client-php/lib/RetailCrm/Http/Client.php:123
Stack trace:
#0 /web/core/components/modretailcrm/model/modretailcrm/retailcrm/api-client-php/lib/RetailCrm/Methods/V4/Orders.php(92): RetailCrm\Http\Client->makeRequest('/orders/create', 'POST', Array)
#1 /web/core/cache/includes/elements/modplugin/22.include.cache.php(92): RetailCrm\Client\ApiVersion5->ordersCreate(Array, 'tivoli-market-r...')
#2 /web/core/model/modx/modscript.class.php(70): include('/web/core/cache...')
#3 /web/core/model/modx/modx.class.php(1609): modScript->process(NULL)
#4 /web/core/components/minishop2/model/minishop2/minishop2.class.php(987): modX->invokeEvent('msOnCreateOrder', Array)
#5 /web/core/components/minishop2/model/minishop2/msorderhandler.class.php(449): miniShop2->invokeEvent('msOnCreateOrder', Array)
#6 /web/core/components/minishop2/model/minishop2/minishop2.class. in /web/core/components/modretailcrm/model/modretailcrm/retailcrm/api-client-php/lib/RetailCrm/Http/Client.php on line 123

<?php
if (!$modx->getService('modretailcrm','modRetailCrm', MODX_CORE_PATH.'components/modretailcrm/model/modretailcrm/'));  
    $modx->log(1, '&#91;RetailCrm&#93; - Not found class RetailCrm');
    return;

$pdo = $modx->getService('pdoFetch');

$site = $modx->getOption('modretailcrm_siteCode');
$apiKey = $modx->getOption('modretailcrm_apiKey');
$crmUrl = $modx->getOption('modretailcrm_url');

$modRetailCrm = new modRetailCrm($modx, $apiKey, $crmUrl, $site);

//Принимаю необходимый массив полей из формы
$task = array();
$name = trim(filter_var($hook->getValue('name'), FILTER_SANITIZE_STRING));
$task&#91;'phone'&#93; = trim(filter_var($hook->getValue('phone'), FILTER_SANITIZE_STRING));
$task&#91;'text'&#93; = 'Требуется позвонить клиенту по имени '.$name;
$task&#91;'performerId'&#93; = 1;
$response = $modRetailCrm->request->tasksCreate($task, $site);

[2018-11-09 18:35:30] (ERROR @ public_html/core/cache/includes/elements/modsnippet/42.include.cache.php : 24) [modRetailCRM]  Task Responce RetailCrm\Response\ApiResponse Object
(
    [statusCode:protected] => 201
    [response:protected] => Array
        (
            [success] => 1
            [id] => 78
        )

)

(
    [statusCode:protected] => 400
    [response:protected] => Array
        (
            [success] => 
            [errorMsg] => Order already exists.
        )
)