Интеграция WooCommerce с Wildberries API

Интеграция WooCommerce с Wildberries нужна, когда интернет-магазин продаёт один ассортимент на собственном сайте и на маркетплейсе, а карточки, цены, остатки и заказы приходится обслуживать в нескольких системах. Пока товаров мало, часть операций можно делать вручную. По мере роста каталога это приводит к расхождениям и повторной работе.

Wildberries предоставляет API для автоматизации процессов продавца. Но рабочая интеграция — это не один запрос к endpoint. Сначала нужно определить источник истины для товара, цены и остатка, выбрать стабильные идентификаторы и продумать повторные запросы, ошибки и журналирование.

Что можно автоматизировать через Wildberries API

Официальная документация Wildberries разделяет API по направлениям работы продавца. Для связки с WooCommerce обычно интересны операции вокруг карточек товаров, характеристик, медиа, цен, складов, остатков и заказов.

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

Не каждому магазину нужна двусторонняя синхронизация всех сущностей. Иногда WooCommerce является главным каталогом, а Wildberries только получает часть данных. В другом проекте источник истины может находиться в 1С, МойСклад или другой ERP, а WooCommerce и маркетплейс будут двумя отдельными каналами.

Токен Wildberries должен храниться на сервере

Для работы с API продавец создаёт API-токен с нужными правами доступа. Такой токен нельзя помещать в JavaScript фронтенда, HTML страницы или публичные настройки темы.

Запросы лучше выполнять на сервере: через отдельный WordPress-плагин, backend-сервис, Worker или VPS. Там же можно централизованно хранить настройки, журналировать ответы API и контролировать повторные попытки.

Базовая архитектура интеграции

WooCommerceХранит товары, вариации и заказы сайта
Интеграционный слойПроверяет данные, хранит token и вызывает Wildberries API
Таблица соответствийСвязывает WooCommerce ID и SKU с идентификаторами Wildberries
Wildberries APIПринимает изменения каталога, цен и остатков и отдаёт данные продавца
Логи и retryФиксируют ошибки и безопасно повторяют операции

Главная задача — стабильное сопоставление товаров

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

На стороне WooCommerce обычно используют product ID, variation ID и SKU. На стороне Wildberries API встречаются собственные идентификаторы карточек и размеров. Конкретный набор зависит от метода API, поэтому интеграционный слой должен хранить необходимые соответствия после создания или первого сопоставления товара.

Это важно для idempotency: повторная синхронизация должна обновить уже известную карточку, а не попытаться создать ещё одну.

Карточки товаров: сначала категории и характеристики

Перед массовой выгрузкой каталога нужно сопоставить структуру WooCommerce с требованиями Wildberries. Для разных предметов и категорий набор обязательных характеристик отличается.

В WooCommerce данные могут лежать в стандартных attributes, custom fields, ACF, свойствах вариаций или внешней ERP. Интеграция должна собрать их в формат, который ожидает конкретный API-метод Wildberries.

Что проверить перед выгрузкой каталога

какой WooCommerce товар соответствует какой категории или предмету Wildberries;
какие характеристики обязательны;
какие атрибуты относятся к общей карточке, а какие к variation;
откуда брать бренд, габариты, состав и другие данные;
какие изображения отправлять и в каком порядке;
как сохранять идентификаторы, которые вернул Wildberries;
что считать ошибкой всей карточки, а что можно повторить отдельно.

Цена должна иметь одного владельца

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

Если цена редактируется в WooCommerce, интеграция может отправлять рассчитанное значение на Wildberries. Если прайс приходит из ERP, лучше использовать её как первичный источник. Иначе появляются цепочки, где одна система перезаписывает другую, а понять происхождение значения становится сложно.

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

Остатки: выбираем источник истины до написания кода

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

В Wildberries API есть методы работы с остатками на складах продавца. Для интеграции нужно определить warehouse, модель продаж и систему, которая владеет доступным количеством. Если главным складским учётом является WooCommerce, он может передавать доступный остаток. Если учёт ведётся в ERP, логичнее синхронизировать оба канала оттуда.

Двусторонняя запись одного stock quantity без правил часто создаёт циклы. Надёжнее иметь одного владельца остатка и фиксировать время или версию последнего успешного обновления.

Заказы Wildberries в WooCommerce нужны не всегда

Иногда бизнес хочет видеть все продажи в одной админке и поэтому создаёт WooCommerce order для внешнего заказа. В других случаях заказы нужно передавать напрямую в CRM или складскую систему, а WooCommerce вообще не должен быть промежуточным звеном.

Перед разработкой важно ответить, зачем внешний заказ нужен сайту: для резерва, печати документов, общей аналитики, уведомлений, CRM или складского учёта. От ответа зависит архитектура.

Если внешний заказ создаётся в WooCommerce, нужно сохранить его источник и внешний ID, чтобы повторное получение того же события не создало дубль.

Idempotency защищает от двойных операций

API-запрос может завершиться timeout после того, как удалённая сторона уже приняла данные. Cron может запуститься повторно. Администратор может вручную нажать синхронизацию ещё раз. Поэтому повторный запуск — нормальный сценарий, а не исключение.

Для каждого типа операции нужен стабильный ключ. При импорте заказа это внешний order ID. При обновлении карточки — сохранённое соответствие идентификаторов. При массовой задаче — запись состояния партии или очереди.

Без idempotency интеграция работает до первой сетевой ошибки, после которой начинает создавать дубли или повторно выполнять бизнес-действия.

Rate limits и ошибки должны быть частью архитектуры

Wildberries API имеет ограничения и правила для разных групп методов. Их нужно читать в актуальной документации перед реализацией конкретного сценария.

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

Что должно попадать в журнал синхронизации

тип операции;
WooCommerce ID и внешний идентификатор;
время запроса;
результат и HTTP status;
короткое сообщение API без сохранения секретов;
номер попытки;
дата следующего retry, если он нужен;
признак ручного вмешательства.

Почему не стоит делать всё одним WP-Cron

Небольшой каталог можно обслуживать простой очередью и расписанием. Для большого объёма товаров лучше делить операции на партии и не пытаться отправить весь каталог в одном HTTP-request.

Задача должна уметь продолжиться после ошибки, не запускать две одинаковые партии параллельно и не блокировать обычные запросы пользователей сайта. Для некоторых проектов достаточно Action Scheduler или собственного cron-механизма; для других лучше отдельный worker.

WooCommerce + Wildberries + Ozon: один интеграционный слой лучше трёх несвязанных

Если магазин работает сразу с несколькими каналами, полезно заранее унифицировать модель данных: SKU, источники цены и остатка, статусы заказов и формат логов. Недавно я подробно разбирал интеграцию WooCommerce с Ozon Seller API. У Wildberries свои endpoints и идентификаторы, но архитектурный принцип похож: один источник истины, явное сопоставление сущностей и безопасные повторные операции.

Для массовой подготовки каталога также может понадобиться отдельный этап импорта товаров в WooCommerce, прежде чем подключать маркетплейсы.

Что нужно для оценки интеграции

Стоимость и срок зависят не только от количества товаров. Важнее количество направлений синхронизации, вариаций, источников данных и бизнес-сценариев.

Что прислать разработчику

ссылку на WooCommerce-магазин;
пример 3–5 типовых товаров и вариаций;
описание модели работы на Wildberries;
какая система является источником товара, цены и остатка;
что именно нужно синхронизировать;
нужно ли создавать внешние заказы в WooCommerce;
какая ERP или CRM уже участвует в процессе;
нужна ли ручная кнопка повторной синхронизации;
какие ошибки должен видеть менеджер.

Итог

Интеграция WooCommerce с Wildberries API позволяет убрать часть ручного дублирования, но стабильность определяется не самим фактом подключения API. Нужны карта данных, серверное хранение токена, устойчивые идентификаторы, idempotency, очереди, логи и понятный источник истины для цены и остатка.

Если нужна такая интеграция, можно описать задачу A.S Groups: какие данные сейчас находятся в WooCommerce, как устроена работа на Wildberries и что должно обновляться автоматически. После этого можно оценить реальный объём разработки без обещаний универсальной синхронизации вслепую.

Официальные источники

Следующий шаг

Нужно решить похожую задачу?

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

Обсудить задачу