Порядок интеграции сервиса рекомендаций через API

Скопировать ссылку на статью

Скопировано

Регистрация и конфигурация сервиса рекомендаций

Для регистрации и конфигурации сервиса рекомендаций необходимо использовать метод POST /api/v5/integration-modules/{code}/edit. Если модуль с кодом {code} уже существует, метод меняет его настройки, в противном случае создается новый интеграционный модуль сервиса рекомендаций. Текущие параметры модуля можно посмотреть используя метод GET /api/v5/integration-modules/{code}.

При регистрации сервиса необходимо указать название integrationModule[name], код integrationModule[code], базовый url integrationModule[baseUrl] и пользовательский идентификатор integrationModule[clientId]. clientId необходим для идентификации пользователя в системе при совершении callback-запросов, подробнее в статье.

Набор вкладок передается в виде массива в поле integrationModule[integrations][recommendation][modes]. Для каждой вкладки требуется задать код и названия на языках системы. Код вкладки передается в url-параметре mode при обращении к сервису рекомендаций. Названия на языках системы передаются в виде ассоциативного массива, где ключ - язык системы (ru, es, en), а значение - название вкладки на данном языке системы. Передача ключа en обязательна, ключи ru и es могут отсутствовать, при отсутствии названия вкладки для языка будет использовано название из языка en. Передача несуществующих языков системы будет вызывать ошибку валидации.

 [
     [
         'code' => 'upsell',
         'names' => [
             'ru' => 'Upsell-товары',
             'en' => 'Products for upsell',
             'es' => ,
         ],
     ],
     [
         'code' => 'presents',
         'names' => [
             'ru' => '',
             'en' => 'Presents',
             'es' => ,
         ],
     ],
 ]

Например, при передаче следующего массива вкладок система посчитает, что модуль рекомендаций предоставляет две вкладки:

• Вкладка с кодом upsell, при выводе вкладки для языка ru будет использоваться название из ключа [names][ru], т.е "Upsell-товары", а для языка en будет использоваться название из [names][en] ("Products for upsell"). Так как название для языка es не передано, то будет использоваться название en.
• Вкладка с кодом presents, при выводе вкладки для всех языков будет использовано название из [names][en], т.е "Presents".

Также можно указать integrationModule[integrations][recommendation][addDefaultModes] со значением true или false. Установка данного флага в true позволяет выводить помимо вкладок модуля системные вкладки "С этим товаром покупают" и "Аналоги". Если модуль позволяет выводить системные вкладки, то на коды вкладок модуля накладывается ограничение - они не должны быть равны analogs и buying_with. В настройках модуля также возможно отключение вывода системных вкладок, если addDefaultModes равен true.

Вкладки показываются в следующем порядке:

• Системная вкладка "С этим товаром покупают" (если вкладка активирована в настройках модуля)
• Системная вкладка "Аналоги" (если вкладка активирована в настройках модуля)
• Вкладки, предоставляемые модулем, в том же порядке как указаны в массиве integrationModule[integrations][recommendation][modes].

Также можно указать логотип сервиса рекомендаций integrationModule[logo], который будет отображаться в списке интеграций в разделе Маркетплейс.

Для активации callback-методов необходимо передать настройки нужного callback-метода в integrationModule[integrations][recommendation][actions]. Для каждого метода необходимо указать код code и url. Адрес для запроса будет собираться из integrationModule[baseUrl] базовой конфигурации и url конкретного метода.

Ниже приведены доступные callback-методы.

Получение списка рекомендаций для товара

Для получения списка рекомендаций система будет выполнять GET запрос к методу с кодом recommendation из массива integrationModule[integrations][recommendation][actions]. К url метода будут добавлены следующие параметры:

• ids[] - ID товаров
• externalIds[] - externalId товаров
• mode - код вкладки, возможные значения берутся из кодов вкладок integrationModule[integrations][recommendation][modes], переданных во время создания/редактирования модуля

В качестве ответа от сервиса рекомендаций система принимает объект со следующими полями:

• by - указывает по какому полю система должна идентифицировать товары, возможные значения id, externalId
• ids - массив с идентификаторами товаров