Импорт и обновление

Как сервис поддерживает поиск в актуальном состоянии.

Полная синхронизация

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

• новые офферы — добавляются;
• изменившиеся — обновляются;
• пропавшие из фида — удаляются из поиска.

Как снять товар с поиска

Уберите его из фида (или проставьте available="false", если нужно оставить как «нет в наличии»). Отдельного «удаления» не требуется — при следующем импорте выдача синхронизируется автоматически.

Накопленная статистика популярности товаров при обычном обновлении сохраняется.

Расписание обновления

• Сервис регулярно обновляет фид сам, по расписанию.
• Интервал задаётся на проект (по умолчанию 24 часа, минимум 1 час).
• Пока по проекту идёт импорт, повторный запуск не стартует — данные не задваиваются и не «бьются».

Ручной запуск

• Первый импорт запускается автоматически при создании проекта.
• На карточке проекта есть действия «Импорт» и «Переиндексация».

Обновление по запросу

Если не хочется ждать очередного обновления по расписанию, сайт может сам сообщить сервису: «фид изменился, забирайте». Это один HTTP-запрос без тела.

ID проекта и токен — на карточке проекта, раздел «Интеграция API»:

POST https://platform.searchforce.ru/api/v1/ВАШ-PROJECT-ID/feed/refresh
Authorization: Bearer ВАШ-ТОКЕН

curl -X POST https://platform.searchforce.ru/api/v1/ВАШ-PROJECT-ID/feed/refresh \
  -H "Authorization: Bearer ВАШ-ТОКЕН"

Вызывайте после пересборки фида, а не после правки товара

Сервис по запросу скачивает фид по той же ссылке. Если файл ещё не перегенерирован, приедет прежнее содержимое и обновление ничего не изменит. Правильный момент — сразу после того, как выгрузка записала новый файл.

Ответы

Код	Тело	Что значит
202	{"status":"queued"}	Приняли, обновление запланировано
202	{"status":"already_running"}	По проекту уже идёт обновление
429	error.code = RATE_LIMITED	Пауза между запросами не вышла. Не ошибка: предыдущий запрос уже принят. В заголовке Retry-After — сколько секунд осталось
401	error.code = AUTH_REQUIRED / AUTH_INVALID	Токен не передан либо неверен (проверьте, не перевыпускали ли его)
409	error.code = FEED_NOT_CONFIGURED	У проекта не задана ссылка на фид или проект отключён
404	error.code = PROJECT_NOT_FOUND	Неверный идентификатор проекта либо закончилась подписка

Обрабатывать стоит только 401, 409 и 404 — они означают ошибку настройки. Коды 202 и 429 — штатная работа, повторять запрос не нужно.

Что важно знать

• Пауза — 5 минут на проект. Каждое обновление скачивает и переваривает фид целиком, поэтому чаще запускать смысла нет. Запрос идемпотентный: если он пришёлся на паузу, обновление уже запланировано предыдущим.
• Расписание продолжает работать. Запрос не отменяет и не сдвигает обычное обновление по интервалу.
• Токен — только для вызовов с сервера. Не вставляйте его в код виджета и вообще в страницы сайта: всё, что уходит из браузера посетителя, секретом быть не может. Перевыпуск токена на карточке проекта немедленно ломает все серверные интеграции проекта — обновите его во всех местах, где он прописан.

Куда встроить вызов

• Выгрузку делает ваш скрипт или модуль — вызов в самом конце, после записи файла.
• Выгрузка штатная, по расписанию — обёртка в cron: сначала выгрузка, потом запрос. Порядок обязателен.
• Хочется «сразу после правки товара» — на событиях каталога ставьте только отметку «каталог изменился», а пересборку фида и запрос делайте задачей раз в несколько минут. Иначе выгрузка каталога из 200 товаров даст 200 запросов, из которых сервис примет один.

Статусы

Ход импорта отражается статусами: скачивание → разбор → индексация → завершено (или ошибка). При ошибке в журнале импорта сохраняется её текст — по нему удобно диагностировать проблему.

Отдельный статус — «Проблемы с данными»: фид скачался и разобрался, но у части товаров не хватает обязательных тегов. Это не сбой импорта, поэтому поиск работает; правит его тот, кто готовит фид.

Фид без товаров

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

Исключений из этого правила нет. Если витрина встала на паузу и фид отдаёт ноль товаров, прогон будет падать, пока товары не вернутся, — прежняя выдача при этом остаётся рабочей. Чтобы убрать проект из поиска, отключите его на карточке (поле «Активен»), а не опустошайте фид.

Каркас важнее содержимого

Если блока <offers> в фиде нет вовсе, это ошибка структуры, а не пустой каталог. См. «Каркас фида».

Ошибки в данных

Импорт проверяет каждый оффер на четыре тега и записывает, чего не хватило:

Что проверяем	Если тега нет
Идентификатор (id оффера)	Товар не попадает в поиск — его нечем отличить от других
Название (<name> или <model>)	Подставляется производитель и категория — в выдаче такой товар выглядит безымянным
Цена (<price>)	Товар уходит в поиск с нулевой ценой
Изображение (<picture>)	Карточка в выдаче остаётся без картинки
Ссылка (<url>)	Адрес достраивается из ссылки на категорию и идентификатора — догадка, которая нередко ведёт в 404

Сюда же попадают две претензии к структуре: в фиде нет блока категорий (строка одна на импорт) и categoryId товара не найден в дереве категорий — тогда вместо названия категории в поиск уходит её идентификатор.

Результат виден на карточке проекта, в блоке «Последнее обновление фида»: поле «Количество ошибок» и кнопка «Показать» рядом с ним. В окне — сводка («Отсутствует поле «Цена» — 1240») и сами строки: чего не хватает, у какого оффера (его id и название) и каким по счёту он идёт в файле. Номер помогает найти место в фиде, если id в выгрузке не ищется. Список листается по 50 строк, а щелчок по строке сводки оставляет в нём только ошибки этого типа.

TIP

Журнал хранит до 10 000 строк одного импорта — если ошибок больше, показаны первые: дальше нужен уже не список, а число, и оно стоит рядом в поле «Количество ошибок». Хранится журнал только последнего импорта: исправили фид, запустили импорт — счётчик обнулился.

Категория в этот список не попадает: цепочку категорий сервис достраивает сам (см. «Оффер»). Но данные всё равно получаются хуже — что положить в фид, описано в «Требованиях».

Ограничения

Параметр	Значение
Размер фида	до 2 ГБ (проверяется и при создании проекта, и при каждом регулярном импорте; превышение — ошибка импорта)
Время на скачивание	15 минут при регулярном импорте, 30 с при анализе в мастере создания проекта
Интервал обновления	от 1 часа (по умолчанию 24 ч)

WARNING

Крупные каталоги лучше генерировать в статический файл по расписанию, а не собирать на лету по запросу, — иначе фид может не успеть отдаться. См. «Требования».

Диагностика неудачного импорта

1. Откройте журнал импортов проекта — там статус и текст ошибки.
2. Типичные причины: нарушен каркас XML, недоступная ссылка, отвергнутый доступ к закрытому фиду («Закрытый фид»), таймаут, превышение размера, неверная кодировка.
3. Проверьте фид локально — см. «Быстрый старт».
4. Исправьте фид и запустите импорт вручную с карточки проекта.