Епіцентр: ціни й наявність для 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» в кабінеті не видно, доступ до оновлення цін і наявності відкриває ваш категорійний менеджер Епіцентру.