Интеграция Валдберис с Opencart

Интеграция Wildberries для OpenCart

Модуль подключает административную часть OpenCart к Wildberries Seller API. Он не меняет витрину магазина и работает с товарами, остатками, ценами, заказами и поставками через админку OpenCart.

Основные функции:

связка товаров OpenCart с карточками Wildberries по vendorCode и выбранному полю OpenCart (sku или model);
сохранение связей product_id, wb_article, nmID, chrtID, imtID;
выгрузка остатков на склад WB Marketplace;
выгрузка цен и скидки;
импорт новых заказов FBS в OpenCart;
работа с поставками FBS и этикетками;
сопоставление атрибутов OpenCart с характеристиками WB;
журналирование синхронизаций;
проверка лицензии Pluginhub.

Интерфейс админки локализован на RU, EN, KK, UZ и ZH.

Структура репозитория

В проекте лежат отдельные сборки для разных версий OpenCart:

upload/ - основная сборка для OpenCart 3.x;
2.3/upload/ - адаптер для OpenCart 2.3.x;
4.0/extension/pluginhub/ - сборка для OpenCart 4.x в формате extension vendor pluginhub;
install.xml, 2.3/install.xml, 4.0/install.xml - OCMOD-метаданные. В текущем виде они не содержат правок файлов ядра;
install.php, 2.3/install.php, 4.0/install.php - вспомогательные установочные контроллеры, не основной способ установки через админку.

Важно: не смешивайте файлы разных версий OpenCart. Устанавливайте только одну сборку, которая соответствует версии магазина.

Текущее состояние после анализа

В целом структура плагина настроена корректно: есть контроллеры админки, модель установки таблиц, библиотека WB API, библиотека лицензирования, языковые файлы и шаблоны.

Что важно учитывать перед установкой на рабочий магазин:

OpenCart 3.x - самая полная сборка: настройки, ручная синхронизация, cron, заказы, поставки, товары, маппинг и отчёты.
OpenCart 4.x содержит отдельные страницы заказов, поставок, товаров, маппинга и отчётов, но в основном контроллере не найден отдельный AJAX-экран проверки лицензии, как в 3.x. Лицензионный ключ сохраняется в настройках, а библиотека лицензии присутствует.
OpenCart 2.3 выглядит как базовый адаптер: есть синхронизация товаров, остатков и цен, но отдельные экраны заказов, поставок, маппинга и отчётов в папке 2.3 не найдены.
install.xml сейчас является только описанием модификации. Не рассчитывайте, что OCMOD автоматически изменит файлы ядра.
Uninstall по умолчанию не удаляет таблицы модуля. Это безопасно для переустановки, но важно знать при полном удалении.
Для OpenCart 3.x сохранение настроек зависит от успешной проверки лицензии: сначала проверьте ключ, затем сохраняйте настройки.
Для cron и лицензии важен один и тот же домен. Библиотека нормализует домен без www, порта и пути, но при вызове cron через другой host возможна ошибка лицензии.

Требования

OpenCart 2.3.x, 3.x или 4.x.
PHP согласно требованиям вашей версии OpenCart.
Расширение PHP curl.
Рабочий HTTPS и корректные SSL-сертификаты для запросов к Wildberries и pluginhub.pro.
Доступ сервера к https://pluginhub.pro/license-check.
Токен Wildberries Seller API с правами на нужные разделы: Content, Marketplace, Prices и Statistics.
ID склада WB Marketplace для выгрузки остатков.

Установка

Перед установкой сделайте резервную копию файлов и базы данных магазина.

OpenCart 3.x

1. Скопируйте содержимое папки upload/ в корень установленного OpenCart.
2. В админке откройте Дополнения -> Дополнения.
3. В фильтре выберите Модули.
4. Найдите Wildberries и нажмите Установить.
5. Откройте настройки модуля.
6. Введите лицензионный ключ и нажмите Проверить лицензию.
7. Заполните API-токены, URL, склад, поле сопоставления и статусы заказов.
8. Нажмите Сохранить.
9. Если на сайте используется OCMOD-кеш, обновите модификаторы.

OpenCart 2.3.x

1. Скопируйте содержимое 2.3/upload/ в корень OpenCart 2.3.
2. В админке откройте Дополнения -> Дополнения.
3. Выберите тип Модули.
4. Установите модуль Wildberries.
5. Откройте настройки, заполните токены, URL, склад и поле сопоставления.
6. Сохраните настройки.

Примечание: в OpenCart 2.3 используется параметр token, а шаблон настроек лежит в .tpl.

OpenCart 4.x

1. Скопируйте содержимое 4.0/extension/ в папку extension/ вашего OpenCart 4.
2. В админке откройте Extensions -> Extensions.
3. Выберите тип Modules.
4. Установите модуль Wildberries от vendor pluginhub.
5. Откройте настройки и заполните параметры.
6. Проверьте права группы администратора для маршрутов модуля.

Маршруты OpenCart 4.x, которым нужны права access и modify:

extension/pluginhub/module/wildberries
extension/pluginhub/module/wildberries_orders
extension/pluginhub/module/wildberries_supplies
extension/pluginhub/module/wildberries_mapping
extension/pluginhub/module/wildberries_products
extension/pluginhub/module/wildberries_reports

Первичная настройка

Рекомендуемый порядок:

1. Включите модуль только после заполнения обязательных параметров.
2. Укажите лицензионный ключ Pluginhub.
3. Для OpenCart 3.x нажмите Проверить лицензию и дождитесь успешного ответа.
4. Укажите основной WB API-токен.
5. Если используете разные токены WB, заполните отдельные поля для Content, Marketplace, Prices и Statistics.
6. Оставьте стандартные URL API, если Wildberries не требует других адресов.
7. Выберите поле сопоставления vendorCode с товаром OpenCart: sku или model.
8. Укажите ID склада WB Marketplace.
9. Настройте скидку для выгрузки цен, если она нужна.
10. При необходимости задайте фильтры товаров по цене, весу, производителям или категориям.
11. Настройте статусы заказов OpenCart для заказов WB.
12. Сохраните настройки.
13. Сначала выполните синхронизацию товаров.
14. После успешной связки карточек выполните выгрузку остатков и цен.
15. Затем синхронизируйте FBS-заказы.

Настройки API

По умолчанию используются адреса:

Content API: https://content-api.wildberries.ru
Marketplace API: https://marketplace-api.wildberries.ru
Prices API: https://discounts-prices-api.wildberries.ru
Statistics API: https://statistics-api.wildberries.ru
Common API внутри библиотеки: https://common-api.wildberries.ru

Если отдельные токены по сервисам не заданы, OpenCart 3.x подставляет основной module_wildberries_api_token как fallback для Content, Marketplace, Prices и Statistics.

Права токена WB должны соответствовать действиям:

Content - получение карточек товаров;
Marketplace - склады, остатки, FBS-заказы, этикетки и поставки;
Prices - выгрузка цен;
Statistics - отчёты и статистика.

Сопоставление товаров

Wildberries отдаёт карточки с vendorCode. Модуль ищет товар OpenCart по выбранному полю:

sku - значение по умолчанию;
model - альтернативный режим.

Если товар уже есть в таблице wildberries_products, связь может быть найдена по wb_article.

Для остатков нужен chrtID, а для цен нужен nmID. Поэтому первая обязательная операция - синхронизация товаров. Без неё выгрузка остатков и цен будет пропускать товары или завершаться с ошибками.

Синхронизация

В OpenCart 3.x доступны типы синхронизации:

products - загрузка карточек WB и сохранение связок с товарами OpenCart;
stock - выгрузка остатков на склад WB;
price - выгрузка цен и скидки;
orders - импорт новых FBS-заказов;
all - последовательный запуск включённых типов синхронизации.

Остатки выгружаются пакетами до 500 позиций. Цены выгружаются пакетами до 1000 позиций. Все результаты пишутся в wildberries_sync_log.

Cron

В OpenCart 3.x есть контроллер upload/admin/controller/cron/wildberries_sync.php.

Типовой HTTP-вызов:

https://example.com/admin/index.php?route=cron/wildberries_sync

Перед включением cron:

1. Проверьте лицензию.
2. Включите модуль.
3. Включите автоматическую синхронизацию.
4. Укажите интервал module_wildberries_sync_interval в минутах.
5. Убедитесь, что включены нужные флаги синхронизации: товары, остатки, цены, заказы.

Cron сам проверяет:

действительность лицензии;
статус модуля;
включена ли автоматическая синхронизация;
прошёл ли заданный интервал с последнего запуска.

Рекомендуется вызывать cron с того же домена, на который активирована лицензия.

Заказы FBS

Модуль получает новые FBS-заказы через Marketplace API и создаёт заказы OpenCart. Для заказа сохраняется связь с WB-заказом в таблице wildberries_orders.

Если товар найден по nmID или артикулу, в заказ попадёт связанный товар OpenCart. Если товар не найден, заказ всё равно может быть создан с техническими данными WB.

Для корректной работы задайте статусы:

новый заказ;
в обработке;
отправлен;
доставлен;
отменён.

Поставки и этикетки

Сборки OpenCart 3.x и 4.x содержат отдельные контроллеры для поставок и заказов. Через Marketplace API доступны операции:

список поставок;
создание поставки;
добавление заказа в поставку;
закрытие поставки;
получение этикеток заказов.

Для этих действий токен Marketplace должен иметь соответствующие права.

Сопоставление атрибутов

Модуль содержит таблицу wildberries_attr_map, где можно хранить соответствие:

attribute_id OpenCart;
wb_charc_id Wildberries;
разделитель значения split;
порядок сортировки.

Это нужно для подготовки характеристик WB на основе атрибутов OpenCart.

Таблицы базы данных

При установке модуль создаёт служебные таблицы с префиксом OpenCart:

wildberries_products - связи товаров OpenCart с карточками WB;
wildberries_orders - связи заказов WB и OpenCart;
wildberries_stock - служебные остатки;
wildberries_sync_log - журнал синхронизаций;
wildberries_attr_map - сопоставление атрибутов;
wildberries_warehouses - локальный список складов WB.

При удалении модуля таблицы по умолчанию не удаляются. Чтобы удалить их при uninstall, настройка module_wildberries_uninstall_drop_tables должна быть равна 1.

Лицензия Pluginhub

Проверка лицензии выполняется через:
https://pluginhub.pro/license-check

В OpenCart 3.x есть кнопка проверки лицензии в настройках модуля. После успешной проверки сохраняются:

module_wildberries_license_valid;
module_wildberries_license_expires;
module_wildberries_license_verified;
module_wildberries_license_domain;
module_wildberries_license_hash.

Если сервер Pluginhub временно недоступен, библиотека использует локальную проверку по ранее сохранённым данным. Если домен изменился, локальная проверка может вернуть ошибку License domain mismatch.

Проверка после установки

После установки проверьте:

1. Модуль установлен и включается без ошибок.
2. Лицензия успешно проверяется.
3. Тест соединения с WB API проходит успешно.
4. В базе созданы таблицы wildberries_.
5. Поле vendorCode в WB совпадает с sku или model в OpenCart.
6. Задан корректный ID склада WB.
7. Синхронизация товаров создаёт записи в wildberries_products.
8. После синхронизации товаров у записей есть nmID и, для остатков, chrtID.
9. Выгрузка остатков не возвращает ошибку по складу.
10. Выгрузка цен создаёт задачу WB Prices API.
11. Импорт FBS-заказов создаёт записи в wildberries_orders.
12. В wildberries_sync_log появляются записи по каждому запуску.

Частые проблемы

Настройки не сохраняются в OpenCart 3.x

Проверьте лицензию через кнопку Проверить лицензию, затем сохраните настройки. В контроллере 3.x метод сохранения вызывает проверку лицензии.

Ошибка лицензии в cron

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

Остатки не выгружаются

Проверьте:

указан ID склада WB Marketplace;
перед выгрузкой остатков выполнена синхронизация товаров;
у товаров есть chrtID;
токен Marketplace имеет права на работу с остатками.

Цены не выгружаются

Проверьте:

перед выгрузкой цен выполнена синхронизация товаров;
у товаров есть nmID;
цена товара больше нуля;
токен Prices имеет нужные права.

Товары не связываются

Проверьте, что vendorCode карточки WB совпадает с выбранным полем товара OpenCart. По умолчанию используется sku.

Нет доступа к страницам модуля

Проверьте права группы администратора. Особенно это важно для OpenCart 4.x и отдельных маршрутов заказов, поставок, товаров, маппинга и отчётов.

Рекомендации перед продакшеном
Сначала протестируйте модуль на копии магазина.
Проверьте WB-токены с минимально необходимыми правами.
Не включайте автоматическую синхронизацию, пока ручные операции не проходят успешно.
Начните с небольшой группы товаров через фильтры.
Проверьте журнал wildberries_sync_log после каждого типа синхронизации.
Перед полным удалением решите, нужно ли сохранять таблицы wildberries_.