retailCRM Документация

Интеграция InSales c системой

Интеграцию интернет-магазина на InSales с системой можно произвести с помощью приложения интеграции. При установке приложение и выставления параметров в настройках интеграции, автоматически загрузит существующие заказы в систему.

После установки приложение будет:

Регистрация интернет-магазина в системе

Перед установкой зарегистрируйте Ваш интернет-магазин в Вашем экземпляре системы (раздел Администрирование > Магазины, например, в демо-версии):

Далее сгенерируйте API-ключ в разделе Администрирование > Интеграция > Ключи API, для взаимодействия системы и InSales, и привяжите к нему созданный магазин:

Важно!!! Тип доступа API ключа должен быть «Доступ к отдельным магазинам» и выбран только один магазин. Если у Вас к одному аккаунту системы подключено несколько магазинов, необходимо для каждого магазина создавать свой API-ключ. В противном случае заказы не будут выгружаться из InSales в систему.

Желательно созданный API ключ не использовать для других целей.

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

"/api/orders/create"
"/api/orders/upload"
"/api/orders/fix-external-ids"
"/api/orders/{externalId}"
"/api/orders/{externalId}/edit" 
"/api/orders/history"
"/api/orders/statuses"
"/api/orders/payments/create" (API v5)
"/api/orders/payments/{id}/edit" (API v5)
"/api/orders/payments/{id}/delete" (API v5)
"/api/customers/{externalId}"
"/api/customers/create"
"/api/customers/upload"
"/api/reference/delivery-types"
"/api/reference/delivery-types/{code}/edit"
"/api/reference/payment-types"
"/api/reference/payment-types/{code}/edit"
"/api/reference/statuses"
"/api/reference/payment-statuses"
"/api/reference/payment-statuses/{code}/edit"

Подробнее об управлении ключами читайте в разделе Создание и редактирование ключа.

Установка приложения в InSales

Настройки выгрузки заказов

Для выгрузки справочников (доставки и оплаты) из InSales можно активировать флаг “Выгрузить справочники из InSales” и после сохранения формы будет запущена выгрузка имеющихся справочников из Вашего магазина.

После сохранения данных системы Вам необходимо указать, каким образом будет генерироваться Ваш ICML-каталог для системы и настроить соответствия справочников двух систем. Варианты для генерации каталога, рассмотрены в главе Настройка выгрузки товаров ниже.

Настройка выгрузки товаров

Вариант 1. Генерация каталога с товарными предложениями

Если у Вас в каталоге присутствуют торговые предложения (несколько торговых предложений одного товара), то в настройках приложения следует отметить галочку «Выгружать ICML средствами приложения». Адрес файла каталога вы увидите сверху, его понадобится указать в качестве источника каталога в настройках магазина в систему.

Файл каталога сгенерируется в течение 3х часов.

Важно! Настройка «Выгружать ICML средствами приложения» влияет не только на генерацию каталога, но и на формирование заказов для отправки в систему или из системы в InSales. Не допускается установка флага «Выгружать ICML средствами приложения» и использование стороннего каталога, так как такие действия могут спровоцировать неправильную передачу товаров в заказах.

Настройка добавления xmlId в ICML для синхронизации с системой МойСклад

Важно! Если Вы указали получать данные из InSales - убедитесь, что в настройках интеграции InSales и МойСклад установлен флаг «Обновлять внешние идентификаторы». Это требуется для того, чтобы Внешние коды полученные из системы МойСклад были актуальные.

При установки флага «Дополнять каталог xmlId» обязательно выбрать один из вариантов описанных выше. Если этого не сделать - данные формы не сохранятся. И Вам высветиться сообщение с возникшей проблемой.

Также присутствует возможность указания домена для генерации ссылок на товары в ICML каталоге. Данный функционал необходим для указания ссылок на товары с определенным (указанным в настройках InSales) доменом в выгружаемом каталоге. Необходимость указания домена заключается в том, что при стандартном URL (напр. example.myinsales.ru) статистика к товарам не подгружалась.

Раздел «Валюты» служит для конвертации разных валют в одну. В данном разделе Вы выбираете валюту в системе для генерации каталога и источник получения курса обмена. Для выбора доступно два источника: Центральный банк РФ и система InSales. При выборе InSales - курс валют подгружается непосредственно из InSales, из раздела "Настройка валют на складе".

Вариант 2. Генерация каталога средствами InSales

Описанные ниже способы приведены для примера. Если у Вас возникли вопросы по настройки генерации каталога средствами InSales, то обратитесь в тех.поддержку InSales.

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

Простая генерация каталога без товарных предложений

Если у Вас в каталоге торговые предложения отсутствуют, перейдите в раздел «Продвижение -> Товарные площадки» вашего магазина. Нужно добавить новую выгрузку «Яндекс.Маркет - Упрощенное описание».

Введите необходимые названия и укажите категории, которые будут добавлены в каталог.

Необходимо указать кодировку файла — она должна быть utf-8.

Генерация каталога по шаблону с товарными предложениями

Если у Вас в каталоге присутствуют торговые предложения, но по какой-то причине генерируемый каталог приложением RetailCRM (интеграцией) Вас не устраивает, то Вы можете создать каталог по шаблону.

Перейдите в раздел Продвижение > Товарные площадки вашего магазина. Нужно добавить новую выгрузку «Яндекс.Маркет - Произвольная выгрузка».

Далее настраиваете данные магазина и указываете какие категории будут загружены в каталог.

Для выгрузки с товарными приложениями рассмотренными в этом примере необходимо активировать флаг “Выгружать модификации”. Кодировка каталога должна быть utf-8.

Далее необходимо добавить шаблон в поле “Шаблон блока offer”.

Один из вариантов такого шаблона указан ниже.

{% for variant in product.variants %}   
	<offer id="{{product.id}}-{{variant.id}}" productId="{{product.id}}" quantity="{{variant.quantity}}">
        	<url>{{account.url}}/product/{{product.handle}}</url>
    	<price>{{variant.price}}</price>
    	<productActivity>{% if product.available %}Y{% else %}N{% endif %}</productActivity>
    	<purchasePrice>{{variant.cost_price}}</purchasePrice>
    	{%for image in product.images limit: 1 %}
    	    	<picture>{{image.url}}</picture>
    	{% endfor %}
    	<name>{{product.title}} {{variant.title}}</name>
    	<productName>{{product.title}}</productName>
    	<param code="weight" name="Вес">{{variant.weight}}</param>
    	<param code="article" name="Артикул">{{variant.sku}}</param>
    	<param code="description" name="Описание">{{product.short_description}}</param>
	</offer>
{% endfor %}

При составлении шаблона не забудьте придерживаться формата указанного в http://help.retailcrm.ru/docs/Developers/ICML

Адрес файла выгрузки, полученный при создании одного из вариантов, также необходимо прописать в настройках системы, и установить галочку «Загрузить каталог из ICML сейчас».

Настройка соответствий справочников

При настройке соответствий оплат, доставок, пользовательских статусов и статусов оплат в настройках приложения в разделе Приложения > Установленные > RetailCRM есть некоторые ограничения:

Соответствие должно быть выставлено по правилу «один к одному» - это значит, что нельзя нескольким элементам в InSales назначить один элемент в системе.

Если на какой-то элемент не будет выставлено соответствие, то это поле не будет принимать участие в обмене. Так, добавив новый тип оплаты, и не выставив для него соответствующий тип оплаты в системе, этот тип оплаты не будет передаваться в заказе при интеграции.

Важно! Используемая версия API влияет на передачу данных. Для версии V4 описанные выше действия повлияют только на пустоту в поле тип оплаты, а вот для версии V5 это может привести к потере заказа. Подробнее в главе Версионность.

Пользовательские статусы

Для корректной синхронизации данных между двумя системами, необходимо настроить соответствия статусов InSales со статусами системы. В ином случае статусы будут передаваться «по умолчанию».

Работа со статусами заказов выполняется по принципу: если нет или не установлены соответствия пользовательских или стандартных статусов в настройках интеграции с InSales, то используются статусы «по умолчанию»:

Важно! Если вы для всех или некоторых статусов InSales не выставили соответствия статусов системы, убедитесь, что в системе присутствуют статусы с символьными кодами, которые описаны выше.

При этом, если не будет выставлено соответствие для пользовательского статуса, то в обмене будет участвовать системный статус, являющийся его родителем и будет использоваться соответствие статусов «по умолчанию», описанные выше.

Статусы оплаты

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

В InSales существует два стандартных статуса «Оплачен» и «Не оплачен». Если не выставлять этим статусам соответствия, то для синхронизации заказов будет использовано соответствия «по умолчанию»:

Статусы оплат для синхронизации по умолчанию создаются при выгрузке справочников из InSales.

Дополнительный статус «Бесплатно» используется только в интеграции InSales > Система. Он необходим чтобы была возможность передачи заказов с нулевой стоимостью из InSales. Так создание заказов с нулевой стоимостью в InSales есть, а в системе нет. Для синхронизации Система > InSales передача этого дополнительного статуса не будет.

Для того чтобы использовать этот статус, необходимо выбрать уже из имеющихся или создать новый статус оплаты с неактивным флагом “Оплата произведена ”. Для того чтобы система не фиксировала оплату заказа и имелась возможность работать с заказом в системе.

Важно! Если не выставлены соответствия типов доставок и оплат, прогрузка архивных заказов не произойдет и интеграция не начнется.

На этом настройка интеграции с InSales завершена.

Периодичность синхронизации данных между системами

После настройки интеграции происходит обмен заказами - заказы выгружаются в обе стороны:

Файл каталога запрашивается системой раз в 3-4 часа.

Если в заказе системы поменять какие-либо данные заказа, то временные диапазоны обновления заказов такие же как и загрузка заказов.

Важно! Если в созданном в системе заказе не выбраны товары, тип оплаты или тип доставки, этот заказ не придет в InSales. Это связано с ограничением API со стороны InSales.

Особенности работы с комплектами

В системе не реализована работа с комплектами как в InSales. Но подобный функционал доступен в интеграцию для улучшения синхронизации комплектов в заказе.

Если у Вас присутствуют комплекты, то изучите материал ниже, он поможет разобраться в новой механики синхронизации данных. Разработанная механика работы с комплектами доступна только если у вас используется генерация ICML с помощью приложения.

Генерация каталога

При генерации ICML к товару комплекта добавляются торговые предложения самого комплекта и его комплектующих. Рассмотрим пример offer, комплекта и одного из его элементов:

<offer id="77316983-132370576-77317134" productId="77317134" quantity="59">
<categoryId>6164923</categoryId>
<url>
http://shop-44447.myinsales.ru/product/ofisnoe-kreslo
</url>
<price>12588</price>
<purchasePrice>5000</purchasePrice>
<productActivity>Y</productActivity>
<picture>
https://static-eu.insales.ru/images/products/1/8052/116940660/Kak-vyibrat-udobnoe-kreslo-dlya-rukovoditelya.jpg
</picture>
<name>Офисное кресло (Комплект: мебель в офис)</name>
<productName>Офисное кресло</productName>
<param code="weight" name="Вес">4.0 кг</param>
<param code="article" name="Артикул">kr-002</param>
<unit code="pce" name="Штука" sym="шт"/>
</offer>
<offer id="77317134-132370830" productId="77317134" quantity="0">
<categoryId>6164923</categoryId>
<url>
http://shop-44447.myinsales.ru/product/mebel-v-ofis
</url>
<price>200000</price>
<purchasePrice>0</purchasePrice>
<productActivity>Y</productActivity>
<picture>
https://static-eu.insales.ru/images/products/1/8079/116940687/23b10de0f4966e53af467c641f56f150.jpg
</picture>
<name>(Комплект) мебель в офис</name>
<productName>(Комплект) мебель в офис</productName>
<param code="weight" name="Вес">19.0 кг</param>
<param code="article" name="Артикул">komplekt-002</param>
<unit code="pce" name="Штука" sym="шт"/>
</offer>

В каталоге, который сгенерирован нашим приложением, появились еще один тип составных id товарных предложений. Он состоит из идентификатора товара, идентификатора товарного предложения и идентификатора комплекта.

Комплекты в системе

Для того чтобы не было путаницы между простыми товарами и комплектными в генерацию ICML к комплектным товарам и их комплектующим были добавлены метки (Комплект) и (Комплект: { название комплекта }) соответственно.

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

Остаток для комплекта в системе является суммой остатка по всем элементам комплекта.

Цена для элемента комплекта может отличаться от той, которая будет в заказе. Так как в InSales, при автоматическом разбиении комплекта, товару присваивается собственная стоимость в зависимости от цены всего комплекта.

Синхронизация данных

Рассмотрим по направлениям синхронизации работу с комплектами в заказе.

Из InSales в систему

Комплектный товар из InSales поступает в систему разбитым на элементы комплекта, за одним только исключением. Товары, которые входят в состав комплекта, привязываются к товарным предложениям комплекта в системе.

На изображении выше показано 2 товарного предложения которые входят в состав комплекта «мебель в офис» и одного дополнительного офисного кресла. Все позиции заказа системы связаны с позициями заказа InSales и как можно заметить сумма элементов комплекта равна цене комплекта. Ниже показан указанный в заказе комплект «мебель в офис» в InSales.

Из системы в InSales

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

Состав комплектного товара:

Для примера создадим заказ в системе с комплектом «мебель в офис» и с отдельным товаром «Офисное кресло».

Состав заказа в системе до синхронизации данных с InSales выглядит следующим образом:

После синхронизации данного заказа с InSales получаем разбитый комплект на элементы и товар «Офисное кресло»:

Особенность синхронизации скидок

Важно понимать, что в InSales скидки хранятся несколько иначе, чем в системе:

Важно! Если в системе поменять эти поля вручную, то в InSales скидки перезапишутся, и в заказе появится по одной скидке на каждый тип в системе (одна скидка в рублевом расчете, и одна в процентном).

Скидки, выставленные в InSales:

Наценка на способ оплаты в заказе не передается в систему ввиду отсутствия её в системе.

Новый обработчик скидок (бета)

В интеграции с InSales присутствует механизм передачи скидок между системами. Для использования этого механизма необходимо в настройках интеграции выставить флаг «Использовать новый обработчик скидок (бета)».

Передача скидок из InSales

Глобальные изменения произошли именно в передаче скидок из-за того, что из InSales передается только валютная величина скидки на каждый товар, для которого распространяется та или иная скидка.

Причина, по которой пришлось прибегнуть к такому варианту заключается в следующем: механика расчета скидок в InSales и системы во многих аспектах различается. Например, валютная скидка для товара считается для всех единиц товара, а в системы для каждой единицы.

Приведем пример того, какие именно будут задействованы данные для отправки скидок в системе.

При передачи скидки в систему для товара «Офисное кресло» добавится скидка 377,64 руб. = 1132,92 руб. / 3 То есть скидки передаваемые в систему будут зависеть от единиц товара. На следующим скриншоте виден результат создания заказа с указанной скидкой.

Передача скидок из CRM

Рассмотрим добавление валютной скидки на весь заказ в CRM. Добавим к уже созданному заказу 1000 руб скидки и 1 товар «Кровать детская» с ценой 2000 руб.

Версия API v5

Как видим из скриншота, скидка в 1000 руб. распределилась по товарам.

Для товара «Офисное кресло» в итоге 677,64 руб. (вместе с распределенной скидкой) при переводе в InSales эта скидка будет равняться 2032,92 руб. = 677,64 руб. * 3.

Для товара «Кровать детская» распределенная скидка равна 100 руб. Так как у этого товара только одна единица, то и в InSales для этого товара присвоится скидка в 100 руб.

Вышеописанный пример передачи скидки из CRM в InSales были рассмотрены в CRM версией 6.7.4, собственно версия API v5

Версия API v4

Так как в v4 нет автоматического распределения скидки заказа по товарам, то валютная скидка в 1000 руб. на весь заказ так и создастся в InSales, но при обратной синхронизации (InSales -> CRM) все равно скидка распределиться по товарам по логике InSales и с учетом уже существующей скидки для товара «Офисное кресло».

Изменение единиц товара

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

Из системы поступил заказ, который показан на скриншоте выше, с одним товаром «Неактивный товар» количество которого равно 6 шт.

Так как в системе была выставлена скидка 30 руб. на каждую единицу товара, то в InSales скидка создалась в 180 руб. = 30 руб. * 6.

И теперь если мы изменим количество единиц товара до 5 шт., то скидка для товара не пересчитается, а останется так же 180 руб.

Автоматически нет возможности менять скидку после изменения количества товара. В InSales также не предусмотрен такой механизм, так как валютная скидка товара применяется к одной единице товара.

И вот что получилось в итоге в CRM после передачи изменений из InSales.

Как можно заметить сумма заказа одинаковая, но вместо валютной скидки в 30 руб. для товара, получилась скидка в 36 руб.

Важно! В связи с этим при изменении единиц товара в InSales, для которой применена валютная скидка, не забудьте изменить и саму скидку с расчетом на сколько единиц изменился этот товар. То есть в примере выше в InSales нужно изменить валютную скидку до 150 руб.

Процентные скидки на заказ

Механика расчета процентных скидок на весь заказ в системе и в InSales различается.

В системе рассчитывается сначала сумма по товарам с учетом скидок на товары, затем применяются скидки на заказ и добавляется стоимость доставки.

Например, на скриншоте ниже показан состав заказа в котором показан результат вышеуказанного механизма.

В InSales механика расчета суммы заказа с процентной скидкой на заказ отличается от механики системы. А именно, в InSales рассчитывается сумма по товарам, применяется процентная скидка на заказ, и потом уже применяются скидки на товары и прибавляется стоимость доставки.

Результат показан на скриншоте ниже.

Описанная ситуация более заметна в интеграции InSales и системы ниже 6 версии. Так как в 6 версии системы было добавлено распределение скидки по товарам и при синхронизации данных с InSales отправляются только валютные скидки на товары.

При добавлении процентной скидки на весь товар эту особенность стоит учитывать и по возможности не использовать. А если и использовать, то быть готовым к тому, что данные в InSales и в системе по скидкам будут различны.

Механика добавления валютной скидки на заказ в InSales и в системе не различается.

Кастомизация приложения

Передача пользовательских полей

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

Дополнительные настройки

Односторонняя интеграция

Появилась возможность сделать приложение одностороннем, например, если Вам требуется по какой-либо причине отключить передачу данных из InSales или из системы. То для этого потребуется обратиться в техподдержку системы.

Обновление номера

Если Вам требуется чтобы в системах была одинаковая номенклатура, то можно настроить передачу номера заказа при создании заказа в системе. Для этого потребуется обратиться в тех. поддержку системы и в обращении указать, что согласны на изменения номера системы номером InSales.

Важно! Перед тем как соглашаться на изменение номера, проверьте может быть у Вас при создании заказа в системе отправляется письмо или сообщение клиенту с номером заказа. Если номер заказа задействован для отправки уведомления клиенту, то не рекомендуется менять номер, так как при создании заказа в системе номер указывается по шаблону записанном в настройках, а номер изменяется уже после создания заказа в InSales. И клиенту при создании отправится один номер заказа (номер системы), а через некоторое время придет сообщение с другим номером заказа (номер InSales).

Конвертация стоимости

Если в InSales у Вас присутствуют товары с разными валютами в ценах и вы используете каталог, который генерируется средствами приложения, то можно конвертировать стоимость товаров в одну валюту, которая у Вас указана в настройках системы.

Для этого потребуется обратиться в техподдержку системы и сообщить что вы согласны на конвертацию валют для каталога.

Версионность

Интеграция предназначена для версии API V4 и выше. Распределение по версиям происходит автоматически. Вам не нужно устанавливать используемую версию API вручную.

Использование версии API retailCRM V4

Скидки

Работа со скидками для версии API V4 описана в главе «Особенность синхронизации скидок».

Использование версии API RetailCRM V5

Скидки

Из-за того что по отношению к предыдущей версии API изменилось получение скидок из системы, изменение заказа в двух системах приведет к переводу общей скидки на скидки на каждую позицию.

Причем при передачи скидок из InSales в систему возможно и передача скидок на весь заказ, но при обратной синхронизации (Система > InSales) будут скидки приведены к формату “скидка на каждый товар в заказе”.

Оплаты

Так как в версии API V5 появилась работа с мультиоплатами, а в InSales всего одна оплата в заказе, то и синхронизация оплат в заказе происходит “один-к-одному”. То есть если заказ создан в InSales то при создании этого заказа в системе заказу будет присвоена одна оплата и ей же будет присвоен внешний id оплаты такой же как и внешний id заказа. И в синхронизации заказов будет участвовать та оплата, которая привязана к заказу внешним id. Если же заказ создан был в системе или оплаты были удалены, то при первом появлении оплаты в заказе системы оплата заказа синхронизируется с оплатой в InSales.

Статус полной оплаты из системы в InSales передается только тогда, когда дата полной оплаты будет выставлена в заказе. То есть тогда, когда все оплаты в заказе будут с пометкой “Оплачен”.

Обращение в техподдержку

Важно!


Редакция от 30.10.2018 12:32