Скопировать ссылку на статью Скопировано Как происходит подключение и активация модуля в системе Скопировать ссылку на статью Скопировано

Содержание

• Включение поддержки простого подключения модуля
• Обновление разрешений подключённого модуля
• Подключение и активация модуля
  • Шаг 1. Информация в модуле
  • Шаг 2. Подключение модуля
  • Шаг 3. Регистрация модуля
  • Шаг 4. Переадресация в настройки модуля
  • Шаг 5. Личный кабинет модуля

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

Включение поддержки простого подключения модуля

Чтобы включить поддержку простого подключения, в партнерском кабинете, в карточке редактирования модуля, необходимо активировать чекбокс «Поддерживается простое подключение» и в поле «URL для запроса конфигурации простого подключения» указать адрес для получения конфигурации. После сохранения карточки модуля в поле «Секрет» будет сгенерирована секретная строка для верификации запроса подключения со стороны системы.

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

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

Обновление разрешений подключённого модуля

Если модулю потребовались другие разрешения:

1. Обновите поле Доступные модулю разрешения в партнерском кабинете. Оно должно включать все разрешения, которые модуль запросит.
2. Обновите список scopes, возвращаемый через configUrl.
3. Для каждого существующего подключения вызовите метод POST /api/v5/integration-modules/{code}/update-scopes, используя текущий связанный ключ экземпляра. Ключ должен иметь разрешение integration_write.
4. Проверьте ключ из ответа, сохраните его и переключите на него все обращения экземпляра к CRM.

Каждый успешный вызов метода создаёт новый ключ и связывает его с экземпляром модуля. Предыдущий ключ простого подключения деактивируется автоматически, если он не связан с другим экземпляром. Если ключ используют несколько экземпляров, прекратите его использование и деактивируйте вручную только после их перевода на отдельные ключи. API-ключ нельзя удалить из системы — его можно только деактивировать.

Подключение и активация модуля

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

         Модуль                   Пользователь                  Система
       ------------------------------------------------------------------
1.          |                Переходит в маркетплейс               |
            |                 и открывает ваш модуль -----> Получает данные для
            |                           |                   подключения модуля
            | <-------------------------------------------- инициацией запроса
            |                           |                     {configUrl}
            |                           |                          |
2.          |                        Нажимает                      |
            |                   кнопку «Подключить»                |
            |                    в карточке Модуля -----> Для подключения модуля
            |                     в Маркетплейсе         система инициирует запрос
            | <--------------------------------------------- {registerUrl}
            |                           |                          |
3.   Регистрация Модуля                 |                          |
        в аккаунте     ------------------------------------------> |
         системы                        |                          |
            |                           |                          |
            |                           |                    Перенаправление
4.          | <-------------------------------------------    Пользователя
            |                           |                  на форму настройки
            |                           |                          |
5.    Перенаправление                   |                          |
       пользователя    ---------------> | -----------------------> |
        в аккаунт                       |                          |
        системы                         |                          |
            |                           |                          |
            |               Пользователь может перейти            |
            |                 в личный кабинет модуля              |
            |              для его дальнейшей настройки            |
       ------------------------------------------------------------------

Если модуль содержит frontend-часть, после успешной регистрации система также начинает:

• отображать виджеты модуля в опубликованных targets;
• открывать собственные страницы модуля, если они заданы;
• выполнять запросы к backend-части модуля через host API.

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

Шаг 1. Информация в модуле

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

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

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

Шаг 2. Подключение модуля

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

Для подключения интеграционного модуля система инициирует запрос {registerUrl} по адресу, указанному в ответе на запрос {configUrl}.

На этом этапе модуль должен:

• проверить валидность запроса;
• проверить входные данные подключения;
• подготовить параметры регистрации модуля в CRM;
• при необходимости вернуть понятное сообщение об ошибке пользователю.

Подключение модуля происходит в тот момент, когда пользователь нажимает на кнопку «Подключить» в 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.

Относительные пути конкретных методов 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.

Параметры frontend-части JS-модуля

Если модуль содержит frontend-часть, при регистрации должны быть согласованы:

• uuid
• entrypoint
• runner
• targets
• pages
• stylesheet

В API v5 эти параметры передаются внутри integrationModule[integrations][embedJs]. Для frontend-части используются поля entrypoint, runner, targets, pages и stylesheet; поле entrypointType не используется.

Для актуального сценария entrypoint должен указывать на JS-файл frontend-части. HTML-файл используется только в legacy-сценарии iframe.

Если модуль публикует собственные страницы, в конфигурации должны быть переданы pages. После активации такие страницы открываются внутри CRM по адресу:

/modules/<moduleCode>/<pageCode>

Если используется v1-endpoint и/или собственные страницы, в integrationModule[integrations][embedJs][runner] нужно передать значение worker. Значение iframe относится к legacy-сценарию и не рекомендуется для новых модулей. Если модуль добавляет собственные страницы или использует v1-endpoint, необходимо указывать worker.

Подробно структура страниц описана в статье «Создание собственных страниц JS-модулей». Навигация внутри страниц описана в статье «Навигация и маршрутизация в JS-модулях».

Список доступных точек встраивания описан в статье «Точки встраивания JS-модулей».

Шаг 4. Переадресация в настройки модуля

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

Шаг 5. Личный кабинет модуля

После подключения модуля, переход в личный кабинет модуля выполняется POST запросом с передачей в параметре clientId уникального хеш-ключа клиента указанного при публикации модуля (clientId).

Если модуль содержит frontend-часть, после подключения система начинает использовать ее как часть интерфейса CRM. Для модулей со страницами становятся доступны навигация, query string и отдельные модульные экраны внутри CRM. Подробно это описано в статьях «Навигация и маршрутизация в JS-модулях» и «Создание собственных страниц JS-модулей».