Эпицентр: цены и наличие для OpenCart

Эпицентр: цены и наличие — модуль для OpenCart 2.3, 3.x и 4.x, который отправляет цену, старую (зачёркнутую) цену и наличие товаров магазина в кабинет Эпицентр Маркетплейс через официальное API. Изменили цену на сайте, закончился товар на складе, запустили акцию — кабинет получает то же самое, без выгрузки файлов и без ручного редактирования сотен карточек.

Описания товаров, которые уже есть в кабинете, модуль не меняет. Он обновляет то, что меняется каждый день: сколько стоит и есть ли в наличии. Карточки в кабинете остаются вашими, модуль лишь держит их цены и остатки в синхроне с магазином.

Новые товары модуль тоже помогает завести. Публичное API Эпицентра создавать товары не умеет, поэтому модуль собирает XML-файл для импорта в кабинет: категории и характеристики берёт из справочника Эпицентра, значения — из ваших товаров, и показывает, какой обязательной характеристики не хватает. После модерации цены и наличие этих товаров дальше держит синхронизация через API.

Зачем это магазину

Продавец на Эпицентре ведёт два каталога: собственный магазин и кабинет маркетплейса. Цену меняют на сайте, а в кабинете она остаётся старой, пока кто-то не дойдёт до неё руками или не загрузит новый файл. Товар закончился у вас — на Эпицентре его продолжают покупать, и заказы приходится отменять.

Каждая такая отмена бьёт по рейтингу продавца, а цена ниже, чем на сайте, — по марже. На каталоге из нескольких сотен позиций ручная сверка не успевает за изменениями, особенно в день распродажи.

Модуль убирает эту сверку. Он видит, что в товаре изменилось, и отправляет в кабинет только это — цену, старую цену и наличие.

Что получает админ

Одна страница в «Расширения → Модули»: подключение, что именно отправлять, синхронизация, список товаров, которые не обновились, и журнал пакетов. Над кнопкой видны счётчики: сколько товаров обновлено, сколько ещё в обработке Эпицентра, сколько не найдено в кабинете и сколько изменений ждёт отправки.

Что именно отправляется

Цена. Модуль считает её так, как её видит покупатель на витрине: с налогом по правилам магазина и в гривнях, даже если основная валюта магазина другая. Расхождение цены между сайтом и маркетплейсом — повод для вопросов от кабинета, поэтому модуль не берёт «сырую» цену из базы, а повторяет расчёт витрины.

Старая цена. Если на товар действует акция, акционная цена уходит как цена, а обычная — как зачёркнутая старая. Акции OpenCart 2.3 и 3.x и новая схема скидок OpenCart 4.1 учитываются одинаково.

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

Код товара. Эпицентр находит ваш товар по артикулу. Модуль берёт артикул (SKU), а если он пустой — модель. Можно принудительно брать только модель.

Как это работает — шаг за шагом

1. Вы вставляете токен кабинета и нажимаете «Проверить». Токен берётся в кабинете: «Настройки компании» → вкладка «API».

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

3. Изменённое собирается в пакеты до 1000 товаров и уходит в Эпицентр одним запросом. Товары, в которых ничего не изменилось с прошлой отправки, пропускаются.

4. Эпицентр принимает пакет в очередь. Через несколько минут кнопка обновления статусов подбирает результат обработки: что обновлено, что уже было таким же, что отклонено.

5. Товары с проблемой попадают в список «Товары, которые не обновились» с объяснением человеческим языком.

В Pro шаги 2–4 происходят сами: сохранение товара в админке или заказ, который списал остаток, ставит товар в очередь, а крон отправляет очередь и подбирает результаты.

Товары, которые не обновились

Кабинет не всегда принимает изменение, и причина важна. Товара с таким артикулом в кабинете нет — нужно сверить коды. Товар участвует в акции Эпицентра — цену менять нельзя, пока акция идёт. У товара на сайте нет ни артикула, ни модели — его просто нечем найти.

Модуль показывает это словами, а не кодом ответа API, со ссылкой на редактирование товара. Тот же набор значений повторно не отправляется, пока вы не измените товар, — кабинет не получает одну и ту же ошибку каждый час.

Журнал пакетов

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

Новые товары с характеристиками

Эпицентр принимает новый товар только с обязательными характеристиками из своего справочника: бренд, страна, объём — у каждой категории свой набор и свои коды значений. Вручную это таблица на сотни строк. Модуль превращает её в три шага:

1. Справочник. Кнопка загружает категории Эпицентра через API, а наборы характеристик и значения списков догружаются только для нужных категорий.
2. Связи. Для категории магазина выбираете категорию Эпицентра поиском по названию, а для каждой характеристики — откуда брать значение: атрибут, опция, производитель, EAN, вес и габариты (переводятся в граммы и миллиметры) или одно значение на все товары. Значения списков подставляются по названию, расхождения вроде «Рінгель» → «Ringel» сопоставляются вручную.
3. Файл. Модуль собирает XML в формате импорта Эпицентра и показывает товары, которые не попали в файл, с причиной: нет фото, пустая обязательная характеристика, значения нет в справочнике. Файл загружается в кабинете: «Импорт» → «Файл» → «Обновить всё».

Без Pro файл собирается для одной категории магазина, с Pro — для всех и пересобирается сам раз в сутки.

Файл изменившихся товаров и проверка перед импортом

Полный файл на несколько тысяч товаров кабинет обрабатывает долго, а за день в магазине меняется десяток позиций. Поэтому каждая сборка теперь пишет два файла: полный и файл только изменившихся товаров. Модуль запоминает отпечаток каждой строки <offer> и в следующий раз сравнивает с ним — в файл изменений попадают только те товары, в которых действительно что-то другое: цена, старая цена, наличие, название, фото или характеристика.

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

Файл изменений берут так же, как полный: кнопкой в админке или постоянным адресом с параметром mode=delta — его можно отдать планировщику. Чужой или пустой токен отдаёт 404, оба файла лежат в непубличной папке system/storage/cc_epicentr.

Отчёт «что кабинет отклонит»

Раньше об ошибке в файле становилось известно уже в кабинете: «Неизвестный тег shop в строке 3» — и импорт остановлен. Теперь файл проверяется до загрузки: кнопки «Проверить файл» и «Проверить файл изменений» читают готовый XML так же, как его читает Эпицентр, и называют проблему вместе с номером строки:

• посторонний тег вне того набора, который принимает кабинет, — именно та строка, на которой импорт оборвётся;
• один и тот же артикул в файле дважды — кабинет сопоставляет товар по артикулу, и вторая строка перезапишет первую;
• оффер без артикула;
• оборванный XML или не-UTF-8 строка — с номером строки;
• пустой файл или файл без единого товара.

Отдельной таблицей идут товары, которые кабинет примет, но с потерями: недоступное фото (локальный адрес, формат не jpg/png/webp, пробел в адресе), код категории, которого нет в справочнике, обрезанные название (150 символов) и описание (12 160), старая цена, которую кабинет проигнорирует, потому что после наценки и округления она уже не больше текущей, битый GTIN по контрольной сумме и необязательные характеристики, которые тихо не попадут в карточку. Такие товары импортируются — просто теперь видно, что именно из них исчезнет.

Файл изменений — возможность Pro; отпечатки считаются всегда, поэтому сразу после покупки Pro первый файл изменений уже корректен. Проверка файла работает и в бесплатной версии.

Что под капотом

Модуль работает через официальные эндпоинты Merchant API Эпицентра для обновления цен и наличия — без парсинга кабинета и без имитации входа. Токен хранится в настройках магазина в зашифрованном виде.

Состояние каждого товара — что именно отправлено и что ответил кабинет — лежит в отдельной таблице, поэтому модуль знает, что изменилось, и не шлёт лишнего. Лимит Эпицентра в 120 запросов за 2 минуты модуль соблюдает сам: если он достигнут, остальное уйдёт следующим проходом.

Для автоматики в OpenCart 4 модуль регистрирует задание в планировщике, а для более частого запуска и в OpenCart 2.3 и 3.x показывает ссылку с токеном для cron хостинга. На витрине модуль ничего не добавляет — покупатель его не видит.

Как установить

1. Загрузите архив под свою версию: в OpenCart 4.x и 3.x — через «Расширения → Установщик расширений». В OpenCart 2.3 установщик работает только через FTP, поэтому содержимое папки upload заливается в корень магазина.

2. «Расширения → Модули» → «Эпицентр: цены и наличие» → «Установить».

3. Откройте настройки, вставьте токен кабинета и нажмите «Проверить».

4. Убедитесь, что код товара в Эпицентре совпадает с артикулом или моделью на сайте, и отправьте изменения.

Если вкладки «API» в кабинете не видно, доступ к обновлению цен и наличия открывает ваш категорийный менеджер Эпицентра.