api wildberries это набор HTTP REST методов, которыми продавец управляет магазином без личного кабинета: заводит карточки, ставит цены, забирает сборочные задания, выгружает отчёты, отвечает на отзывы. Официальная спецификация лежит на портале для разработчиков по адресу dev.wildberries.ru/docs/openapi/api-information, отдаётся в формате Swagger OpenAPI и импортируется в Postman или Swagger CodeGen. Ниже разобрано устройство интерфейса: разделы, адреса, токены, лимиты и коды ответов, с проверкой по документации и прямыми запросами к хостам площадки 22 августа 2026 года.
Что даёт интерфейс продавца и чего он не заменяет
Назначение по документации: интеграция с информационными системами продавца, то есть ERP, WMS, OMS и CRM. Отсюда границы. API работает только с данными вашего магазина, привязанными к идентификатору продавца внутри токена, и не открывает чужие магазины.
Юридическая рамка: по пункту 9.9.6 оферты интеграция с порталом продавца в обход WB API запрещена. Скрипт, который логинится в кабинет и кликает за человека, вне правил площадки.
Проверка связи это метод GET /ping, он есть у каждого хоста и работает с токеном любой категории. Лимит у него жёсткий и считается отдельно для каждого домена: максимум 3 запроса за 30 секунд, попытка опрашивать его по расписанию приводит к временной блокировке запросов. Обращение в техподдержку создаётся через диалоги в личном кабинете с категорией «Интеграции по API», адрес портала для разработчиков dev-info@rwb.ru.
Если подключать API некому, карточки, рекламу и остатки ведёт продвижение на Wildberries.
Wildberries seller api: категории методов и адреса, по которым они работают
Единого хоста нет: wildberries seller api разбит на домены по категориям. На этом спотыкается почти каждая новая интеграция, метод существует, но запрос уходит не на тот адрес и возвращает 404. Домены ниже проверены запросом GET /ping без заголовка Authorization: каждый ответил 401, то есть хост живой и требует токена.
| Категория | Базовый адрес | Что внутри |
|---|---|---|
| Общее | common-api.wildberries.ru | Проверка подключения, новости портала, данные продавца, тарифы |
| Контент | content-api.wildberries.ru | Карточки, характеристики, медиафайлы, ярлыки |
| Цены и скидки | discounts-prices-api.wildberries.ru, dp-calendar-api.wildberries.ru | Цены, скидки, календарь акций |
| Маркетплейс | marketplace-api.wildberries.ru | Склады, остатки, заказы FBS, DBS, DBW, Самовывоз |
| Поставки | supplies-api.wildberries.ru | Поставки FBW |
| Статистика | statistics-api.wildberries.ru | Отчёты по заказам и продажам |
| Аналитика | seller-analytics-api.wildberries.ru | Удержания, платное хранение, продажи по регионам |
| Продвижение | advert-api.wildberries.ru, advert-media-api.wildberries.ru | Кампании, ставки, поисковые кластеры, медиакампании |
| Вопросы и отзывы | feedbacks-api.wildberries.ru | Вопросы, отзывы, закреплённые отзывы |
| Чат с покупателями | buyer-chat-api.wildberries.ru | Переписка с покупателями |
| Возвраты | returns-api.wildberries.ru | Возвраты покупателями |
| Документы | documents-api.wildberries.ru | Документы продавца |
| Финансы | finance-api.wildberries.ru | Баланс, финансовые отчёты |
| Пользователи | user-management-api.wildberries.ru | Управление пользователями продавца |
Домены, кроме общего, один в один совпадают с категориями доступа у токена: знаете нужный домен, знаете и галочку при выпуске ключа. Загрузка карточек это «Контент» и content-api, забор сборочных заданий FBS это «Маркетплейс» и marketplace-api. Методы common-api исключение, они работают с токеном любой категории.
Как устроена wildberries api документация: Swagger, песочница, журнал изменений
На портале для разработчиков wildberries api документация разложена по разделам верхнего меню. «Документация» это справочник методов из тринадцати страниц по направлениям (работа с товарами, заказы FBS, DBW, DBS, самовывоз, поставки FBW, продвижение, общение с покупателями, тарифы, аналитика, отчёты, бухгалтерия): описание, адреса Prod и Sandbox, параметры, примеры ответов и таблица лимитов прямо в карточке метода. «Swagger» отдаёт машинную спецификацию OpenAPI. «Песочница» это изолированный тестовый контур. «Статус API» показывает текущую доступность сервисов, туда идут до того, как чинить свой код. «Журнал изменений» фиксирует правки, и площадка прямо предупреждает: методы обновляются регулярно, за журналом надо следить, иначе интеграция отвалится молча.
Отсюда рабочее правило: спецификацию OpenAPI кладут в репозиторий и обновляют, тогда смена обязательности поля ловится диффом, а не жалобой, что остатки не поехали. Для ручной проверки документация советует Postman под Windows и curl под Linux.
Токен api wildberries: где выпускается и что видно только один раз
Порядок выпуска изменился по сравнению с тем, что до сих пор описывают сторонние инструкции. Сейчас токен api wildberries создаётся в личном кабинете продавца в разделе «Интеграции по API», а не в старом пункте «Доступ к API».
- В личном кабинете открыть раздел «Интеграции по API».
- Нажать «+ Создать токен». Откроется окно с двумя вкладками, для всех типов кроме сервисного нужна вкладка «Для интеграции вручную».
- Выбрать тип токена.
- Задать название, отметить категории методов и уровень доступа: «Чтение и запись» или «Только чтение».
- При желании добавить комментарий. Для персонального токена отметить чекбокс «Я понимаю, что не следует передавать токен третьим лицам».
- Нажать «Создать», затем «Скопировать и закрыть».
После закрытия окна токен в кабинете больше не показывается: потеряли значение, выпускайте новый. Срок жизни ключа 180 дней с момента создания, дальше перевыпуск, поэтому дату истечения держат в календаре вместе с ответственным. Передаётся токен в заголовке Authorization.
Документация советует выпускать отдельный ключ на каждую интеграцию с минимумом категорий: если для загрузки карточек выдана одна категория «Контент», утёкший ключ не откроет ни финансы, ни рекламный кабинет.
Четыре типа токенов и когда какой брать
Типов доступа четыре, и лимиты запросов у них разные, поэтому выбор влияет не только на безопасность, но и на скорость выгрузок.
| Тип | Для чего | Ограничение |
|---|---|---|
| Персональный | Свои программы и системы on-premise, включая коробочные версии 1С | Нельзя передавать третьим лицам и использовать в облаке, при создании принимается предупреждение об ответственности |
| Сервисный | Подключение конкретного облачного сервиса из Каталога готовых решений для бизнеса | Работает только с выбранным сервисом, настройки заполняются автоматически |
| Базовый | Вспомогательный ключ, в том числе тест на реальных данных | Ограниченный набор данных и заниженные лимиты |
| Тестовый | Отладка в песочнице | Работает только с песочницей, реальные данные магазина недоступны |
Сервисный лимит распространяется на все токены в пределах одного сервиса, а не на один ключ. Подключили облачный сервис, его запросы делят общую квоту с вашим собственным скриптом.
В карточках отдельных методов встречается блок с иконкой ключа: там записаны ограничения, например требование конкретного типа токена или сервисного секрета. Нет блока, метод работает с любым типом.
Как устроен сам токен: JWT, поля и битовая маска
Ключ это JWT по RFC 7519, его можно декодировать и увидеть, что именно выдано. Документация советует не пользоваться внешними онлайн-декодерами, иначе рабочий токен уедет на чужой сервер.
Тип определяется по трём полям payload:
- acc равен 1 у базового, 2 у тестового, 3 у персонального, 4 у сервисного;
- for отсутствует у базового и тестового, равен self у персонального и asid:{ID сервиса} у сервисного;
- t равен true только у тестового токена.
Служебные поля: id это UUIDv4 токена, sid это UUIDv4 продавца, exp это время жизни по стандарту JWT, s это битовая маска свойств. В маске бит 1 это «Контент», 2 «Аналитика», 3 «Цены и скидки», 4 «Маркетплейс», 5 «Статистика», 6 «Продвижение», 7 «Вопросы и отзывы», 9 «Чат с покупателями», 10 «Поставки», 11 «Возвраты покупателями», 12 «Документы», 13 «Финансы», 16 «Пользователи». Бит 30 поднят, если токен выдан только на чтение.
Польза от декодирования прикладная: до первого запроса видно, совпадает ли набор категорий с задачей и не пытаетесь ли вы писать данные ключом с поднятым битом 30.
Api запросы wildberries: лимиты, всплеск и заголовки ответа
Ограничения на api запросы wildberries считает алгоритм token bucket. Лимит задаётся четырьмя числами: период, максимум запросов за период, интервал между запросами и всплеск (сколько можно отправить подряд без пауз). Считается он на аккаунт продавца, а не на токен.
Пример из документации, лимит для всех методов категории «Маркетплейс»:
| Тип токена | Период | Лимит | Интервал | Всплеск |
|---|---|---|---|---|
| Персональный | 1 минута | 300 запросов | 200 мс | 20 запросов |
| Сервисный | 1 минута | 300 запросов | 200 мс | 20 запросов |
| Базовый | 1 минута | 150 запросов | 200 мс | 10 запросов |
| Тестовый | 1 минута | 150 запросов | 200 мс | 10 запросов |
Другие категории считаются иначе. Все методы «Контента» это 100 запросов в минуту, интервал 600 мс, всплеск 5, а метод создания карточек POST /content/v2/cards/upload вынесен в исключение: 10 запросов в минуту, интервал 6 секунд, всплеск 5.
Самый жёсткий случай в «Статистике»: метод GET /api/v1/supplier/orders на персональном, сервисном и базовом с секретом токене даёт 1 запрос в минуту, а на обычном базовом 1 запрос в 3 часа. Поэтому выгрузка заказов на базовом ключе выглядит сломанной, хотя просто упирается в квоту.
Штраф за ошибки реальный: один ответ 4XX списывается из квоты как 10 обычных запросов, поэтому кривая пагинация выжигает лимит в десять раз быстрее.
Управлять паузами помогают заголовки ответа:
- X-Ratelimit-Remaining, сколько запросов можно сделать прямо сейчас без пауз, приходит во всех ответах кроме 429 и уменьшается на единицу после каждого запроса;
- X-Ratelimit-Retry, через сколько секунд можно повторить запрос после 429, раньше пробовать бессмысленно;
- X-Ratelimit-Limit, максимальное значение всплеска, которое будет восстановлено;
- X-Ratelimit-Reset, через сколько секунд всплеск восстановится до максимума.
В примере документации ответ 429 приходит с X-Ratelimit-Reset: 29, X-Ratelimit-Retry: 2 и X-Ratelimit-Limit: 10. Рабочая интеграция читает эти заголовки, а не ставит sleep наугад.
Коды ответов и формат ошибки
Статусы стандартные для REST, но три строки в таблице специфичны для площадки: 402 приходит только сервисам из Каталога решений, 403 может означать отсутствие подписки Джем, 422 отдаётся при противоречивых параметрах, а не при синтаксической ошибке.
| Код | Что означает | Что делать |
|---|---|---|
| 200 / 204 | Успешно, объект создан, обновлён или удалён | Ничего |
| 400 | Неправильный запрос | Проверить синтаксис, повтор не поможет |
| 401 | Пользователь не авторизован | Токен отсутствует, просрочен, некорректен или его категория не та |
| 402 | Требуется платёж | Только для сервисов из Каталога решений: нет средств на балансе |
| 403 | Доступ запрещён | Токен выпущен удалённым пользователем, метод заблокирован, нет подписки Джем |
| 404 | Не найдено | Проверить URL: чаще всего перепутан домен |
| 409 | Ошибка сохранения или обновления статуса | Данные не отвечают требованиям сервиса |
| 413 | Превышен лимит объёма данных в запросе | Уменьшить пачку |
| 422 | Данные запроса противоречат друг другу | Проверить параметры, например nmId |
| 429 | Слишком много запросов | Ждать секунды из X-Ratelimit-Retry |
| 5XX | Внутренняя ошибка сервиса | Повторить позже |
Ошибки приходят в формате problem+json. Реальный ответ на GET https://content-api.wildberries.ru/ping без заголовка авторизации, снятый 22 августа 2026 года: {“title”:”unauthorized”,”detail”:”empty Authorization header”,”origin”:”s2s-api-auth-content”,”status”:401,”statusText”:”Unauthorized”} плюс поля code, requestId и timestamp. Значение requestId дублируется в заголовке x-request-id, именно его прикладывают к обращению в поддержку. В ошибках 404 и 429 подсказка лежит в поле details, поэтому логировать стоит тело ответа целиком, а не один статус.
Песочница: чем тестовый контур отличается от боевого
Адрес песочницы получается добавлением суффикса -sandbox к домену категории, например marketplace-api-sandbox.wildberries.ru рядом с боевым адресом в карточке метода FBS. Сводной таблицы песочниц в документации нет: часть адресов перечислена в разделе проверки подключения, часть встречается только в карточках методов. Проверка хостов 22 августа 2026 года дала живой тестовый контур у «Контента», «Маркетплейса», «Цен и скидок», «Статистики», «Продвижения», «Вопросов и отзывов» и «Поставок»; у остальных категорий на эту дату он не отвечал. Ориентироваться надёжнее на адрес Sandbox в карточке конкретного метода.
Отличия песочницы, о которых надо знать заранее:
- работает только с тестовым токеном, реальные данные магазина недоступны;
- потолок 1 запрос в секунду суммарно на все методы категории, нагрузочное тестирование там не проводится;
- карточка товара создаётся сразу, без асинхронного ожидания;
- в статистике заказов диапазон дат ограничен последними 4 месяцами.
Вывод: песочница проверяет контракт, а не тайминги и не поведение под нагрузкой. Логику ожидания и повторов всё равно приходится проверять в бою, лучше на одном тестовом товаре.
Что ломается на практике
Ошибки повторяются от проекта к проекту, и почти все про то, что данные не появляются мгновенно.
- Создание карточки асинхронно. Синхронизация занимает до 30 минут, и всё это время нельзя ни завести остатки, ни поставить цену. Скрипт, который создаёт карточку и сразу ставит цену, будет падать всегда.
- Ответ 200 не значит, что всё создалось. Часть карточек может отвалиться, и проверять их надо методом списка несозданных карточек с ошибками.
- Размер пачки ограничен. В одном запросе не более 100 отдельных карточек или 100 групп объединённых по 30, максимальный размер тела 10 Мб. Превышение это 413.
- Статистика отстаёт. Данные отчёта по заказам обновляются раз в 30 минут, информация о заказе хранится 90 дней. Мониторинг минута в минуту на этих методах не строится.
- Выгрузка постраничная. На один ответ по заказам действует условное ограничение 80 000 строк, следующий запрос идёт с dateFrom, равным полному значению lastChangeDate из последней строки предыдущего ответа. Пустой массив означает, что всё выгружено.
- Часовой пояс не ваш. Даты передаются в формате RFC3339 в московском времени UTC+3, а не в UTC и не в поясе вашего сервера.
Нужна интеграция, которая переживёт правки документации
Собираем обмен с WB API под конкретный процесс: карточки, цены, остатки, заказы, отчёты. С учётом лимитов, повторов по X-Ratelimit-Retry, ротации токенов раз в 180 дней и мониторинга журнала изменений.
Когда свой код не нужен и хватает готового сервиса
Документация предлагает два пути: своя разработка по спецификации OpenAPI или подключение партнёрского сервиса из Каталога готовых решений для бизнеса. Во втором случае сервис сам следит за обновлениями методов, а токен выпускается сервисный: вы выбираете сервис в списке, категории и уровни доступа проставляются автоматически.
Ориентир простой. Задача типовая и уже умеет готовый сервис, свой код добавит только расходы на поддержку: за каждой правкой в журнале изменений следить вам. Свой код оправдан при нестандартной логике: собственные правила переоценки, связка с ERP и складом, обмен между несколькими площадками. Разбор готовых инструментов вынесен в материал про автоматизацию работы с маркетплейсами.
Промежуточный вариант рабочий: сервис на сервисном токене закрывает рутину, свой скрипт на отдельном базовом токене с одной категорией делает то, чего в сервисе нет. Помните про общую квоту на аккаунт: два потребителя делят один лимит.
Частые вопросы
Сколько живёт токен и что делать после истечения
180 дней с момента создания. После этого запросы начнут отдавать 401, ключ перевыпускается в разделе «Интеграции по API» личного кабинета.
Почему один и тот же метод отвечает 404
Перепутан домен категории. Карточки живут на content-api.wildberries.ru, заказы FBS на marketplace-api.wildberries.ru, отчёты на statistics-api.wildberries.ru. Подсказка в ошибке 404 приходит в поле details.
Что делать при 429
Читать заголовок X-Ratelimit-Retry и ждать указанное число секунд. Повтор раньше срока снова вернёт 429, а каждый ответ 4XX списывается как 10 обычных запросов.
Можно ли выдать подрядчику доступ только на чтение
Да. При создании базового или персонального токена выбирается уровень доступа «Только чтение», в декодированном JWT он виден как поднятый бит 30 в поле s.
Чем тестовый токен отличается от базового
Тестовый работает только с песочницей и сгенерированными данными, потолок 1 запрос в секунду на категорию. Базовый работает с реальным магазином, но с урезанными лимитами: 150 запросов в минуту в «Маркетплейсе» против 300 у персонального.
