Синхронизация остатков WooCommerce с внешней системой: как избежать дублей и отрицательного склада

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

Если архитектура не определяет источник истины и правила повторной обработки, магазин рано или поздно показывает неверный остаток. Это приводит к продаже отсутствующего товара, отменам заказов и ручной сверке между сайтом и складом.

Ниже разберу, как строится надёжная синхронизация остатков WooCommerce с ERP, складской системой или любым внешним API.

Сначала определить источник истины

Самый важный вопрос — где хранится окончательный остаток. Если сотрудники могут независимо менять количество и в WooCommerce, и в учётной системе, автоматическая синхронизация превращается в гонку: системы начинают перезаписывать друг друга.

В большинстве проектов источником истины становится склад или ERP. WooCommerce показывает клиенту состояние, полученное из этой системы, а новые заказы передают наружу информацию о необходимости резервирования или списания.

Иногда источником истины остаётся WooCommerce, например для небольшого интернет-магазина без отдельной ERP. Это тоже рабочая схема, но она должна быть явно зафиксирована.

SKU должен однозначно связывать товары

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

Чаще всего используется SKU, артикул или внешний ID. Для вариативных товаров ключ должен храниться на уровне каждой variation, если склад учитывает варианты отдельно.

Если соответствия нет, интеграция должна явно зафиксировать ошибку, а не пытаться угадать товар по похожему имени.

Webhook или периодическая синхронизация

Webhook быстрее реагирует на изменения и уменьшает количество пустых запросов. Но полагаться только на него рискованно: внешняя система может не доставить событие, сеть может быть недоступна, а endpoint — временно отвечать ошибкой.

Поэтому для критичных остатков полезна гибридная схема: webhooks дают быстрые обновления, а периодическая сверка проверяет расхождения и восстанавливает пропущенные изменения.

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

Почему нельзя просто прибавлять и вычитать

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

Например, webhook «остаток стал 12» можно обработать несколько раз, и итог останется 12. А webhook «вычесть 2» при повторной доставке превратит 12 сначала в 10, потом в 8.

Если API работает только с дельтами, интеграции нужен стабильный ID операции и журнал уже применённых изменений.

Idempotency защищает склад от повторной обработки

Повтор события — штатная ситуация. Внешний сервис может отправить webhook снова, если не получил подтверждение вовремя. Очередь может повторить задачу после временного сбоя. Запрос может завершиться таймаутом уже после того, как сервер принял изменение.

Поэтому каждая операция должна иметь idempotency key или другой стабильный идентификатор. Перед применением изменения система проверяет, не было ли оно уже подтверждено.

event_key = "warehouse-stock-987654"

if already_processed(event_key):
    return

update_woocommerce_stock(sku, quantity)
mark_processed(event_key)

Реальная реализация может хранить ключ в отдельной таблице, custom post type или интеграционном сервисе. Главное — обеспечить атомарную проверку.

Что происходит во время заказа

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

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

Если внешняя ERP умеет резервировать товар, полезно отправлять туда резерв и получать подтверждение. Если не умеет, правила уменьшения WooCommerce stock должны быть согласованы с тем, как склад списывает заказ.

Вариативные товары требуют отдельного внимания

У родительского товара WooCommerce и его variations могут быть разные настройки управления запасами. Если склад учитывает размеры, цвета или комплектации отдельно, интеграция должна работать с каждой variation по её собственному SKU.

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

Как обрабатывать ноль и отрицательные значения

Внешний API может временно вернуть отрицательное количество из-за внутреннего резерва или особенностей расчёта. Нельзя бездумно отправлять это число в WooCommerce.

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

Если магазин разрешает предзаказ, отрицательное физическое количество и доступность для продажи — это разные понятия. Их лучше не смешивать в одном поле.

Очереди нужны для больших каталогов

Обновлять тысячи товаров одним HTTP-запросом опасно. Скрипт упирается в timeout, лимиты памяти или ограничение API, а затем непонятно, на каком товаре он остановился.

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

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

Retries должны быть ограниченными

Если складской API отвечает 502 или 503, повтор через некоторое время оправдан. Если сервер отвечает 400 из-за неправильного SKU, бессмысленно отправлять тот же запрос каждые десять секунд.

• сетевые и 5xx ошибки — повторять с увеличивающейся задержкой;
• 429 — учитывать Retry-After и лимиты провайдера;
• 401/403 — остановить задачу и проверить авторизацию;
• 4xx из-за данных — зафиксировать конкретный товар и причину;
• неизвестный формат ответа — не применять данные до проверки.

Полная сверка нужна даже при идеальных webhooks

Практически любая долгоживущая интеграция должна уметь отвечать на вопрос: «есть ли сейчас расхождения между системами?». Для этого полезен reconciliation job — фоновая сверка без слепой перезаписи всего каталога.

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

Логи и история изменений

Когда клиент сообщает «вчера товар сам появился в наличии», без журнала невозможно понять причину. Интеграция должна хранить хотя бы минимальный контекст: SKU, старое значение, новое значение, источник события, внешний ID, время и результат.

При этом секреты API и лишние персональные данные в логах не нужны. Диагностика должна помогать, а не создавать ещё одну утечку.

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

Я начинаю не с переписывания всего кода, а с определения текущего потока. Нужно понять, кто меняет stock, какие хуки WooCommerce задействованы, есть ли cron или Action Scheduler, откуда приходят webhooks и где сохраняются внешние ID.

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

Как я подключаю склад или ERP к WooCommerce

Сначала определяю структуру каталога и правила остатка, затем проверяю API внешней системы. После этого формируется карта SKU и внешних ID, схема событий и стратегия восстановления после ошибок.

Если нужно связать WooCommerce с учётной системой через API, часть архитектуры пересекается с интеграциями WordPress с API. Для магазина я также проверяю влияние на checkout, статусы заказов и фоновые процессы.

Разработка и доработка интернет-магазинов описана на странице WooCommerce-разработки. Если у вас уже есть складской API или описание текущей синхронизации, его можно прислать через контакты A.S Groups — по схеме обычно быстро видно, где должны находиться контрольные точки.