RetailCRM

Настройка интеграции

1. В RetailСRM cоздайте API-ключ. Для этого откройте Настройки > Интеграция > Ключи доступа к API и нажмите на кнопку Добавить. Откроется страница «Новый ключ API». На этой странице:
   1. В поле Комментарий введите краткое описание интеграции, например «По городу».
   2. В поле Тип доступа выберите Доступ ко всем магазинам.
   3. В списке Разрешенные методы API установите все флажки.
   4. Нажмите на кнопку Сохранить.

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

2. Настройте интеграцию в личном кабинете клиента MeaSoft:
   1. Выберите пункт основного меню Интеграция, перейдите на вкладку Настройки интеграции и в списке «Все интеграции» в строке «RetailCRM» нажмите Добавить.
   2. В окне «Настройка интеграции RetailCRM» укажите название интеграции, домен RetailCRM, созданный выше API-ключ. При необходимости укажите значения других полей:
      • Чтобы в RetailCRM отображался статус платежа после доставки заказа, в поле Код статуса оплаты укажите символьный код статуса платежа RetailCRM. Чтобы увидеть символьный код платежа, в RetailCRM выберите Настройки > Справочники > Статусы оплат. Статус платежа передается, если на момент закрытия заказа оставалась только одна сумма к оплате.
      • Чтобы в RetailCRM передавались статусы заказа из MeaSoft, в поле Получать статусы доставки выберите Получать. Настройки передачи статусов для RetailCRM см. в разделе «Передача статусов из MeaSoft».
      • Чтобы получать тип и сумму оплаты из MeaSoft, в поле Получать тип и сумму оплаты выберите значение Получать. Если тип оплаты, указанный в заказе, не совпадает с типом оплаты в MeaSoft и цена заказа не равна нулю, платеж в RetailCRM удаляется, создается новый платеж с суммой и типом оплаты из MeaSoft.

   По завершении настройки нажмите Сохранить.

3. Настройте интеграцию в RetailCRM:
   1. Откройте Настройки > Справочники > Типы доставок и на странице «Типы доставок» нажмите на кнопку Добавить. Откроется окно «Новая доставка»:
      
   2. В этом окне заполните обязательные поля и в выпадающем списке Интегрировать с выберите значение Курьерская служба 2008.
   3. Нажмите Сохранить.

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

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

Передача наложенного платежа

Чтобы настроить корректную передачу наложенного платежа:

1. Откройте Настройки > Интеграция и выберите модуль MEASOFT.
2. На странице «Настройки интеграции с Курьерская служба 2008» перейдите на вкладку Доставка и на панели справа выберите пункт Способы оплаты.
3. Установите флажки для способов оплаты, которые могут использоваться для передачи наложенного платежа, и нажмите Сохранить .
   

Передача статусов из MeaSoft

Чтобы получать статусы заказа из MeaSoft:

1. Откройте Настройки > Интеграция и выберите модуль MEASOFT.
2. На странице «Настройки интеграции с Курьерская служба 2008» перейдите на вкладку Доставка и на панели справа выберите пункт Статусы.
3. Настройте сопоставление статусов MeaSoft и RetailCRM. Для этого в столбце «Статус в RetailCRM» из выпадающего списка выберите соответствие для каждого статуса службы доставки.
   
4. Нажмите на кнопку Сохранить.

Статус из MeaSoft в RetailCRM передается 1 раз в 30 минут. Поэтому некоторые промежуточные статусы для заказа могут быть пропущены, и будет показан последний выставленный на момент синхронизации статус заказа.

Проверка интеграции

Чтобы проверить настройки интеграции:

1. Перейдите в форму создания заказа и убедитесь, что в списке Тип доставки появилось соответствующее значение:
   
2. Нажмите Выбрать тариф. Тарифы должны передаваться из настроек курьерской службы:
   
   
   В случае ошибки обратитесь в курьерскую службу для настройки тарифов. Проверить тарифы можно в ЛК MeaSoft в разделе Калькулятор.

Печатные формы

Чтобы в RetailCRM формировать печатные формы, аналогичные формам в Личном кабинете MeaSoft, используйте один из следующих способов:

• в сохраненном заказе на панели действий сверху нажмите Печать и выберите нужную печатную форму «Курьерская служба»;
• в списке заказов отметьте заказы флажками, внизу страницы нажмите Действия > Распечатать документы и выберите печатную форму «Курьерская служба».

Настройка триггеров

Триггер

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

Пример: каждый месяц 1-го числа списывается абонентская плата за интернет. Триггер «1-ый день месяца» — это событие, при наступлении которого срабатывает процедура «списание абонентской платы».

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

Для RetailCRM предусмотрены следующие триггеры:

• «Отправка заказа в MeaSoft» — при наступлении события «Смена статуса заказа на "Отправлен в MeaSoft"». При установке статуса, означающего, что заказ отправлен в курьерскую службу, срабатывает триггер, и заказ передается в MeaSoft;
• «Отмена заказа в MeaSoft» — при наступлении события «Смена типа доставки у заказа». При изменении типа доставки с доставки MeaSoft на доставку, например, Почтой России, заказ в MeaSoft отменяется, если он туда передан и имеет статус «Новый» или «Ожидает синхронизации»;
• «Изменения заказа в MeaSoft» — при наступлении события «Изменение заказа в RetailCRM». При изменении заказа в RetailCRM новые данные отправляются в MeSoft, если заказ передан и имеет статус «Новый» или «Ожидает синхронизации».

Примечание. Триггеры отправки и обновления данных заказа не учитывают типы оплат для наложенного платежа (Настройки > Интеграция > Маркетплейс > Доставки). Поэтому если наложенный платеж для неоплаченного заказа равен нулю (например, при оплате на сайте), триггер все равно передаст сумму к оплате.

Для корректной отправки таких заказов не используйте триггеры.

Передача заказа при смене статуса

Чтобы настроить триггер:

1. Cоздайте пользовательский статус заказа, при установке которого заказ будет автоматически передаваться в курьерскую службу. Можно создать любое количество статусов.
   1. В RetailCRM выберите Настройки > Статусы и нажмите на кнопку Добавить. Откроется окно «Новый статус»:
      
   2. Заполните поля формы. В поле Символьный код используйте только цифры и латинские буквы без пробелов. Запишите созданный символьный код, он понадобится на следующих шагах.
2. Выберите Настройки > Справочники > Типы доставок. Запишите символьные коды доставок, которые будут использоваться в триггере. В примере ниже используются коды outcity и incity.
   
3. Откройте Настройки > Триггеры и нажмите на кнопку + Триггер. Откроется окно «Новый триггер».

   Заполните поля:

   Название. Название триггера, например «Отправка заказа в MeaSoft».

   В разделе Событие нажмите на кнопку + Событие, выберите значение Изменение заказа и нажмите на кнопку Добавить.

   В разделе Условие установите переключатель Редактор и добавьте следующий скрипт:

   order.getStatus().getCode() in ["SentMeaSoft"] and order.getDeliveryType().getCode() in ["outcity","incity"]
   

   где

   • SentMeaSoft — символьный код статуса заказа. Если нужно указать 2 статуса, напишите их через запятую в виде: ["SentMeaSoft","SentMeaSoft_2"] вместо ["SentMeaSoft"];
   • outcity, incity — символьные коды типа доставки. Если нужно указать 1 тип доставки, напишите его в виде ["incity"] вместо ["outcity","incity"].
4. В разделе Действие нажмите на кнопку + Действие, выберите Выполнить HTTP-запрос. Появятся дополнительные поля настроек. Заполните их следующим образом:
   • Адрес — https://home.courierexe.ru/reintegrations/requests/trigger/retailcrm;
   • HTTP метод — POST;
   • Передавать параметры — В теле запроса (urlencode);
5. Нажмите на кнопку Добавить параметр 3 раза подряд и заполните появившиеся поля следующими данными:

Параметр	Значение
id	{{ order.getNumber() }}
sum	{{ order.getIntegrationDeliveryData().getDeclaredSum() }}
key	{{ order.getIntegrationDeliveryData().getExtraData().deliveryApiKey }}

Примечание. Переносы строк не допускаются.

6. В панели Действия нажмите Сохранить, затем сохраните триггер.

Триггер настроен.

Отмена заказа при смене типа доставки

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

Возможность отмены заказа есть только у курьерских служб с тарифом «Премиум» или «Максимум». По умолчанию она выключена, ее нужно включить в личном кабинете курьерской службы: Управление ЛК > Параметры > Расширенные > Разрешить отмену и изменение заказов.

При отмене заказа поле Инфо о доставке получает значение Отменено заказчиком, поле Дата доставки заполняется текущей датой, а в поле Вручил курьер появляется системная запись Отмена.

Чтобы настроить триггер:

1. В RetailCRM выберите Настройки > Справочники > Типы доставок.
   

   Запишите символьный код типа доставки (доставок), заказы которой отправляются в MeaSoft.

2. Перейдите в раздел Продажи и нажмите на кнопку Новый заказ. В разделе Доставка выберите тип доставки, заказы которой отправляются в MeaSoft, укажите город, вес и тариф.
3. В разделе Доставка появится поле API ключ службы доставки. Запишите его значение. В результате у вас есть пара «символьный код типа доставки» — «API ключ службы доставки».
4. Повторите действия пп. 2-3 для каждой доставки, заказы по которой отправляются в MeaSoft.
5. Откройте Настройки > Триггеры и нажмите на кнопку + Триггер. Откроется окно «Новый триггер».

   Заполните поля:

   • Название. Название триггера, например «Отмена заказа в MeaSoft»;
   • В разделе Событие нажмите на кнопку + Событие, выберите значение Изменение заказа и нажмите на кнопку Добавить.
   • В разделе Условие установите переключатель Редактор и добавьте следующий скрипт:

   changeSet.hasChangedField("delivery_type") and changeSet.getOldValue("delivery_type").getCode() in ["outcity","incity"]
   

   где outcity, incity — символьные коды типа доставки. Если нужно указать один тип доставки, напишите его в виде ["incity"] вместо ["outcity","incity"].

6. В разделе Действие нажмите на кнопку + Действие, выберите Выполнить HTTP-запрос. Появятся дополнительные поля настроек. Заполните их следующим образом:
   • Адрес — https://home.courierexe.ru/reintegrations/requests/cancel/retailcrm;
   • HTTP метод — POST;
   • Передавать параметры — В теле запроса (urlencode);
7. Нажмите на кнопку Добавить параметр 2 раза подряд и потом еще столько раз, сколько у вас сопоставленных пар «символьный код типа доставки» - «API ключ службы доставки». Заполните появившиеся поля следующими данными:

Параметр	Значение
id	{{ order.getNumber() }}
sum	{{ order.getIntegrationDeliveryData().getDeclaredSum() }}
Cимвольный код типа доставки 1	API-ключ службы доставки 1
Cимвольный код типа доставки 2	API-ключ службы доставки 2

Примечание. Переносы строк не допускаются.

8. В панели Действия нажмите Сохранить, затем сохраните триггер.

Триггер настроен.

Передача изменений заказа

Изменять заказ могут только курьерские службы с тарифом «Премиум» или «Максимум». По умолчанию опция выключена, ее нужно включить в личном кабинете курьерской службы: Управление ЛК > Параметры > Расширенные > Разрешить отмену и изменение заказов.

Чтобы настроить триггер:

1. В RetailCRM выберите Настройки > Справочники > Типы доставок.
   

   Запишите символьный код доставки (доставок), заказы которой отправляются в MeaSoft.

2. Откройте Настройки > Триггеры и нажмите на кнопку + Триггер. Откроется окно «Новый триггер».

   Заполните поля:

   • Название. Название триггера, например «Передача изменений заказа в MeaSoft»;
   • В разделе Событие нажмите на кнопку + Событие, выберите значение Изменение заказа и нажмите на кнопку Добавить.
   • В разделе Условие установите переключатель Редактор и добавьте следующий скрипт:

   changeSet.isUpdate() and 
   (
   changeSet.hasChangedField("first_name") or 
   changeSet.hasChangedField("last_name") or 
   changeSet.hasChangedField("patronymic") or 
   changeSet.hasChangedField("phone") or 
   changeSet.hasChangedField("site") or 
   changeSet.hasChangedField("additional_phone") or
   changeSet.hasChangedField("email") or 
   changeSet.hasChangedField("customer.phones") or 
   changeSet.hasChangedField("order_product") or 
   changeSet.hasChangedField("total_summ") or 
   changeSet.hasChangedField("delivery_date") or 
   changeSet.hasChangedField("delivery_time") or 
   changeSet.hasChangedField("payments") or 
   changeSet.hasChangedField("prepay_sum") or 
   changeSet.hasChangedField("weight") or 
   changeSet.hasChangedField("length") or 
   changeSet.hasChangedField("width") or 
   changeSet.hasChangedField("height")  or 
   changeSet.hasChangedField("payments.id")  or 
   changeSet.hasChangedField("payments.status")  or 
   changeSet.hasChangedField("payments.type")  or 
   changeSet.hasChangedField("payments.external_id")  or 
   changeSet.hasChangedField("payments.amount")  or 
   changeSet.hasChangedField("payments.paid_at")  or 
   changeSet.hasChangedField("payments.comment")  or 
   changeSet.hasChangedField("discount_manual_amount")  or 
   changeSet.hasChangedField("discount_manual_percent") 
   )
   and 
   order.getDeliveryType().getCode() in ["outcity","incity"]
   

   где outcity, incity — символьные коды типа доставки. Если нужно указать один тип доставки, напишите его в виде ["incity"] вместо ["outcity","incity"].

3. В разделе Действие нажмите на кнопку + Действие, выберите Выполнить HTTP-запрос. Появятся дополнительные поля настроек. Заполните их следующим образом:
   • Адрес — https://home.courierexe.ru/reintegrations/requests/update/retailcrm;
   • HTTP метод — POST;
   • Передавать параметры — В теле запроса (urlencode);
4. Нажмите на кнопку Добавить параметр 3 раза подряд и заполните появившиеся поля следующими данными:

Параметр	Значение
id	{{ order.getNumber() }}
sum	{{ order.getIntegrationDeliveryData().getDeclaredSum() }}
key	{{ order.getIntegrationDeliveryData().getExtraData().deliveryApiKey }}

Примечание. Переносы строк не допускаются.

5. В панели Действия нажмите Сохранить, затем сохраните триггер.

Триггер настроен.

Проверка работоспособности интеграции

1. Убедитесь, что выполнены все шаги инструкции по настройке интеграции.
2. Если используются триггеры, убедитесь, что они настроены согласно инструкции.
3. Создайте заказ, заполните требуемые данные.
4. Нажмите на кнопку Сохранить внизу страницы, флажок Не отправлять данные в службу доставки должен быть снят.
   Заказ должен отправиться в курьерскую службу. Если заказ отправлен без ошибок и отображается в ЛК, значит интеграция настроена.
5. Если возникает ошибка, ее текст отображается наверху страницы.

Если это ошибка заполнения формы, исправьте внесенные данные и попробуйте отправить заказ снова. Пример ошибки: «Ошибка сервиса доставки "Курьерская служба 2008": field [receiver phone] has no valid phone number».

Если это ошибка ответа курьерской службы, сообщите об этом разработчику. Пример ошибки: «Служба доставки прислала ответ в неверном формате».

Текст ошибки можно увидеть через отладку в личном кабинете. Чтобы найти свой заказ в запросах, нажмите CTRL+F и введите в строку поиска номер заказа или ориентируйтесь на время создания заказа.