API запросы Wildberries: сценарии автоматизации процессов

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

Как получить токен, какие бывают категории и полный перечень методов, разобрано отдельно в статье документация API Wildberries. Здесь только прикладная часть, сверенная по порталу разработчиков WB на 22 августа 2026 года.

Wildberries Seller API: как разложить процесс на запросы

Wildberries Seller API устроен не как один сервис, а как набор доменов по категориям: у цен свой адрес, у сборочных заданий свой, у статистики третий. Связность каждого проверяется методом /ping, но не чаще трёх запросов за 30 секунд, и лимит считается отдельно для каждого домена. Автоматизировать пинг в цикле нельзя: запросы временно заблокируют.

Дальше архитектуру сценария определяет тип метода.

• Синхронные. Отправили запрос, получили данные. Так работают сборочные задания, остатки, отзывы.
• Асинхронная загрузка. Отправили пачку на запись, получили ID загрузки, дальше опрашиваете состояние отдельным методом. Так устроены цены и скидки.
• Отчёт по заданию. Создали задание, получили task_id, проверили статус, только потом скачали результат. Так работает отчёт об остатках на складах WB.

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

Цены и скидки по расписанию: загрузка, карантин, проверка результата

Метод POST /api/v2/upload/task принимает максимум 1 000 товаров за запрос, цена и скидка не могут быть пустыми одновременно. Лимит категории «Цены и скидки» зависит от токена: персональный, сервисный и базовый с секретом дают 10 запросов за 6 секунд с интервалом 600 мс и всплеском 5, обычный базовый всего 4 запроса в час с интервалом 15 минут. Каталог на 40 000 SKU это 40 запросов: персональным токеном они уйдут за полминуты, обычным базовым растянутся почти на 10 часов.

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

1. Собрать пачку до 1 000 позиций и отправить POST /api/v2/upload/task. В ответе придёт ID загрузки.
2. Если пришёл код 208, такая загрузка уже есть: повторять её не нужно, это защита от дублей, а не ошибка.
3. Через паузу запросить GET /api/v2/history/tasks?uploadID=: состояние обработанной загрузки. Пока она не обработана, состояние смотрят методом /api/v2/buffer/tasks, а детализацию по позициям берут из /api/v2/history/goods/task.
4. Сверить факт: GET /api/v2/list/goods/filter с параметром limit до 1 000 и offset, повторяя запрос, пока не вернётся пустой массив.

Ответ 200 на загрузку означает только то, что задание принято. Скрипт, который отправил цены и не проверил детализацию, это лотерея.

Сборочные задания FBS: от нового заказа до передачи в доставку

Одно сборочное задание всегда содержит одну единицу товара. Положил покупатель в корзину 10 одинаковых футболок, у продавца появится 10 отдельных заданий с общим полем orderUid. Расчёты «сколько заказов за день» ломаются, если этого не учесть.

Метод GET /api/v3/orders/new возвращает все новые задания на момент запроса, без параметров периода. Дальше цикл такой:

1. Создать поставку: POST /api/v3/supplies.
2. Добавить задания: PATCH /api/marketplace/v3/supplies/{supplyId}/orders. За один запрос до 100 сборочных заданий, и они переходят в статус confirm, то есть «на сборке».
3. Получить стикеры: POST /api/v3/orders/stickers, до 100 заданий за запрос.
4. Передать в доставку: PATCH /api/v3/supplies/{supplyId}/deliver. После этого задания становятся complete.

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

Статусы читает POST /api/v3/orders/status, от 1 до 1 000 ID за запрос. Полей два, и их постоянно путают.

Сборку на своём складе ведут по supplierStatus, факт получения и отмены ловят по wbStatus. Значение declined_by_client это отмена покупателем в первый час после заказа, пока задание не переведено на сборку: если робот забирает задания в сборку мгновенно, такие отмены придут уже возвратом.

Лимит категории «Маркетплейс» на аккаунт продавца: 300 запросов в минуту с интервалом 200 мс и всплеском 20 для персонального и сервисного токенов, 150 запросов в минуту с всплеском 10 для базового и тестового.

Синхронизация остатков со складом: PUT и тихие ошибки

Остатки продавца обновляются методом PUT /api/v3/stocks/{warehouseId}, до 1 000 позиций в одном запросе, ответ при успехе 204.

Здесь спрятана самая дорогая ловушка WB API: названия параметров запроса не валидируются. Отправите поле с опечаткой в имени, получите успешный 204, а остатки не изменятся. Ошибки не будет. Обмен «работает», отчёт зелёный, товар уходит в оверселл.

Защита одна и она обязательна: после записи прочитать остатки обратно и сверить с отправленным. Полную сверку гонят раз в сутки, даже если событийный обмен из WMS идёт непрерывно.

Код 406 означает, что обновление остатков заблокировано. Это не сетевой сбой, повторять бесполезно, причину разбирают в кабинете. Лимит тот же, что у всей категории «Маркетплейс», и помните про множитель: запрос с кодом 4XX списывается здесь как 10 запросов.

Отзывы и вопросы: сбор и автоответ, который не навредит

Опрашивать полный список отзывов каждые пять минут не нужно. Дешёвый метод GET /api/v1/new-feedbacks-questions отвечает, есть ли непросмотренные отзывы и вопросы, и только при положительном ответе имеет смысл идти за содержимым.

Список забирает GET /api/v1/feedbacks с обязательными параметрами isAnswered, take и skip, максимум 5 000 отзывов за запрос. Обработанным Wildberries считает отзыв, на который получен ответ, либо отзыв с одной оценкой без текста и фото.

Ответ отправляет POST /api/v1/feedbacks/answer, текст от 2 до 5 000 символов, успех это 204. И снова тихая ошибка: ID отзыва не валидируется, при некорректном ID ошибки не будет, ответ уйдёт в никуда, а лог покажет успех. Поэтому статус отзыва перечитывают через /api/v1/feedback.

Лимит категории «Вопросы и отзывы»: 3 запроса в секунду с интервалом 333 мс и всплеском 6 для персонального, сервисного и базового с секретом токенов. У обычного базового 5 запросов в час с интервалом 12 минут, для автоответчика этого не хватит физически.

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

Отчёт о продажах в свою базу: курсор, 80 000 строк и задержка 30 минут

Для аналитики в своей базе используют GET /api/v1/supplier/orders и GET /api/v1/supplier/sales. Их свойства надо знать до того, как строить витрину.

• Данные обновляются раз в 30 минут. Опрашивать чаще нечего.
• Одна строка это один заказ, одно сборочное задание, одна единица товара. Ключ для склейки и дедупликации: поле srid.
• Информация о заказе хранится 90 дней с момента оформления. Всё, что нужно на большем горизонте, вы обязаны сложить к себе.
• На один ответ с flag=0 или без flag установлено условное ограничение 80 000 строк. Чтобы выгрести всё, во втором и последующих запросах в dateFrom подставляют полное значение lastChangeDate из последней строки предыдущего ответа. Пустой массив означает, что выгрузка закончена.
• Поля finishedPrice, priceWithDisc и forPay могут временно быть равны нулю: они заполняются асинхронно и актуализируются в течение 24 часов.

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

Лимит жёсткий: 1 запрос в минуту для персонального, сервисного и базового с секретом токенов. У обычного базового 1 запрос в 2 часа на продажи и 1 запрос в 3 часа на заказы. Схема «дёрнем при открытии дашборда» не работает, только инкрементальный забор в своё хранилище по расписанию.

Вебхуков нет: чем заменить push-уведомления

Разработчики из других экосистем первым делом ищут вебхуки. В каталоге категорий WB API раздела вебхуков нет: маркетплейс не стучится к вам сам, все методы работают на запрос с вашей стороны. Реактивность строится опросом.

Ближе всего к реальному времени Лента заказов, метод POST /api/analytics/v1/order-feed. Данные обновляются в режиме реального времени, заказы отдаются по времени текущего статуса от нового к раннему, глубина максимум 31 день. Лимит: 1 запрос в минуту для персонального, сервисного и базового с секретом токенов, 1 запрос в 3 часа для базового.

Отсюда двухслойная схема. Быстрый слой раз в минуту забирает ленту заказов и новые сборочные задания и кладёт события в очередь. Медленный раз в 30 минут или ночью забирает статистику и пересобирает витрину. Смешивать их в одном скрипте не стоит: разные лимиты и разная цена ошибки.

Тяжёлые отчёты живут по третьей модели. Отчёт об остатках на складах WB создаётся заданием GET /api/v1/warehouse_remains, дальше проверяется /tasks/{task_id}/status и только после готовности скачивается через /download. Лимит на создание задания: 1 запрос в минуту, а статус опрашивают с шагом в несколько секунд и с ограничением числа попыток.

Токен API Wildberries под сценарий: права, срок и разделение

Токен API Wildberries живёт 180 дней с момента создания и передаётся в заголовке Authorization. Дата истечения зашита в поле exp самого токена, который представляет собой JWT по RFC 7519. Отсюда два правила для сценария.

Первое: срок жизни мониторят программно. Дату из exp кладут в мониторинг и напоминают за две недели, а не вспоминают в день, когда обмен встал.

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

Ошибки, повторы и идемпотентность в API WB Wildberries

Любой сценарий на API WB Wildberries рано или поздно упрётся в 429. Нагрузка распределяется алгоритмом token bucket, и всё нужное для расчёта паузы приходит прямо в заголовках ответа.

Слепой экспоненциальный backoff здесь не нужен: ждите ровно X-Ratelimit-Retry секунд. И помните про множитель: в категории «Маркетплейс» один ответ 4XX списывается как 10 запросов, поэтому цикл, упорно бьющийся в 400, выжигает квоту почти мгновенно. Дальше вопрос, какие запросы безопасно повторять.

• Повторять свободно: все GET-методы и PUT остатков, они идемпотентны по смыслу. Повторная запись того же количества ничего не портит.
• Повторять с проверкой: загрузку цен. Код 208 «такая загрузка уже есть» и есть встроенная защита от дублей, его надо считать успехом, а не ошибкой.
• Не повторять вслепую: создание поставки и добавление заданий к поставке. Перед повтором читают текущее состояние: задание могло уже перейти в confirm.
• Разбирать, а не повторять: коды 400, 409, 413 и 422. Это про содержимое запроса. При 413 уменьшают количество объектов в пачке.

Ответ 401 чаще всего означает не «токен просрочен», а несовпадение категории токена и категории API: обращаетесь к ценам токеном для статистики. Ответ 403 приходит, когда токен создан удалённым пользователем. Повторами не лечится ни то ни другое. И мелочь, которая экономит часы: в ошибках 404 и 429 Wildberries кладёт подсказку в поле details, поэтому логируют всё тело ответа, а не только статус-код.

Песочница: как проверить сценарий, не тронув боевые данные

У Wildberries есть тестовый контур с отдельными доменами вида discounts-prices-api-sandbox.wildberries.ru и statistics-api-sandbox.wildberries.ru. Работает он по тестовому токену, данные сгенерированы случайно и реальным продавцам не принадлежат. Что учитывать при отладке:

• Скорость другая: максимум 1 запрос в секунду суммарно на все методы категории. Нагрузочное тестирование в песочнице бессмысленно.
• Для статистики диапазон dateFrom и dateTo ограничен последними 4 месяцами от текущей даты.

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

Как собрать это в рабочий контур

Разрозненные скрипты по крону это тот же ручной режим, только с отложенным разбором. Контур, который держится годами, состоит из пяти частей.

1. Очередь задач. Каждый вызов API это задача с числом попыток и полем «повторить после», куда пишется X-Ratelimit-Retry.
2. Лог запросов и ответов. Метод, тело, статус, поле details, ID загрузки. Без этого разбор расхождения в ценах превращается в гадание.
3. Своё хранилище. Данные о заказе живут в API 90 дней, история за год существует только у вас. Инкремент по lastChangeDate, дедупликация по srid.
4. Обратная сверка. После каждой записи чтение и сравнение. Особенно для остатков, где неверное имя поля даёт успешный 204 и нулевой эффект.
5. Мониторинг. Доля ответов 429, возраст последних успешных данных по каждому процессу, число дней до истечения токена.

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

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

Сколько товаров можно обновить одним запросом цен

До 1 000 товаров в одном вызове POST /api/v2/upload/task. Ограничение на частоту зависит от токена: 10 запросов за 6 секунд для персонального, сервисного и базового с секретом, и всего 4 запроса в час для обычного базового токена.

Почему остатки не обновились, хотя пришёл успешный ответ

Метод PUT /api/v3/stocks/{warehouseId} не валидирует названия параметров запроса. При опечатке в имени поля вернётся 204, а остатки останутся прежними. Лечится только обратным чтением остатков и сверкой после каждой записи.

Как часто обновляются данные по продажам

Раз в 30 минут. Дополнительно поля finishedPrice, priceWithDisc и forPay заполняются асинхронно и актуализируются в течение 24 часов, поэтому свежий отчёт может показывать заниженную выручку. Для точной сверки используют детализации к отчётам реализации.

Что делать при коде 429

Прочитать заголовок X-Ratelimit-Retry и подождать указанное в нём число секунд: более ранний повтор снова вернёт 429. Заодно стоит проверить долю ошибок 4XX, потому что в категории «Маркетплейс» один такой ответ списывается как 10 запросов.

Есть ли у Wildberries вебхуки

Нет, в каталоге категорий WB API раздела вебхуков нет, все методы работают на запрос с вашей стороны. Ближе всего к реальному времени метод POST /api/analytics/v1/order-feed «Лента заказов»: данные обновляются в реальном времени, глубина до 31 дня, лимит 1 запрос в минуту.