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

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

(перенаправлено с Developers.Marketplace)

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

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

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

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

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

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

Активация модуля и взаимодействие с 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 будет выполнять запрос при активации/деактивации модуля пользователем либо заморозке/разморозке модуля со стороны retailCRM в моменты, когда не удается списать оплаты за очередной месяц использования модуля. Формат данного колбека описан здесь POST {integrationModule["baseUrl"]}/{integrationModule["actions"]["activity"]}.

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

Адрес личного кабинета 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. Любые другие комментарии, которые помогут при проверке модуля

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


Редакция от 17.11.2017 16:35