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

Размещение модуля в Маркетплейс

Вводные положения

Вы можете разработать собственный модуль для retailCRM и разместить его в Маркетплейсе retailCRM. Модуль может быть как бесплатным, так и платным. Перед размещением модуля вам требуется зарегистрироваться как партнер retailCRM и заключить договор. Для этого обратитесь к нам через форму на сайте.

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

Разработка модуля

Ваш модуль может выполнять все функции, которые доступны в API. В справочнике методов приведен полный перечень API-методов. Для работы с API требуется создать API-ключ. Вы должны понимать, какие API-методы понадобятся для работы модуля. В дальнейшем в инструкции по включению модуля вам потребуется указывать, какие API-методы должен разрешить пользователь для API-ключа, который предоставляется вашему модулю. При активации модуля методом GET /api/credentials вы можете проверить, все ли необходимые методы разрешены пользователем.

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

Основные требования к модулям

  1. Модуль должен расширять пользовательский функционал retailCRM и нести очевидную ценность продукту. Решения, дублирующие стандартный функционал retailCRM, к публикации не допускаются. Также в публикации модуля может быть отказано, если его функционал находится в разработке у retailCRM.
  2. Интеграция подразумевает автоматический обмен данными между retailCRM и внешней системой. Простого вызова интерфейса внешнего сервиса из интерфейса retailCRM для публикации модуля недостаточно.
  3. Интеграция должна передавать данные в retailCRM из внешних сервисов. Чтобы клиент не переключался между окнами и админками различных сервисов.
  4. Описание модуля должно соответствовать функционалу. Название модуля должно быть емкое и не должно содержать элементов фирменного стиля retailCRM.
  5. Решение не должно запрашивать логин и пароль пользователя для авторизации в retailCRM. Для получения необходимых данных из аккаунта клиента необходимо использовать API ключ.
  6. Модулем должна быть предусмотрена обработка возможных возможных ошибок со стороны API. Сообщения об ошибках, которые выводятся пользователю, должны быть понятны и достаточно содержательны.
  7. Не должно быть ошибок в работе модуля.
  8. Модуль и его описание не должны содержать оскорбительную, непристойную информацию, призывы к насилию, порнографию, расизм, и прочие запрещенные законодательством РФ материалы.
  9. Рекомендуется предусматривать логирование запросов к API и ответов и хранить эти данные в течение месяца или хотя бы нескольких дней, для использования в случае решения проблем с интеграцией.
  10. Модуль может быть не допущен для публикации в маркетплейсе retailCRM без объяснения причин по решению модератора.

Активация модуля и взаимодействие с retailCRM

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


          Модуль                  Пользователь                 retailCRM
       ------------------------------------------------------------------
            |                           |                          |
1.          |                        Создание  ------------------> |
            |                       API-ключа                      |
            |                           |                          |
            |                           |                          |
2.          |                        Нажимает                      |
            |                   кнопку «Подключить» -------------> |
            |                    в карточке Модуля                 |
            |                     в Маркетплейсе                   |
            |                           |                    Перенаправление
3.          | <------------------------ | <---------------    Пользователя
            |                           |                  на форму настройки
            |                           |                  и включения Модуля   
4.          | <------------------ Заполняет форму                  |      
            |                           |                          |
5.   Проверка API-ключа,                |                          |
     прав для API-ключа  ----------------------------------------> |
       и API-версии                     |                          |
            |                           |                          |
6.   Регистрация Модуля                 |                          |
        в аккаунте     ------------------------------------------> |
        retailCRM                       |                          |
            |                           |                          |
7.    Перенаправление                   |                          |
       пользователя    ---------------> | -----------------------> |
        в аккаунт                       |                          |
        retailCRM                       |                          |
            |                           |                          |
       ------------------------------------------------------------------

Рассмотрим шаги данного процесса.

Шаг 1

Пользователь заходит в Маркетплейс и видит ваш модуль, например:

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

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

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

Шаг 2

Пользователь в карточке модуля нажимает кнопку Подключить.

Шаг 3

Система перенаправляет пользователя на форму настройки модуля. Адрес данной страницы задается при публикации модуля. При перенаправлении передается GET-параметр account, в котором передается адрес аккаунта retailCRM, где активируется модуль, например, http://some-service.ru/cabinet?account=https://some.retailcrm.ru.

Шаг 4

На странице настройки модуля пользователю, как правило, требуется ввести адрес его аккаунта (куда стоит подставлять значение из GET-параметра account, если он передан) и API-ключ, а также указать дополнительные настройки модуля.

Шаг 5

Пользователь отправляет форму с настройками. В этот момент модуль должен проверить:

  1. Есть ли доступ к API по указанному API-ключу. Для этого можно выполнить запрос GET /api/api-versions, заодно проверив, доступна ли версия API, с которой работает модуль.
  2. Проверить права, которые выданы API-ключу, с помощью метода GET /api/credentials. В случае нехватки прав, сообщить об этом пользователю.
  3. Проверить прочие настройки модуля.

Шаг 6

Далее модуль регистрирует себя в указанном аккаунте retailCRM. Регистрация производится с помощью метода POST /api/v5/integration-modules/{code}/edit. При регистрации указываются следующие данные:

Символьный код модуля integrationModule[integrationCode]

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

Символьный код экземпляра модуля integrationModule[code]

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

Если поддержка нескольких экземпляров в рамках одного аккаунта не предполагается, то данный параметр может совпадать с integrationModule[integrationCode].

Активность модуля integrationModule[active]

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

Уникальный хеш-ключ клиента integrationModule[clientId]

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

Базовый URL integrationModule[baseUrl]

Базовый URL, относительно которого будут строится адреса, куда аккаунт retailCRM выполняет запросы. Например https://some-service.ru/retailcrm/api.

Относительные пути конкретных методов integrationModule[actions][]

Необходимо задать относительный путь метода integrationModule[actions][activity], на который аккаунт retailCRM будет выполнять запрос при:

Формат данного колбека описан здесь POST {integrationModule["baseUrl"]}/{integrationModule["actions"]["activity"]}.

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

Адрес личного кабинета integrationModule[accountUrl]

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

Параметры отображения модуля до публикации в Маркетплейсе

Название модуля, логотип модуля и страны, в которых работает модуль задаются при публикации модуля, но для проверки их корректного применения на этапе разработки модуля вы можете передавать их при активации модуля в параметрах integrationModule[name], integrationModule[logo] и integrationModule[availableCountries]. После публикации модуля в Маркетплейсе данные параметры игнорируются.

Параметры для особых видов модуля

Для модулей типа Доставка, Телефония и Склад требуется передавать дополнительные настройки, которые необходимы для полноценной работы данных типов модулей. Подробнее о порядке разработки данных типов модулей написано в документации по каждому из типов модулей:

Особенности платных модулей

Если ваш модуль является платным и у него нет пробного периода, в момент активации модуля retailCRM пытается списать с баланса пользователя оплату за ближайший месяц использования модуля. Если оплату не удалось списать метод POST /api/v5/integration-modules/{code}/edit выдаст ошибку со HTTP-статусом 402. В этом случае нужно сообщить пользователю, что на его счету недостаточно средств для активации модуля и предложить вернуться в аккаунт retailCRM для пополнения баланса.

Шаг 7

Если активация модуля произведена успешно, то требуется перенаправить пользователя обратно в аккаунт retailCRM на страницу Маркетплейса.

Публикация модуля

Добавление нового модуля

Для размещения модуля вам требуется зарегистрироваться как партнер retailCRM и заключить договор. Для этого обратитесь к нам через форму на сайте. После регистрации вам на электронную почту придут доступы к личному кабинету партнера.

Модуль добавляется в разделе Модули.

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

Системные данные

Символьный код

В данном поле требуется указать уникальный символьный код вашего модуля, который может состоять из латинских символов, цифр, дефиса и знака подчеркивания. Данный код вы должны передавать при активации модуля аккаунта на Шаге 6 в поле integrationModule[integrationCode].

Минимальная версия API системы

Требуется указать минимальную версию API. Ваш модуль будет показан только в тех аккаунтах, которую поддерживают данную версию API.

Раздел Маркетплейса

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

Логотип

Требуется загрузить векторную версию логотипа в svg-формате.

Цены

Цена в месяц

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

Цена в месяц со скидкой

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

Срок пробного периода

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

Прочее

Страны

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

Материалы

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

Название

Здесь указывается название модуля.

Описание возможностей

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

Описание установки

Требуется описать порядок подключения модуля. Можно отталкиваться от описаний установки в существующих модулях Маркетплейса. В данном разделе важно указать, какие методы нужно включить для API-ключа, который клиент указывает в настройках подключения модуля. Не допускаются формулировки вида «Требуется разрешить все методы для API-ключа». Допустимые формулировки: «Необходимо разрешить методы разделов Склад и Доставки».

Адрес страницы подключения

Указывается адрес сервера модуля, куда будет перенаправлен пользователь в момент нажатия кнопки Подключить на Шаге 2.

Страница контактов техподдержки

Адрес страницы, где указаны контакты техподдержки модуля.

Страница документации по модулю

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

Модерация модуля

После того, как модуль разработан и все данные модуля в кабинете заполнены, вы можете отправить его на модерацию. Для этого в карточке модуля требуется выбрать «Отправить на модерацию» и в «Комментарии для модерации» указать следующие данные:

  1. Доступ к аккаунту retailCRM, на котором можно тестировать модуль (адрес аккаунта, логин и пароль)
  2. Доступ к аккаунту на сервере модуля (адрес, логин, пароль)
  3. Перечень возможностей, которые реализованы в модуле
  4. Любые другие комментарии, которые помогут при проверке модуля

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

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

Сроки модерации не регламентируются и зависят от текущей загрузки модераторов.

Важно! Изменения, вносимые в модуль, в том числе состояние активности модуля применяются в Маркетплейсе в течение 10 минут.

Работа с ценами модуля

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

Режимы оплаты модуля

Установлена только цена модуля в месяц

Допустим на модуль установлена цена 2500 рублей в месяц. Цена со скидкой и пробный период не установлены. Клиент видит ваш модуль в Маркетплейсе следующим образом:

По нажатию на модуль, он отображается таким образом:

При подключении модуля в момент его регистрации и активации на Шаге 6 система спишет 2550 рублей за первый месяц использования модуля. Если на счете нет достаточной суммы, то API выдаст ошибку со статусом 402 и не активирует модуль. В таком случае пользователю необходимо вывести информацию о том, что на счете недостаточно средств и нужно пополнить счет для включения модуля. Если первое списание прошло успешно и модуль активировался, то следующее списание будет автоматические произведено через 1 календарный месяц.

Установлена цена и цена со скидкой

Допустим на модуль установлена цена 2550 рублей в месяц и цена со скидкой 2000 рублей в месяц. Пробный период не установлен. Клиент видит ваш модуль в Маркетплейсе следующим образом:

По нажатию на модуль, он отображается таким образом:

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

Установлена цена и пробный период

Допустим на модуль установлена цена 2500 рублей в месяц и пробный период 7 дней. Цена со скидкой не установлена. Клиент видит ваш модуль в Маркетплейсе следующим образом:

По нажатию на модуль, он отображается таким образом:

Допустим клиент включает модуль 16 ноября. В момент активации модуля списание за использование модуля не производится. Списание производится системой автоматически при окончании пробного периода, то есть 21 ноября. Следующее списание будет произведено через 1 календарный месяц, то есть 21 декабря.

Заморозка модуля

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

Клиент видит замороженный модуль в Маркетплейсе следующим образом:

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

Изменение цен

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


Редакция от 20.06.2018 13:09