RIZEL Search API для Битрикс

Модуль rizel.searchapi отправляет каталог в RIZEL и выполняет поисковые запросы по ключам API. Разработчик устанавливает и настраивает его в Битрикс. Доступ RIZEL к серверу сайта, привязка установки к порталу и Aspro не нужны. Доступ к самому API требует действующей подписки или пробного периода.

Требования

• PHP 7.4 или новее с JSON, mbstring и OpenSSL.
• Модули Битрикс main, iblock, catalog; currency для пересчёта валют.
• Исходящие HTTPS-запросы к адресу API, действующие корневые сертификаты.
• Администратор Битрикс для установки и настройки.
• Ключ импорта rzi_... и ключ поиска rzp_live_.... Оба ключа должны относиться к одному подключению.

В кабинете RIZEL откройте «Интеграции → Поиск», нажмите «Подключить сайт» и выберите самостоятельное подключение через API. Укажите HTTPS-адрес и тариф. После добавления сайта выпустите два ключа: «Импорт каталога» и «Поиск». Оба доступны до загрузки каталога. Сохраните их перед закрытием окна. SSH-доступ и добавление сайта администратором портала не требуются.

Это отдельный модуль. Он не использует настройки rizel.search и не заменяет компоненты rizel:search.form, rizel:search.page, страницу /search/ или шапку сайта. Не направляйте два экспортёра в одно подключение API: их полные выгрузки будут заменять каталог друг друга.

Установка

1. Распакуйте rizel.searchapi-1.1.4.tar.gz. Внутри находится папка rizel.searchapi.
2. Скопируйте её в /local/modules/. Должен существовать файл /local/modules/rizel.searchapi/install/index.php.
3. Откройте «Маркетплейс → Установленные решения» в административной части Битрикс. Установите «RIZEL Search API».
4. Откройте настройки модуля: /bitrix/admin/settings.php?lang=ru&mid=rizel.searchapi.

Установщик обновляет стандартные файлы в /local/components/rizel/search.api и добавляет агент отправки пакетов. Перед заменой изменённых файлов сохраняется резервная копия в /local/components/rizel/.rizel-searchapi-backups/. Дополнительные пользовательские шаблоны, настройки и ключи сохраняются. Правки непосредственно в стандартном шаблоне .default заменяются версией модуля и остаются в резервной копии. Её PHP-файл защищён от выдачи исходного текста: после первой строки находится JSON, files содержит прежние файлы в base64, modes — их права. Восстановление выполняется администратором с файловым доступом.

После замены папки модуля достаточно нажать «Обновить стандартный компонент» в настройках модуля на вкладке «Подключение». Переустановка также обновляет компонент. Если шаблон переопределён в /local/templates/.../components/rizel/search.api/ или /bitrix/templates/.../components/rizel/search.api/, обновите его отдельно: он имеет приоритет над стандартным шаблоном.

Настройки

Адрес API по умолчанию: https://rizel.ru. HTTPS-адрес сайта подставляется из текущего домена. Если административная часть открыта на другом домене, укажите публичный адрес магазина вручную. Рядом с полями ключей есть ссылка «Получить», которая открывает подключение поиска в личном кабинете RIZEL. Вставьте ключ импорта в соответствующее поле. Ключ поиска можно добавить сразу вместе с ключом импорта. Поля ключей после сохранения остаются пустыми: пустое значение сохраняет прежний ключ. Настройки с ключами доступны только администратору. Ключи хранятся в таблице настроек Битрикс; ограничьте доступ к базе и её резервным копиям.

Выберите инфоблок товаров из списка зарегистрированных торговых каталогов. Инфоблоки торговых предложений не показываются как самостоятельные каталоги. Связанный инфоблок предложений и свойство связи определяются автоматически по настройкам торгового каталога Битрикс. Если предложений нет, появится «Не используются».

Свойства выбираются из списков с названием и CODE. Для артикула модуль ищет коды ARTIKUL, ARTICLE, CML2_ARTICLE, SKU и VENDOR_CODE; для бренда: BRAND, BREND и MANUFACTURER. Проверьте предложенный выбор или выберите другое свойство. Артикул товара выбирается из свойств товаров, артикул предложения из свойств предложений, бренд из свойств товаров. Свойства без CODE в списки не попадают. При смене каталога списки обновляются, характеристики нужно выбрать заново.

Характеристики выбираются из общего списка свойств товаров и предложений. Для выбора нескольких строк удерживайте Ctrl (Cmd на macOS). Повторяющиеся CODE показаны один раз и применяются к обоим инфоблокам. Пустой список характеристик означает, что характеристики не отправляются. Это позволяет исключить внутренние данные каталога.

Остальные поля берутся из стандартных полей Битрикс, как в исходном модуле:

Выгружаются активные элементы с учётом дат активности. Родитель предложения должен входить в активный каталог выбранного инфоблока. Иначе выгрузка остановится с указанием ID проблемного предложения. У предложений без своего раздела используется раздел родителя.

В этой версии одна конфигурация каталога на установку Битрикс. Выгрузка предназначена для публичного ассортимента: права групп Битрикс, персональные цены, скидки и остатки по отдельным складам в API не передаются. Для закрытого каталога модуль не подходит. JSON API не принимает изображения: компонент получает фотографии товаров локально по ID элемента через собственный image.php.

Первая выгрузка

1. Во вкладке «Подключение» укажите адреса и оба ключа. Во вкладке «Каталог» выберите инфоблок и свойства. Нажмите «Сохранить настройки».
2. При необходимости нажмите «Проверить сохранённые ключи». Эта кнопка не сохраняет введённые значения.
3. Откройте вкладку «Выгрузка» и нажмите «Выгрузить каталог» один раз.
4. Модуль сам передаёт каталог порциями. Индикатор показывает число переданных записей и процент относительно количества активных элементов в начале выгрузки. Изменение каталога во время передачи может изменить итоговое количество.
5. После 100% появляется статус приёма каталога и номер задания. Затем модуль проверяет это задание до публикации индекса. Индексация может ожидать ночного окна. Старый опубликованный индекс продолжает обслуживать запросы.
6. Дождитесь статуса «Поисковый индекс опубликован». В кабинете RIZEL запустите пробный период, если доступ ещё не активен, и проверьте поиск на сайте.

Не нужно нажимать кнопки для каждой порции. Пока страница открыта, запросы выполняются последовательно автоматически. Можно закрыть страницу: агент Битрикс продолжит выгрузку раз в минуту. После возвращения прогресс восстановится. Агенты должны выполняться на посещениях сайта или через настроенный cron. На сайте без посещений настройте штатный запуск агентов через cron; сам модуль системный cron не меняет. Если закрыть страницу при неработающих агентах, выгрузка продолжится при следующем открытии настроек.

При временной ошибке модуль повторяет запрос автоматически с увеличением паузы. После пяти неудач он сохраняет состояние и показывает причину. Исправьте соединение и нажмите «Повторить подключение». Подготовленные данные и ключ идемпотентности сохраняются, принятые записи повторно не учитываются. Если ошибка в самих данных, отмените незавершённую передачу, исправьте каталог и запустите новую выгрузку. После отправки задания на индексацию отмена недоступна: модуль сначала должен получить результат текущего задания.

Обновление каталога

После завершения индексации снова доступна кнопка «Выгрузить каталог». Ручной сброс состояния не требуется. Каждая выгрузка полная: удалённые и деактивированные товары исключаются из новой версии индекса. Пока она строится, поиск использует опубликованную версию.

Статус конкретного задания проверяется через GET /v1/catalog/jobs/{id} с ключом импорта. Версия API портала должна поддерживать этот метод. При обновлении сначала обновите портал, затем модуль. Готовность предыдущего индекса не считается подтверждением завершения новой выгрузки.

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

Страница поиска

Создайте страницу /catalog-search/index.php средствами Битрикс или загрузите файл:

<?php
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php';
$APPLICATION->SetTitle('Поиск по каталогу');
$APPLICATION->IncludeComponent('rizel:search.api', '', [
    'MODE' => 'results',
    'ACTION_PAGE' => '/catalog-search/',
    'PAGE_SIZE' => 20,
    'FALLBACK_URL' => '/search/',
]);
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/footer.php';

FALLBACK_URL укажите только если по этому адресу есть отдельный штатный поиск. При ошибке API компонент покажет ссылку на него с сохранённым запросом. Пустое значение скроет ссылку. Автоматического перенаправления нет.

Чтобы поставить только строку поиска в шапку или включаемую область:

<?php
$APPLICATION->IncludeComponent('rizel:search.api', '', [
    'MODE' => 'form',
    'ACTION_PAGE' => '/catalog-search/',
]);

Компонент использует те же HTML-шаблоны, JavaScript и CSS, что и компоненты rizel:search.form и rizel:search.page автоматической интеграции:

• MODE=form: выпадающая выдача при вводе, товары, бренды, разделы, подсказки, фотографии, очистка поля, навигация клавиатурой и переход ко всем результатам.
• MODE=results: поиск при вводе и отправке формы, карточки, похожие запросы, «Показать ещё», состояние загрузки и история браузера.

Для работы нужен JavaScript. Запросы идут в ajax.php внутри компонента; изображения — в image.php. Оба обработчика устанавливаются вместе с компонентом. Модуль rizel.search не требуется. Ключ API остаётся на сервере магазина. ACTION_PAGE задаёт адрес страницы результатов, в том числе для истории браузера и переходов по похожим запросам. Страница должна содержать компонент в режиме results.

При обновлении используйте кнопку «Обновить стандартный компонент» или переустановку модуля. Код и стандартный шаблон обновляются вместе. Пользовательские шаблоны требуют переноса изменений отдельно. Идентичность стандартных шаблонов проверяется тестом. Скрипт ожидает готовности DOM и поддерживает загрузку через композитные фреймы. В шапках Aspro с мобильным контейнером .inline-search-block компонент перехватывает мобильную кнопку поиска и открывает ту же RIZEL-форму вместо перехода на штатный поиск.

Проверка перед включением

• Оба ключа принадлежат одному подключению; доступ к поиску активен.
• Артикулы, русские названия и товары с предложениями находятся.
• Ссылки ведут на правильные карточки, цены соответствуют базовым ценам каталога.
• Обновлённый товар появляется после повторной выгрузки; удалённый исчезает.
• Ошибочный ключ показывает сообщение об ошибке, а не секрет или ответ сервера.
• Исходный модуль и штатный поиск продолжают работать.

Удаление и обновление

Удалите модуль через список модулей Битрикс. Агент будет удалён. Настройки и компонент сохраняются, чтобы не потерять ключи и изменения шаблона. Компонент после удаления модуля ничего не выводит. Удалите его вызовы из шаблона сайта. При окончательном отказе от сервиса отзовите ключи и удалите сохранённые настройки через Bitrix\Main\Config\Option::delete('rizel.searchapi') из доверенного административного скрипта. Каталоги модуля и компонента удаляются вручную после сохранения нужных файлов.

Перед обновлением остановите фоновую отправку и сохраните копию модуля, компонента и настроек. Обновляйте только rizel.searchapi и rizel:search.api.

Проверки разработчика

php -n tests/sync_test.php
php -n tests/api_test.php
php -n tests/component_test.php
php -n tests/settings_test.php
php -n tests/install_test.php
php -n tests/options_test.php
node --test tests/sync-ui.test.mjs

Автоматические проверки используют имитацию ответов API. Установка на живой Битрикс и запросы с действующими ключами требуют отдельной проверки на тестовом сайте.

Цены магазина и отображение результатов

Экспортёр не читает цены и не передаёт price/currency в поисковый сервис. Компоненты игнорируют цены из индекса и получают их на стороне магазина через CCatalogProduct::GetOptimalPrice: количество 1, группы текущего покупателя, текущий сайт, проверка доступа к элементу. Для найденного предложения используется matched_offer_id, иначе external_id. Обработчики расчёта цен магазина продолжают работать. Если локальная цена недоступна, цена не выводится; базовая цена из индекса не используется как запасной вариант. Цена корзины может отличаться от цены каталога. Ответ AJAX с локальными ценами имеет Cache-Control: private, no-store.

В параметрах компонентов доступны флажки (Y/N, по умолчанию Y):

• SHOW_AVAILABILITY — отображать наличие.
• SHOW_PRICES — отображать цены; при N локальный расчёт не вызывается.
• SHOW_BRANDS — отображать бренды в товарах и группах выпадающего поиска.
• SHOW_SECTIONS — отображать разделы в товарах и группах выпадающего поиска.
• SHOW_SUGGESTIONS — отображать текстовые подсказки / похожие запросы. Товарная выдача сохраняется при отключении этого флажка.

Настройки действуют на блоки, которые выводит выбранный режим компонента. Для нестандартного оформления и источника цены магазин может использовать свой шаблон с result_modifier.php или обработчики OnGetOptimalPrice. После обновления нужно обновить также установленные компоненты и публичный AJAX-обработчик (если используется rizel.search). Старые цены в поисковом индексе перестанут использоваться сразу; их удаление из каталога сервиса происходит при следующей синхронизации соответствующих записей и публикации индекса.