В случае, если вы не планируете публиковать модуль в Маркетплейсе, используйте способ подключения описанный в отдельной статье. В остальных случаях используйте описанный ниже способ.
Включение поддержки простого подключения модуля
Чтобы включить поддержку простого подключения, в партнерском кабинете, в карточке редактирования модуля, необходимо активировать чекбокс «Поддерживается простое подключение» и в поле «URL для запроса конфигурации простого подключения» указать адрес для получения конфигурации. После сохранения карточки модуля в поле «Секрет» будет сгенерирована секретная строка для верификации запроса подключения со стороны системы.
Учитывайте метод Обновление разрешений для API ключа, который нужен для обновления разрешений API ключа. При этом доступные права будут зависеть от указанных в партнёрском кабинете.
Также, для тестирования простого подключения, неопубликованный модуль будет отображаться в партнерском CRM-аккаунте, который связан с учетной записью в партнерском кабинете.
Подключение и активация модуля
Общая схема активации модуля выглядит следующим образом:
Модуль Пользователь Система
------------------------------------------------------------------
1. | Переходит в маркетплейс |
| и открывает ваш модуль -----> Получает данные для
| | подключения модуля
| <-------------------------------------------- инициацией запроса
| | {configUrl}
| | |
2. | Нажимает |
| кнопку «Подключить» |
| в карточке Модуля -----> Для подключения модуля
| в Маркетплейсе система инициирует запрос
| <--------------------------------------------- {registerUrl}
| | |
3. Регистрация Модуля | |
в аккаунте ------------------------------------------> |
системы | |
| | |
| | Перенаправление
4. | <------------------------------------------- Пользователя
| | на форму настройки
| | |
5. Перенаправление | |
пользователя ---------------> | -----------------------> |
в аккаунт | |
системы | |
| | |
| Пользователь может перейти |
| в личный кабинет модуля |
| для его дальнейшей настройки |
------------------------------------------------------------------
Рассмотрим основные шаги данного процесса.
Шаг 1. Информация в модуле
Пользователь заходит в Маркетплейс и видит ваш модуль. По нажатию на модуль открывается описание возможностей модуля и инструкция по подключению.
Информация, отображаемая в карточке модуля, вносится через партнерский кабинет. Об этом рассказано подробнее в разделе Публикация модуля.
При открытии PopUp также происходит получение данных, необходимых для подключения модуля. Для этого система инициирует запрос по адресу, указанному в партнерском кабинете.
Шаг 2. Подключение модуля
Пользователь в карточке модуля нажимает кнопку Подключить.
Для подключения интеграционного модуля система инициирует запрос {registerUrl} по адресу, указанному в ответе на запрос {configUrl}.
Подключение модуля происходит в тот момент, когда пользователь нажимает на кнопку «Подключить» в PopUp. По запросу системы модуль должен верифицировать запрос с помощью параметра register[token]. Данный токен - это хэш-код, сгенерированный на основе переданного API-ключа методом hmac с помощью алгоритма sha256, где в качестве секрета используется секретная строка из личного кабинета в партнерском кабинете.
Например, в php токен можно вычислить так: hash_hmac(‘sha256’, ‘<api-key>’, ‘<secret>’), где <api-key> - переданный ключ, <secret> - секретная строка из партнерского кабинета. Если результат выполнения функции не равен переданному токену - значит запрос не валидный и пришел, вероятнее всего, не из системы.
Обработка ошибок
При возникновении ошибки, необходимо вернуть ответ (HTTP статус 200) в формате:
{
"success": false,
"errorMsg": "Текст ошибки" // Сообщение об ошибке. Будет отображаться пользователю в карточке модуля
}Шаг 3. Регистрация модуля
С помощью метода POST /api/v5/integration-modules/{code}/edit сделать запрос в систему с полученными данными для регистрации модуля и, в случае успеха, вернуть в ответе ссылку на созданный личный кабинет пользователя в поле accountUrl. После чего, пользователь будет перенаправлен в личный кабинет по указанной ссылке так, как будто он перешёл в личный кабинет по ссылке на странице редактирования модуля в системе (будет сделан POST запрос с параметром clientId). При регистрации указываются следующие данные:
Символьный код модуля integrationModule[integrationCode]
Данный код должен совпадать с тем кодом модуля, который указан при публикации модуля. На основе этого система будет понимать, что это именно ваш модуль. Это важно, например, в случае платного модуля, за который списываются деньги с пользователя, которые затем перечисляются вам как партнеру.
Символьный код экземпляра модуля integrationModule[code]
В случае, если ваш модуль позволяет регистрировать несколько экземпляров модуля в рамках одного аккаунта, данный код должен быть уникальным. Это полезно, например, в случае модулей интеграции со службами доставки, так как нередко у пользователя есть несколько учетных записей в службе доставки для разных юридических лиц.
Если поддержка нескольких экземпляров в рамках одного аккаунта не предполагается, то данный параметр может совпадать с integrationModule[integrationCode].
Активность модуля integrationModule[active]
Требуется указать в данном параметре true, чтобы модуль активировался в аккаунте. В случае, если модуль платный, это является основанием для списания с пользователя суммы за ближайший месяц использования модуля, но при условии, что для модуля не настроен пробный период.
Уникальный хеш-ключ клиента integrationModule[clientId]
В данном параметре необходимо передавать сгенерированный хеш-ключ, который будет известен только вам и данному аккаунту системы. Данный параметр будет передаваться во всех запросах от системы и позволяет модулю, во-первых, определить, что данные запросы пришли именно от этого аккаунта, а во-вторых, что их отправил именно данный аккаунт, а не третья сторона.
Базовый URL integrationModule[baseUrl]
Базовый URL, относительно которого будут строится адреса, куда аккаунт системы выполняет запросы. Например https://some-service.ru/simla/api.
Относительные пути конкретных методов integrationModule[actions][]
Необходимо задать относительный путь метода integrationModule[actions][activity], на который аккаунт системы будет выполнять запрос при:
- активации/деактивации модуля пользователем
- заморозке/разморозке модуля со стороны системы в моменты, когда не удается списать оплаты за очередной месяц использования модуля
- переименовании системы.
Формат данного колбека описан здесь POST {integrationModule["baseUrl"]}/{integrationModule["actions"]["activity"]}.
В случае получения запроса деактивации или заморозки модуля, модуль должен соответственно прекратить либо приостановить свою работу на данном аккаунте. В случае получения запроса активации или разморозки модуля, модуль соответственно должен произвести обратные действия. При переименовании системы нужно сохранить новый URL системы, присланный в запросе, и все последующие запросы к системе отправлять на этот URL.
Адрес личного кабинета integrationModule[accountUrl]
В данном параметре передается полный адрес личного кабинета на стороне модуля. При передаче данного параметра после активации в карточке модуля в системе для пользователя доступна кнопка перехода в кабинет, где он может впоследствии изменять настройки модуля. При нажатии на кнопку пользователь перенаправляется на указанный адрес POST-методом с переданным параметром clientId. Если на стороне модуля присутствует авторизация, необходимо прозрачно авторизовывать пользователя на основе clientId и перенаправлять в раздел редактирования настроек модуля.
Параметры отображения модуля до публикации в Маркетплейсе
Название модуля, логотип модуля и страны, в которых работает модуль задаются при публикации модуля, но для проверки их корректного применения на этапе разработки модуля вы можете передавать их при активации модуля в параметрах integrationModule[name], integrationModule[logo] и integrationModule[availableCountries]. После публикации модуля в Маркетплейсе данные параметры игнорируются.
Параметры для особых видов модуля
Для модулей типа Доставка, Телефония, Склад и ряда других требуется передавать дополнительные настройки, которые необходимы для полноценной работы данных типов модулей. Подробнее о порядке разработки данных типов модулей написано в документации по каждому из типов модулей:
- Телефония
- Служба доставки
- Платежная система
- Складская система и фулфилмент
- Рекомендации
- Боты
- Мессенджеры
- JS модули
Особенности платных модулей
Если ваш модуль является платным и у него нет пробного периода, в момент активации модуля система пытается списать с баланса пользователя оплату за ближайший месяц использования модуля. Если оплату не удалось списать метод POST /api/v5/integration-modules/{code}/edit выдаст ошибку со HTTP-статусом 402. В этом случае нужно сообщить пользователю, что на его счету недостаточно средств для активации модуля, вернув пояснительное сообщение в поле errorMsg.
Шаг 4. Переадресация в настройки модуля
Если активация модуля произведена успешно, то система автоматически перенаправит пользователя на страницу настройки модуля.
Шаг 5. Личный кабинет модуля
После подключения модуля, переход в личный кабинет модуля выполняется POST запросом с передачей в параметре clientId уникального кеш-ключа клиента указанного при публикации модуля (clientId).