Интеграция с Wildberries: API, остатки, поставки

Интеграция с Wildberries обычно начинается не с API, а с боли: остатки в 1С разошлись с личным кабинетом, поставка зависла на этапе приёмки, а менеджер каждый вечер вручную поднимает цены на карточках. За последний год я закрывал похожие задачи для нескольких продавцов на WB, от ИП с одним складом до небольшой сети с одновременной работой по FBS и FBO. В статье разберу, какие API у Wildberries реально нужны, как настроить обмен остатками без овербукинга и как автоматизировать создание поставок, чтобы не сидеть в личном кабинете каждый день.

Какие API нужны для интеграции с Wildberries

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

• Statistics API - отчёты о продажах, остатках на складах WB, заказах и возвратах за период. Отсюда обычно берут исходные данные для сверки с учётной системой.
• Marketplace API - работа с заказами FBS, обновление остатков и статусов сборки, создание и ведение поставок по своей доставке.
• Content API - карточки товаров, характеристики, медиафайлы.
• Prices API - управление ценами и скидками на карточках.
• Supplies API - создание заданий на поставку для FBO и получение коэффициентов приёмки складов.

На практике для задачи “остатки плюс поставки” хватает связки Marketplace API и Supplies API, Statistics API подключаю, когда нужна сверка или аналитика по продажам, а не только операционка.

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

Токены доступа: права и ограничения личного кабинета

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

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

Лимиты запросов WB считает по методам, а не по токену в целом, и цифры отличаются от эндпоинта к эндпоинту: где-то это несколько запросов в секунду, где-то жёстче. Актуальные значения смотрю в официальной документации перед каждым новым проектом, потому что WB их периодически пересматривает.

Токен храню в переменных окружения сервера или в секретах CI, никогда в самом репозитории, и раз в несколько месяцев перевыпускаю его заново через личный кабинет, особенно если к проекту подключались подрядчики со стороны. Ограничение по IP включаю всегда, когда скрипт работает с одного постоянного сервера, это закрывает риск утечки токена почти полностью, даже если он случайно попадёт в чужие руки.

Для самого сервера обычно хватает недорогого VDS: n8n и Python-скрипт по расписанию не требовательны к ресурсам, важнее держать мониторинг доступности и алерт, если процесс упал или завис.

Остатки: синхронизация склада с Wildberries

Для продавцов на FBS остатки обновляются через Marketplace API методом обновления стоков по конкретному складу продавца. Логика простая: берём актуальное количество товара из учётной системы, сопоставляем по баркоду или артикулу WB и отправляем PUT-запросом.

curl -X PUT "https://marketplace-api.wildberries.ru/api/v3/stocks/{warehouseId}" \
  -H "Authorization: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "stocks": [
      { "sku": "2037654321", "amount": 15 }
    ]
  }'

Для FBO своих остатков на складе продавца нет, товар физически лежит на складе Wildberries, а значит через этот метод их не обновить. Здесь синхронизация идёт в обратную сторону: остатки на складах WB забираются через Statistics API и подтягиваются в учётную систему, чтобы менеджеры видели реальную картину и не продавали то, чего уже нет.

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

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

Как обрабатывать ошибку 429 и не терять обновления

Хорошо помогает простой ретрай с задержкой и ограничением числа попыток: если WB вернул 429, скрипт ждёт указанное в заголовке время или фиксированную паузу и повторяет запрос, а не просто пишет ошибку в лог и идёт дальше. На практике трёх повторов с растущей задержкой хватает почти всегда, а сами неудачные партии складываю в отдельную очередь, чтобы прогнать их отдельным запуском, если основной цикл синхронизации всё равно не смог их отправить.

import time
import requests

def update_stock(warehouse_id, payload, token, retries=3):
    url = f"https://marketplace-api.wildberries.ru/api/v3/stocks/{warehouse_id}"
    headers = {"Authorization": token, "Content-Type": "application/json"}
    for attempt in range(retries):
        response = requests.put(url, json=payload, headers=headers)
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 5))
            time.sleep(wait)
            continue
        response.raise_for_status()
        return response
    raise RuntimeError("Не удалось обновить остатки после повторных попыток")

Поставки: создание и сопровождение через API

Для FBS поставка собирается из готовых заказов: создаётся поставка методом Marketplace API, в неё добавляются заказы, готовые к отгрузке, после чего поставка закрывается и формируются документы для курьера или транспортной компании. Статус каждой поставки можно отслеживать через API и подсвечивать в CRM или боте, когда заказы просрочены по сборке.

Для FBO процесс другой: продавец выбирает склад и дату поставки, ориентируясь на коэффициент приёмки. Коэффициент показывает, насколько дорого или дёшево обойдётся приёмка на конкретном складе в конкретный день, и через API его можно получать программно вместо ручного обновления вкладки в браузере.

Я обычно ставлю рядом с основной интеграцией небольшого бота на aiogram, который присылает в Telegram уведомление, если коэффициент приёмки на нужном складе упал до нуля или, наоборот, освободился льготный слот. Ручной мониторинг вкладки в личном кабинете отнимает время у менеджера, а бот делает то же самое в фоне.

При приёмке поставки на складе Wildberries важен не только сам факт привоза товара, но и штрихкод поставки, который система формирует после закрытия задания в личном кабинете или через API. Без правильно распечатанного и наклеенного штрихкода короба приёмщик физически не сможет провести товар по системе, и поставка зависнет в статусе ожидания. Для FBS похожая история со стикерами на заказах, их тоже удобно печатать пакетно через API, а не по одному вручную из карточки заказа.

Автоматизация обновления остатков: n8n, Python и расписание

Три рабочих варианта, которые встречаю у клиентов чаще всего.

Для несложных случаев, например синхронизации остатков между одним складом и Wildberries, n8n закрывает задачу за пару дней: HTTP-нода забирает данные из учётной системы, вторая нода приводит их к формату WB, третья отправляет PUT-запрос и логирует ответ. Как только логика усложняется, появляются кастомные правила округления остатков, резервы под другие маркетплейсы, обработка частичных ошибок в батче, я перехожу на Python-скрипт, потому что в нём проще держать тесты и версионировать логику.

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

Мониторинг и логирование

Отдельно веду простое логирование каждого цикла синхронизации: время запуска, количество отправленных SKU, количество ошибок и их коды. Храню это в отдельной таблице или логе, а не только в консоли, потому что через месяц работы без истории сложно понять, действительно ли остатки перестали обновляться вчера или скрипт вообще ни разу не запускался в выходные. Если синхронизация падает несколько раз подряд, отправляю алерт в Telegram тем же ботом, что уведомляет о коэффициентах приёмки, чтобы не заводить для этого отдельный канал.

Перед полным переключением на автоматическую синхронизацию всегда прогоняю тест на одном складе и небольшой части каталога, обычно 20-30 SKU: смотрю, как система реагирует на реальные ответы WB, ловлю расхождения в форматах баркодов и только после нескольких чистых циклов подключаю весь каталог. Переключать всё сразу без такого прогона рискованно, ошибку в сопоставлении артикулов проще поймать на тридцати товарах, чем на полутора тысячах.

Частые ошибки интеграции и сколько стоит разработка

Что подготовить до старта

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

• Выгрузку товаров с баркодами и артикулами WB в любом формате, хоть Excel.
• Доступ в личный кабинет WB Partners с правом создать токен API.
• Описание источника остатков: 1С, CRM, отдельная база или таблица, и как часто там меняются данные.
• Список складов, с которых идёт отгрузка, если продавец работает по FBS с нескольких точек.

Из того, что регулярно вижу при разборе чужих интеграций с Wildberries:

• Скрипт не обрабатывает ответ 429 и просто теряет часть обновлений вместо повтора запроса с задержкой.
• Остатки обновляются одним большим батчем раз в сутки, из-за чего товар продолжает продаваться уже после того, как физически закончился.
• Сопоставление товаров идёт по названию, а не по баркоду, и после смены названия карточки остатки перестают обновляться молча, без ошибки в логах.
• Токен с полными правами лежит в коде репозитория вместо переменных окружения.

По деньгам ориентируюсь на реальный объём задачи. Скрипт синхронизации остатков между учётной системой и Wildberries через API у меня стоит от 20 000 ₽, сценарий в n8n с уведомлениями в Telegram и обработкой ошибок, от 25 000 ₽. Если требуется связать WB с полноценной CRM или интернет-магазином, разработка ведётся как отдельный проект, и оценка считается по объёму каталога и количеству складов.

Частые вопросы

Нужно ли юрлицо, чтобы получить доступ к API Wildberries?

Организационная форма не влияет на выдачу токена: доступ к API привязан к личному кабинету продавца на Wildberries. Работает и ИП, и самозанятый, и ООО, важно только, что кабинет активен и в нём открыт раздел настроек доступа к API. Проверить это можно за пару минут прямо в личном кабинете, отдельного юридического подтверждения WB не запрашивает.

Как часто можно обновлять остатки через API без риска попасть в лимиты?

Лимиты считаются по методам API, а не в целом по аккаунту. Для ходовых товаров ставлю синхронизацию раз в 5-15 минут, для остального хватает раза в час. Если запросов много одновременно, добавляю очередь с задержкой, чтобы не упираться в лимит и не терять обновления при ответе 429. Даже при аккуратной настройке раз в месяц стоит перепроверять актуальные значения лимитов в документации, WB их иногда меняет без широкого анонса.

Что делать, если поставка на склад Wildberries зависла или коэффициент приёмки равен нулю?

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

Сколько занимает настройка интеграции с Wildberries с нуля?

Простая синхронизация остатков между одним складом и WB через n8n или Python занимает несколько дней. Полноценная связка с 1С или CRM, поставками и уведомлениями обычно требует от 2 до 4 недель, в зависимости от того, сколько складов и источников данных нужно свести вместе. Сроки растягиваются в основном не из-за самого API, а из-за качества исходных данных на стороне клиента, разномастных артикулов и складов без единого справочника.