WPWB — интеграция Woocommerce и Wildberries

Двусторонняя интеграция одного магазина на WooCommerce с одним кабинетом продавца Wildberries: карточки товаров, цены и остатки, заказы FBS/FBO, отзывы и вопросы покупателей.

00О плагине

WPWB связывает каталог товаров, цены, остатки, заказы и обратную связь покупателей между вашим сайтом на WooCommerce и продавцовским кабинетом Wildberries. Работа идёт через официальный Seller API WB — плагин ничего не «парсит» и не эмулирует браузер, только обращается к документированным (и нескольким служебным недокументированным, но подтверждённым вживую) методам API.

Плагин рассчитан на простую конфигурацию: один сайт WordPress — один кабинет WB, один API-токен. Если у вас несколько кабинетов WB или несколько сайтов на одном магазине — потребуется отдельная установка плагина на каждый сайт.

01Требования

• WordPress 6.0 или новее. 
• WooCommerce 8.0 или новее. Плагин совместим с HPOS (новым хранилищем заказов) и объявляет эту совместимость явно.
• PHP 8.0 или новее.
• Расширение PHP libsodium — им шифруется API-токен перед сохранением в базу.
• Действующий кабинет продавца Wildberries и API-токен с доступом к категориям: Контент, Цены и скидки, Маркетплейс, Статистика, Вопросы и отзывы.

02Установка

1. Загрузите и активируйте плагинКак обычный плагин WordPress — через Плагины → Добавить новый → Загрузить либо копированием папки в wp-content/plugins/. При активации плагин сам создаёт шесть собственных таблиц в базе данных (карточки товаров, заказы, отзывы, сопоставления категорий и характеристик, журнал синхронизации) — вручную ничего создавать не нужно.
2. Проверьте, что WooCommerce активенЕсли WooCommerce выключен или не установлен, плагин покажет уведомление в админке и не будет инициализироваться, пока WooCommerce не появится.
3. Откройте настройки плагинаПункт меню появится под основным меню WooCommerce в боковой панели админки — раздел «Wildberries» и несколько подпунктов «WB — …».

03Быстрый старт

Минимальный путь от установки до первого товара, отправленного на Wildberries. Каждый шаг подробно раскрыт в своей главе — здесь только последовательность.

1. Сохраните API-токен Экран Wildberries. Для первого знакомства с плагином настоятельно рекомендуется тестовый токен песочницы, а не боевой.
2. Сопоставьте категорию Экран WB — категории — свяжите хотя бы одну категорию WooCommerce с предметом (subject) WB.
3. Настройте характеристики предмета В той же панели — какой атрибут Woo считать размером, какие (если есть, можно несколько) — группирующими, и сверьте значения атрибутов со справочниками WB, если характеристика в реестре справочников.
4. Отправьте товар на WB Экран WB — товары, вкладка «Товары WooCommerce» → кнопка Отправить на WB на строке товара.
5. Проверьте результат Статус строки товара сменится на «Синхронизирован» (карточка создаётся на WB асинхронно, обычно занимает от нескольких секунд до пары минут — если статус завис на «Ожидание nmID от WB», нажмите Проверить статус ещё раз чуть позже).

04Экран «Wildberries»

  Главный экран настроек. Две вкладки: Настройки и Журнал (журнал разобран отдельно, в главе «Журнал синхронизации»).  

Токен и режим песочницы

Поле API-токен WB — токен из личного кабинета продавца. Поле типа «пароль»: значение скрыто, а если оставить его пустым и нажать «Сохранить» — уже сохранённый токен не будет затронут (это защита от случайной перезаписи, а не обязательное повторение при каждом сохранении настроек). Ниже поля плагин показывает статус: «Токен сохранён (оканчивается на «…»), обновлён <дата>» либо «Токен ещё не сохранён». Сам токен в базе хранится не в открытом виде, а зашифрованным.

Чекбокс Тестовый токен (песочница) переключает все запросы плагина на sandbox-хосты Wildberries (у каждого модуля API есть двойник с суффиксом -sandbox). Пока чекбокс включён — ни один запрос не уходит в боевой кабинет, это безопасный режим для освоения плагина и тестирования сопоставлений.

Кнопка Проверить токен делает контрольный запрос к API (в боевом режиме — простой ping, в песочнице — через Content API, так как у ping нет sandbox-версии) и сообщает, действителен ли токен.

Склад FBS и бренд по умолчанию

Поле Склад FBS по умолчанию — ID склада, на который плагин будет отправлять остатки товаров при продаже со своего склада (FBS). Кнопка Загрузить список складов подтягивает реальные склады продавца из кабинета WB и подставляет выпадающий список вместо ручного ввода ID.

Пока склад не выбран, отправка остатков не работает — плагин честно сообщает об этом статусом «partial» при синхронизации цены/остатка (цена при этом всё равно уходит).

05Экран «WB — Категории»

Здесь плагин связывает ваш каталог с моделью данных Wildberries. Без сопоставления хотя бы категории и (при необходимости) характеристики размера ни один товар этой категории не удастся отправить на WB — попытка вернёт понятную ошибку с прямой ссылкой сюда же.

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

Таблица со всеми категориями товаров WooCommerce. Для каждой — поле с автодополнением: начните вводить название и выберите подходящий предмет (subject) из справочника WB, затем нажмите Сохранить. Кнопка Характеристики становится доступна только после того, как категория сопоставлена.

Характеристики предмета

Разворачивающаяся панель со всеми характеристиками, которые WB допускает для этого предмета. Для каждой строки можно выбрать атрибут WooCommerce, которым она заполняется, и отметить один из двух флажков (в рамках одной строки они взаимоисключающие — характеристика не может быть одновременно и «размером», и «группирующей»):

• Это размер? — значение атрибута уходит в размерную сетку карточки (sizes[]), а не в обычные характеристики. На предмет допускается не больше одной такой характеристики.
• Группирует по карточкам WB? — по значению этого атрибута вариации товара Woo разбиваются на отдельные карточки (nmID) внутри одной объединённой карточки WB. В отличие от «Это размер?», эту галочку можно поставить сразу на нескольких строках — каждая отмеченная характеристика станет своей собственной осью вариации (например, «Цвет» и «Длина предмета» одновременно). Плагин не пытается угадать, какая характеристика на самом деле различает варианты — вы указываете это явно, сколько характеристик нужно, столько и отмечаете. Подробно эта модель разобрана в главе «Как WB видит товар».

Справочники допустимых значений

Часть характеристик WB принимает значение только из закрытого справочника, а не произвольный текст — это нигде не помечено в самом API (кроме официального списка из шести названий) и обычно узнаётся только после того, как WB молча отклонит создание карточки. Плагин знает шесть таких характеристик и умеет сверять их заранее:

Если характеристика сопоставлена с одной из шести и находится в этом реестре, рядом с ней в панели появляется кнопка Проверить значения — она сверяет все текущие термины сопоставленного атрибута Woo со справочником WB и показывает, какие из них не пройдут («карточка с таким значением будет молча отклонена»).

06Как WB видит товар

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

imtID — объединённая карточка→nmID — вариант (обычно цвет)→chrtID — размер внутри варианта

• imtID — объединённая карточка, «витрина» товара на WB. Может объединять несколько nmID.
• nmID — конкретная номенклатура (в подавляющем большинстве случаев — один цвет). У простого товара без цветовых вариаций один nmID и один imtID совпадают по смыслу «один в один».
• chrtID — конкретный размер внутри nmID. У безразмерного товара один chrtID на nmID.

В плагине это соответствует двум разным путям экспорта, которые выбираются автоматически по настройке характеристик предмета (глава «Характеристики предмета»):  

• Простой путь — если ни одна характеристика предмета не отмечена «Группирует по карточкам WB?». Товар (или все его вариации, если различаются только размером) становится одной карточкой с одним nmID; размерные вариации превращаются в sizes[] внутри неё.
• Путь объединённой карточки — если отмечена хотя бы одна такая характеристика. Вариации Woo группируются по значению всех отмеченных характеристик сразу (например, по цвету — а если отмечено несколько, то по их сочетанию), каждая уникальная комбинация становится отдельным nmID под общим imtID.

При импорте с WB в Woo действует зеркальное правило: товар с одним nmID (и, возможно, несколькими размерами) становится простым или вариативным товаром Woo с одной осью атрибута «размер»; объединённая карточка с несколькими nmID становится вариативным товаром, у которого по одной оси на каждую характеристику, отмеченную «Группирует» для этого предмета (названной её настоящим именем — «Цвет», «Длина предмета» и т.д.), плюс отдельная необязательная ось «WB размер», если у карточек есть реальная размерная сетка. Если на момент импорта для предмета ещё не отмечено ни одной группирующей характеристики, используется запасная ось «WB вариант» по артикулу варианта — просто чтобы вариации не совпадали друг с другом, без претензии на содержательное название.

07Экран «WB — Товары»

Основной рабочий экран. Две вкладки: Товары WooCommerce (экспорт Woo → WB) и Карточки WB (не сопоставлены) (импорт WB → Woo).

Экспорт: вкладка «Товары WooCommerce»

Список товаров вашего каталога (опубликованных и черновиков) с колонками «Статус WB» и «Последняя синхронизация». Действие на строке зависит от текущего состояния:

Если у товара несколько вариантов WB (объединённая карточка), статус выглядит как «Синхронизирован (N вариантов WB)».

Массовый экспорт

Кнопка Экспортировать все несопоставленные в верхней части вкладки. Запускает фоновую очередь: находит все товары каталога, у которых ещё нет ни одной карточки на WB, и отправляет их пачками, объединяя простые (без группировки по цвету) товары в общие запросы к API вместо запроса на каждый товар — так соблюдается лимит частоты запросов даже на каталоге в тысячи позиций.

Под кнопкой появляется строка прогресса «Обработано N из M…», которая обновляется каждые несколько секунд, пока задача выполняется в фоне (можно закрыть вкладку — обработка продолжится). Причины ошибок по конкретным товарам (например, несопоставленная категория) пишутся в журнал синхронизации.

Импорт: вкладка «Карточки WB (не сопоставлены)»

Кнопка Обновить список из WB загружает карточки продавца, ещё не связанные ни с одним товаром Woo, сгруппированные по imtID — одна строка списка может представлять сразу несколько вариантов (nmID). Кнопка Импортировать на строке создаёт товар Woo черновиком: простой или с одной осью «размер» для одиночной карточки; для объединённой — вариативный, с одной осью на каждую характеристику предмета, отмеченную «Группирует по карточкам WB?» (см. главу «Характеристики предмета»), плюс отдельная ось «WB размер», если у карточек есть реальная размерная сетка. Если ни одна характеристика предмета ещё не отмечена галочкой на момент импорта — используется одна запасная ось «WB вариант» по артикулу.

Чекбокс Показывать все карточки WB (в т.ч. уже сопоставленные) переключает список в полный режим: появляется колонка «Статус» — ссылка на товар Woo, если карточка уже привязана и товар существует, либо пометка «товар удалён» с кнопкой Убрать привязку, если товар был удалён из Woo напрямую (не через плагин) в обход автоматической очистки связей.

Что переносится при импорте, а что нет

• Цена — переносится: плагин подтягивает текущую цену (и скидку, если она реально применена) отдельным запросом к Prices API и сразу проставляет её товару.
• Название, описание, фото, характеристики, размеры — переносятся из карточки как есть.
• Остаток — не переносится. FBS-остаток относится к складу продавца, а не к самой карточке; импортированный товар остаётся черновиком, пока вы не заполните остаток вручную (модуль «Цены и остатки») и не опубликуете его.

Массовый импорт

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

Чекбокс Импортировать только для наполнения каталога — без дальнейшей автоматической синхронизации цены/остатка, расположенный над списком, действует и на одиночный, и на массовый импорт — см. следующий раздел.

Синхронизация цены/остатка: включить или выключить точечно

По умолчанию любой сопоставленный товар (созданный в Woo или импортированный с WB) участвует в автоматической синхронизации цены и остатка: при каждом сохранении товара в Woo и при плановой сверке раз в 30 минут плагин отправляет актуальные данные на WB.

Это не всегда нужно — например, если вы импортируете каталог с WB только для того, чтобы не заполнять карточки товаров вручную, а ценами и остатками продолжаете управлять напрямую в кабинете WB. Для этого случая:

• чекбокс «только для наполнения каталога» на вкладке «Карточки WB» — отключает синхронизацию сразу при импорте;
• переключатель Синхр. цена/остаток под кнопками действий на строке товара на вкладке «Товары WooCommerce» — включает и выключает синхронизацию в любой момент для уже сопоставленного товара.

Отключение синхронизации не разрывает саму связь с карточкой WB — сопоставление nmID/imtID остаётся, поэтому заказы и отзывы по этому товару по-прежнему находят нужный товар Woo. Не отправляется только цена/остаток.

08Экран «WB — Цены и остатки»

Кнопка Сверить всё сейчас запускает полную сверку по всем товарам, у которых уже есть карточка на WB и включена синхронизация — то же самое, что происходит автоматически каждые 30 минут, но по требованию. По завершении показывает счётчики: сколько синхронизировано, сколько частично (нет выбранного склада FBS — цена ушла, остаток нет) и сколько с ошибкой.

Раздел «Остатки FBO (информационно)» и кнопка Обновить остатки FBO показывают остатки на складах самого WB (Statistics API) — это данные только для просмотра, плагин их не редактирует и не влияет на них: в отличие от FBS, где источник истины — ваш магазин, для FBO источник истины — сам WB.

09Экран «WB — Заказы»

Кнопка Проверить новые заказы забирает новые сборочные задания FBS с WB и создаёт по каждому заказ Woo. Один заказ WB — это всегда ровно одна единица товара (так устроен API маркетплейса), поэтому один заказ Woo от плагина всегда содержит одну позицию с количеством 1; товар в заказе определяется по chrtID, и если он не сопоставлен ни с одним товаром Woo, заказ пропускается с понятной причиной в журнале.

Кнопка Обновить статусы подтягивает изменившиеся статусы уже созданных заказов и переносит их на заказ Woo:

new → processing → confirm → processing → complete → completed

Переход confirm наступает не сам по себе, а когда сборочное задание добавлено в поставку (глава «WB — Поставки»); переход complete — когда поставка передана в доставку.

Кнопка Состав на строке заказа открывает окно с позициями, суммой, адресом доставки, комментарием покупателя, номером сборочного задания и поставки, а также ссылкой на сам заказ Woo.

Раздел «Заказы FBO (только просмотр)» и кнопка Загрузить заказы FBO — заказы со склада самого WB; в отличие от FBS они не создают заказы Woo, это справочная информация из Statistics API.

10Экран «WB — Поставки»

Раздел «Сборочные задания без поставки» — отметьте нужные чекбоксами, задайте название и нажмите Создать поставку из выбранных. Именно этот шаг переводит задания в статус confirm — отдельного действия «подтвердить сборку» в API WB не предусмотрено, подтверждение и есть добавление в поставку.

Раздел «Поставки» (кнопка Загрузить список поставок) — для каждой поставки доступны:

• Состав — список входящих в неё заданий;
• Передать в доставку (пока поставка не закрыта) — закрывает поставку на стороне WB и переводит все её заказы в статус complete → Woo completed;
• QR-код (после того как поставка закрыта) — короткий код для сдачи поставки на приёмку в WB.

11Экран «WB — Отзывы и вопросы»

Две вкладки — Отзывы и Вопросы, у каждой фильтр по статусу. Новые неотвеченные подтягиваются автоматически каждые 30 минут; кнопка Проверить новые делает то же самое по требованию.

На карточке неотвеченной записи — поле для текста ответа и кнопка Ответить. У вопросов есть вторая кнопка, Отклонить: покупатель получает уведомление с вашим текстом, но сам вопрос и ответ на сайте не публикуются (у отзывов такой операции в API WB не существует, поэтому кнопки отклонения там нет).

Кнопка Загрузить историю (отвеченные/отклонённые) подтягивает по требованию записи, на которые уже ответили — в том числе если ответили напрямую в кабинете WB, а не через плагин. Это разовое действие, оно не входит в автоматический 30-минутный поллинг, чтобы не тянуть всю историю переписки каждый раз.

12Журнал синхронизации

Вкладка Журнал на экране «Wildberries». Единая лента событий по всем модулям — сюда пишется вообще всё: и обычные информационные события («карточка создана»), и предупреждения, и ошибки с точным текстом, который вернул WB.

Фильтры по модулю и уровню (Информация / Предупреждение / Ошибка). У части ошибок под сообщением есть разворачиваемый блок Контекст с сырыми техническими деталями запроса — полезно, если нужно разобраться в проблеме глубже, чем позволяет текст сообщения.

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

13Автоматическая синхронизация

Все фоновые задачи работают через Action Scheduler (тот же механизм, что использует сам WooCommerce) — отдельная настройка не требуется, но для их выполнения в срок сайту нужен обычный поток посетителей или настроенный системный cron, как для любых WP-задач.

При ошибке «превышен лимит запросов» (HTTP 429) плановая отправка не теряется — задача переставляется на время, которое подсказал сам ответ WB (заголовок Retry-After), максимум 5 попыток подряд.

14Известные ограничения

• Нет поддержки обязательной маркировки товаров («Честный знак», УИН, IMEI, GTIN, декларации соответствия) — для категорий, где она обязательна, карточки нужно доводить до готовности к продаже вручную в кабинете WB.
• Нет работы с пропусками на склад WB и грузоместами для сдачи через ПВЗ (см. главу «Поставки»).
• Заказы FBO старше примерно четырёх месяцев недоступны через Statistics API — это ограничение самого WB, не плагина.
• Закреплённые (продвигаемые) отзывы не поддерживаются — эта функция WB доступна только на платных тарифах продвижения.
• Для товаров без включённого управления остатком в WooCommerce на WB уходит условное большое число (999), если товар «в наличии», и 0 — если «нет в наличии»: WooCommerce в этом режиме не хранит точное количество, а WB требует целое число.
• Цена в объединённой карточке задаётся на уровне варианта (nmID) целиком, а не по каждому размеру отдельно.
• Один сайт — один кабинет WB.

15Решение проблем

Карточка отправлена, но не появляется на WB, и ошибки в журнале нет

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

«Категория не сопоставлена с предметом WB»

Зайдите на WB — категории и сопоставьте категорию товара (или любую из его категорий, если их несколько).

«Недопустимое значение цвета» / аналогичная ошибка по другой характеристике

Значение атрибута не входит в справочник WB — см. главу «Справочники допустимых значений» и кнопку Проверить значения.

«Для данной категории товара необходимо заполнить поле Размер»

У предмета есть реальная размерная сетка, даже если сам WB не пометил характеристику «Размер» обязательной. Сопоставьте атрибут-размер и включите «Это размер?» в панели характеристик.

«Цена (…) должна находиться в диапазоне 50–999999»

У WB есть собственный минимум и максимум цены — поднимите цену товара выше нижней границы (обычно актуально при тестировании на демо-данных с символическими ценами).

«WB API rate limit exceeded» в журнале

Обычная защита от превышения частоты запросов — задача сама переставится и повторится (см. главу «Автоматическая синхронизация»). Если это происходит регулярно именно с модулем «reviews» — см. предупреждение про тип токена в главе «Отзывы и вопросы».

Удалил импортированный товар в Woo, а карточка так и не появляется среди непривязанных

При удалении товара плагин сам убирает связь с карточкой WB. Если это произошло до обновления плагина или связь осталась по иной причине — включите чекбокс Показывать все карточки WB на вкладке «Карточки WB», найдите строку с пометкой «товар удалён» и нажмите Убрать привязку.

Сообщение об успехе, но счётчик «Обработано: 0»

Сообщение о ходе выполнения массового экспорта/импорта могло обновиться в момент между началом и концом обработки последней пачки — сама операция при этом продолжает идти или уже завершена корректно; откройте журнал синхронизации или обновите список, чтобы увидеть фактический результат.

16Глоссарий

Идентификатор объединённой карточки WB — может включать несколько nmID.

nmID

Идентификатор номенклатуры (варианта) внутри объединённой карточки — обычно один цвет.

chrtID

Идентификатор конкретного размера внутри nmID.

vendorCode

Артикул продавца — то, что связывает карточку WB с товаром в вашей системе (у плагина это, как правило, SKU товара Woo).

FBS

Fulfillment by Seller — продажа со склада продавца; остатком и сборкой заказа управляете вы.

FBO

Fulfillment by Operator — продажа со склада WB; в плагине доступно только для просмотра.

Сборочное задание

Единица заказа на стороне WB — всегда один товар в одном экземпляре.

Песочница (sandbox)

Тестовый контур WB с отдельными хостами API и собственным жёстким лимитом в 1 запрос/сек.17

17Для разработчиков

Краткая техническая справка — подробности читайте в исходном коде, он сопровождён докблоками именно с расчётом на это.

• Пространство имён WPWB\, автозагрузка PSR-4 из includes/ (с собственным fallback-автозагрузчиком, если Composer не разворачивался).
• Собственные таблицы: wpwb_product_map, wpwb_order_map, wpwb_reviews, wpwb_category_map, wpwb_attribute_map, wpwb_sync_log.
• Все фоновые задачи — Action Scheduler, группа wpwb.
• API-клиенты по одному на модуль Wildberries: ContentClient, PricesClient, MarketplaceClient, StatisticsClient, FeedbacksClient — все поверх общего Api\Client, который отвечает за авторизацию, троттлинг песочницы и разбор ошибок.
• Токен хранится в опции wpwb_settings зашифрованным через libsodium; ключ шифрования выводится из константы сайта AUTH_KEY.