[syncMoySklad] - синхронизация с "Мой Склад"

[syncMoySklad] — пакет для синхронизации с сервисом «Мой Склад».
В отличии от уже имеющихся дополнений работает с JSON API. Функционал работы по api существенно отличается от функционала протокола CommerceML, а инициатором синхронизации выступает сайт.
На данный момент реализована лишь следующая часть функционала…

Что уже реализовано…

• Группа товаров — импорт/экспорт
  
• Товары — импорт/экспорт
  
• Услуги — импорт/экспорт
  
• Модификации — импорт/экспорт
  
• Остатки — импорт
  
• Валюты — импорт
  
• Метаданные (товара, модификации) — импорт
  

После установки пакета в админке появится кнопка синхронизации (на шаблонах указанных к настройке «Активные шаблоны»)


и вкладка синхронизации. Там ненужно ничего руками заполнять, эти данные заполняются автоматически. Их редактирование полезно/возможно для отладки и когда вы понимаете что делаете. Самостоятельно там ненужно ничего прописывать.
Если эти данные вас смущают можно отключить вкладку настройкой sync_show_sync_data.

Синхронизация — админка сайта
Для запуска синхронизации достаточно выбрать нужное действие, будет открыто окно с логированием процесса.
Можно остановить/запустить/перезапустить процесс синхронизации.



Синхронизация — крон
Для синхронизации под крон пример файла ("/cron/sync.php"). Необходимо указать

• service — сервис синхронизации
  


• action — процессор синхронизации
  
• sync_step — начальный шаг синхронизации
  

Создаем подобный файл и ставим на крон.

$corePath = $modx->getOption('sync_core_path', null,
	$modx->getOption('core_path', null, MODX_CORE_PATH) . 'components/sync/');
	/** @var Sync $Sync */
	$Sync = $modx->getService('sync');

	$params = array(
	'service'   => 'moysklad',
	'action'    => 'mgr/mscategory/sync',
	'sync_step' => 'sync_init',
	);

	$response = $Sync->curlExec($params);

Пользователь синхронизации (задается в настройках sync) должен существовать в админке сайта с необходимыми правами (обновление и создание ресурсов и т.п. ), иначе при запуске вы получите сообщение "Доступ запрещён!".

Класс синхронизации
Возможно самостоятельное добавление класса синхронизации. Достаточно создать настройку
имя_класса_actions, к примеру
moysklad_actions и перечислить доступные действия

Будет добавлен пункт синхронизации имя_класса и подменю в виде перечисленных действий. Под каждое действие должен сущестовать процессор в папке имя_класса компонента синхронизации.

{"mscategory":{"sync":"mscategory\/sync","import":"mscategory\/import","export":"mscategory\/export","stock":"mscategory\/stock"}}

Синхронизация — «Мой склад»
Базовый класс синхронизации с сервисом «Мой склад». На данный момент реализована синхронизация следующих сущностей.

• Группа товаров — импорт/экспорт
  
• Товары — импорт/экспорт
  
• Модификации — импорт/экспорт
  
• Остатки — импорт
  
• Валюты — импорт
  
• Метаданные (товара, модификации) — импорт
  

Можно выгрузить продукты сайта в сервис «Мой склад», можно загрузить продукты с сервиса «Мой склад» на сайт.
Инициатором синхронизации является сайт. Более подробно можно ознакомиться по ссылке МойСклад JSON API

Настройки синхронизация — «Мой склад»
Доступны в разделе «Системные настройки» -> «syncMoySklad» -> «Основные»

• sync_moysklad_actions — Доступные действия синхронизации.
  
• sync_moysklad_api_endpoint — Url для отправки запроса к МойСклад Api.
  
• sync_moysklad_api_user — Логин пользователя МойСклад.
  
• sync_moysklad_api_password — Пароль пользователя МойСклад.
  
• sync_moysklad_api_limit — Лимит обработки данных.
  
• sync_moysklad_sync_folder — Папка синхронизации. Название папки МойСклад.
  
• sync_moysklad_sync_parent — Категория синхронизации. Id категории сайта.
  
• sync_moysklad_currency — Валюта магазина.
  
• sync_moysklad_currency_rate — Тарифная ставка магазина.
  
• sync_moysklad_process_modification — Обрабатывать модификации.
  
• sync_moysklad_process_stock — Обрабатывать остатки.
  
• sync_moysklad_process_image — Обрабатывать изображения.
  

Доступны в разделе «Системные настройки» -> «syncMoySklad» -> «Категория»

• sync_moysklad_category_class_key — Класс категории.
  
• sync_moysklad_category_template — Шаблон категории.
  
• sync_moysklad_category_published — Статус категории.
  
• sync_moysklad_category_fields — Основные поля категории продукта, массив соответсвия полей.
  
• sync_moysklad_category_skip_fields_on_upd — Поля категории продукта исключаемые при обновлении.
  
• sync_moysklad_category_process_on_import_upd — Обрабатывать категории продукта при импорте и обновлении.
  
• sync_moysklad_category_process_on_import_cre — Обрабатывать категории продукта при импорте и создании.
  
• sync_moysklad_category_process_on_export_upd — Обрабатывать категории продукта при экспорте и обновлении.
  
• sync_moysklad_category_process_on_export_cre — Обрабатывать категории продукта при экспорте и создании.
  

Доступны в разделе «Системные настройки» -> «syncMoySklad» -> «Продукт»

• sync_moysklad_product_class_key — Класс продукта.
  
• sync_moysklad_product_template — Шаблон продукта.
  
• sync_moysklad_product_published — Статус продукта.
  
• sync_moysklad_product_fields — Основные поля продукта, массив соответсвия полей.
  
• sync_moysklad_product_skip_fields_on_upd — Поля продукта исключаемые при обновлении.
  
• sync_moysklad_product_attributes — Атрибуты продукта, массив соответсвия полей.
  
• sync_moysklad_product_price — Цены продукта, массив соответсвия полей.
  
• sync_moysklad_product_stock — Остатки продукта, массив соответсвия полей.
  
• sync_moysklad_product_process_on_import_upd — Обрабатывать продукты при импорте и обновлении.
  
• sync_moysklad_product_process_on_import_cre — Обрабатывать продукты при импорте и создании.
  
• sync_moysklad_product_process_on_export_upd — Обрабатывать продукты при экспорте и обновлении.
  
• sync_moysklad_product_process_on_export_cre — Обрабатывать продукты при экспорте и создании.
  
• sync_moysklad_product_process_attributes_on_import — Обрабатывать атрибуты продукты при импорте.
  
• sync_moysklad_product_process_attributes_on_export — Обрабатывать атрибуты продукты при экспорте.
  
• sync_moysklad_product_process_image_on_import_cre — Обрабатывать изображения при импорте и создании
  продукта.
  
• sync_moysklad_product_process_image_on_import_upd — Обрабатывать изображения при импорте и обновлении
  продукта.
  
• sync_moysklad_product_process_image_on_export_cre — Обрабатывать изображения при экспорте и создании
  продукта.
  
• sync_moysklad_product_process_image_on_export_upd — Обрабатывать изображения при экспорте и обновлении
  продукта.
  
• sync_moysklad_product_process_stock — Обрабатывать остатки продукта.
  

Доступны в разделе «Системные настройки» -> «syncMoySklad» -> «Модификация»

• sync_moysklad_modification_fields — Основные поля модификации, массив соответсвия полей.
  
• sync_moysklad_modification_characteristics — Характеристики модификации, массив соответсвия полей.
  
• sync_moysklad_modification_price — Цены модификации, массив соответсвия полей.
  
• sync_moysklad_modification_stock — Остатки модификации, массив соответсвия полей.
  
• sync_moysklad_modification_process_on_import — Обрабатывать модификации продукта при импорте.
  
• sync_moysklad_modification_process_on_export_upd — Обрабатывать модификации при экспорте и обновлении.
  
• sync_moysklad_modification_process_on_export_cre — Обрабатывать модификации при экспорте и создании.
  
• sync_moysklad_modification_process_char_on_export — Обрабатывать характеристики модификации при экспорте.
  
• sync_moysklad_modification_process_price_on_export — Обрабатывать цену модификации при экспорте.
  
• sync_moysklad_modification_process_stock — Обрабатывать остатки модификации при синхронизации.
  

Доступные действия

• sync — Полная синхронизации.
  
• import — Импорт.
  
• export — Экспорт.
  
• stock — Импорт остатков.
  

Полная синхронизации
Будет выполнена полная синхронизация с «Мой склад».

Импорт
Будет выполнен импорт с «Мой склад».

Экспорт
Будет выполнен экспорт в «Мой склад».

Импорт остатков
Будет выполнен импорт остатков с «Мой склад».

На данный момент api «Мой склад» не поддерживает выгрузку с указанием родителя. Поэтому при импорте всегда
будут выгружены полностью
все сущности импорта. Служба поддержки сообщила что работы по внедрению данного функционала ведутся. Как
только он будет доступен
— будет возможен выборочный импорт по родителю.
Экспорт же проходит с указанием текущей категории. Помните об этом при запуске синхронизации.

Первичная настройка
Необходимо задать логин и пароль пользователя «Мой склад»
moysklad_api_password
moysklad_api_user

Необходимо задать настройку moysklad_sync_folder — категорию синхронизации «Мой склад» и
moysklad_sync_parent — id категорию сайта.

К примеру мы хотим синхронизировать папку «Товары склада» в категорию сайта «Мой склад»




Поля категории
Настройка moysklad_category_fields — массив соответствия полей ресурса к полю сущности «Группа
товаров»

{"pagetitle":{"key":"name","type":"string"},"description":{"key":"description","type":"string"},"editedon":{"key":"updated","type":"datetime"}}

Поле «pagetitle» ресурса будет задано значение поля «name» сущности
Поле «description» ресурса будет задано значение поля «description» сущности

Поля продукта
Настройка moysklad_product_fields — массив соответствия полей продукта к полю сущности «Товар»

{"pagetitle":{"key":"name","type":"string"},"description":{"key":"description","type":"string"},"article":{"key":"article","type":"string"},"weight":{"key":"weight","type":"float"},"volume":{"key":"volume","type":"float"},"editedon":{"key":"updated","type":"datetime"}}

Поле «pagetitle» ресурса будет задано значение поля «name» сущности
Поле «description» ресурса будет задано значение поля «description» сущности
Поле «article» ресурса будет задано значение поля «article» сущности

Атрибуты продукта
Продукту или услуге можно добавить дополнительные поля, нажимаем на шестеренку и добавляем нужные поля


например добавим поле Размер


теперь нужно прописать соответствие поле МС к полю продукта на сайте. Пускай полю Размер будет соответствовать поле size продукта, тогда соответствие будет выглядеть так

"size":{"key":"Размер","type":"array"}

можно задать значение поля по умолчанию, для этого надо задать атрибут value

"size":{"key":"Размер","type":"array","value":"oneSize"}

Также можно задавать соответствия к опциям продукта, для этого ключ необходимо указать с префиксом
options-
Например ключ поля stock, в настройкам прописываем его как

options-stock

Также можно задавать соответствия к тв полям, для этого ключ необходимо указать в формате
tv3
Например нам нужна твшка с именем Остаток, смотрим идентификатор этого тв поля — 3 и в настройкам прописываем его как

tv3

Настройка moysklad_product_attributes — массив соответствия дополнительный полей продукта к полю
сущности «Атрибуты Товара»

{"introtext":{"key":"Описание товара","type":"string"},"color":{"key":"Цвет","type":"array"},"size":{"key":"Размер","type":"array"}}

Поле «introtext» ресурса будет задано значение поля «Описание товара» сущности
Поле «color» ресурса будет задано значение поля «Цвет» сущности. Дополнительно указываем тип поля
«array»
Поле «size» ресурса будет задано значение поля «Размер» сущности. Дополнительно указываем тип поля
«array»
Примечание: Возможна работа с дополнительными опциями продукта, необходимо добавить префикс
«options-имяОпции» (options-stock)
Возможна работа с ТВ полями, имя поля необходимо задать как «tvидентификаторТВ» (tv1)

Цена продукта
Настройка moysklad_product_price — массив соответствия цен продукта к полю
сущности «Цена товара»

{"price":{"key":"Цена продажи","type":"float","value":0},"old_price":{"key":"Цена старая","type":"float","value":0}}

Поле «price» ресурса будет задано значение поля «Цена продажи» сущности
Значение по умолчанию 0

Остатки продукта
Настройка moysklad_product_stock — массив соответствия остатков продукта к полю
сущности «Остаток»

{"options-stock":{"key":"stock","type":"float","value":0}}

Поле «options-stock» ресурса будет задано значение поля «stock» сущности
Значение по умолчанию 0.
Для minishop2 создаем опцию «stock», в нее и будет записываться остаток



Свои действия
Возможно добавление своих действий синхронизации. Для этого необходимо внести действие в настройку sync_moysklad_actions.
Рассмотрим добавление действия по импорту остатков продукта.

Настройка sync_moysklad_actions — sync,import,export,stock

Процессор stock. Указывает необходимые шаги синхронизации. Разрешаем опцию «process_stock» — обработки
остатков

require_once dirname(__FILE__) . '/sync.class.php';

	class modSyncMoySkladStockProcessor extends modSyncMoySkladSyncProcessor
	{
	/**
	* @var array
	*/
	protected $steps = array(
	"sync_init",

	"sync_read_stock",

	"sync_import_upd_stock",

	"sync_close",
	);

	public function initialize()
	{
	$initialize = parent::initialize();

	$this->setOption('process_stock', true);

	return $initialize;
	}

	}

	return 'modSyncMoySkladStockProcessor';

WebHook
Возможна обработка событий от «Мой склад». Необходимо задать соответсвующие webHook.
Расмотрим пример обработки события при удалении продукта.
Описаны базовые функции
Задаем WebHook

• getWebHook — Получить список сущесвующих хуков.
  
• setWebHook — Установить хук. Необходимо указать 'action' — действие и 'entityType' — сущность
  
• updWebHook — Обновить хук.
  
• delWebHook — Отключить хук.
  

Задаем WebHook

if (!$Sync->loadSyncTools("moysklad")) {
	die('loadSyncTools');
	}
	$Sync->SyncTools->setWebHook(array('action' => 'DELETE', 'entityType' => 'product'));

Создаем плагин в админке сайта на событие «syncOnSyncObjectProcess» и при получении события удаления
сущности продукта
будет помечать ресурс на удаление.

$syncService = 'moysklad';
	if (!$Sync->loadSyncTools($syncService)) {
	return;
	}

	/** @var xPDOObject $object */
	$object = $modx->getOption('object', $scriptProperties, null, true);
	if (
	!$object
	OR
	!$Sync->isSyncObject($object, $syncService)
	) {
	return;
	}

	$syncType = $object->get('sync_type');
	$syncAction = $object->get('sync_action');
	$classKey = $object->get('class_key');
	switch (true) {
	/* hook event */
	case $classKey == 'event' AND $syncType == 'product' AND $syncAction == 'update':
	break;
	case $classKey == 'event' AND $syncType == 'product' AND $syncAction == 'delete':
 	case $classKey == 'event' AND $syncType == 'service' AND $syncAction == 'delete':
	$Sync->SyncTools->processSyncResourceDeleted($object);
	break;
	case $classKey == 'event' AND $syncType == 'productfolder' AND $syncAction == 'delete':
	$Sync->SyncTools->processSyncResourceDeleted($object);
	break;
	}

Снять привязку
При синхронизации происходит связь объекта (ресурса) с сущностью синхронизации. Данные синхронизации доступны во вкладке синхронизации.
Возможно снять эту привязку, достаточно выполнить действие снять привязку — данные текущего объекта и всех вложенных будут очищены.
Полезно например когда вы выполнили синхронизацию, и сделали это допустим некорректно или еще что либо… и вам к примеру проще удалить сущность в сервисе Мой Склад и выполнить все заново, вот для этого и пригодится данное действие.

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

PS. Функционал описан кратко и возможностей конечно очень много. По мере возможностей постараюсь раскрыть тему шире.
Всем спасибо за внимание!

update (09.02.2017) .
— Пакет синхронизации разделен на [Sync] базовый пакет — основной функционал и [syncMoySklad] — класс и процессоры для работы с «Мой Склад»
— Добавлена работа с модификациями, адаптирован пакет [msOptionsPrice2]

update (04.03.2017).
— Добавлена работа с сущностью услуга — импорт/экспорт
— Добавлена работа различным кол-ом валют
— Добавлена работа со складами. Как следствие работа с остатками по складам.

"size":{"key":"Размер","type":"array"}

"popular":{"key":"Популярный","type":"boolean"},"new":{"key":"Новый","type":"boolean"},"favorite":{"key":"Распродажа","type":"boolean"}

"tv6":{"key":"На главной","type":"boolean"}

<?php
if ($modx->event->name=="OnDocFormSave"  && $resource->get('template') == "17")  
{
$pub = 0;
$q = $resource->get('id'); // Получаем id ресурса
$product = $modx->getObject('msProduct', $q); //id Товара msProduct
$stock = $product->get('stock.value');
$m = null;
$q = ['rid' => $resource->get('id')];
$res = $modx->getCollection('msopModification', $q);
    foreach ($res as $item) {
          //формируем массив из остатков всех модификаций этого товара
          $prod[] = ['count' => $item->get('count')];
        }
    //Проверяем есть ли у нас в наличии хоть одна из модификаций текущего товара
    $res = false;
    foreach ($prod as $a) {
        if ($a['count'] != 0) {
          $res = true;
          break;
        }
    }
if (isset($stock) || $res) {
   $pub = 1;
} 
$resource->set('published', $pub);
}

<?php

define('MODX_API_MODE', true);

$developmentConfig = dirname(dirname(dirname(dirname(dirname(dirname(__FILE__)))))) . '/core/config/config.inc.php';
$productionConfig = dirname(dirname(dirname(dirname(__FILE__)))) . '/config/config.inc.php';

if (file_exists($developmentConfig)) {
    /** @noinspection PhpIncludeInspection */
    require_once $developmentConfig;
} else {
    /** @noinspection PhpIncludeInspection */
    //require_once $productionConfig;
}
/** @noinspection PhpIncludeInspection */
require_once '/home/ert/public_html/index.php';

$modx->getService('error', 'error.modError');
$modx->setLogLevel(modX::LOG_LEVEL_ERROR);
$modx->setLogTarget('FILE');
$modx->error->message = null;

/** @var Sync $Sync */
$Sync = $modx->getService('sync', 'Sync',
    $modx->getOption('sync_core_path', null,
        $modx->getOption('core_path') . 'components/sync/') . 'model/sync/');
$corePath = $modx->getOption('sync_core_path', null, $modx->getOption('core_path') . 'components/sync/');
$modx->lexicon->load('sync:default');

$params = array(
    'service'   => 'moysklad',
    'action'    => 'mgr/mscategory/export',
    'sync_step' => 'sync_init',
);

$response = $Sync->curlExec($params);

//var_dump($response);