Общее (general)

Wildberries API предоставляет продавцам инструменты для управления магазином и получения оперативной и статистической информации по протоколу HTTP REST API.

Главное преимущество API — возможность автоматизировать процессы за счет интеграции с информационными системами продавца: например, ERP, WMS, OMS, CRM. С WB API продавец может не управлять магазином через интерфейс сайта вручную.

Использование API для работы с магазином на Wildberries — это отличный способ:

• автоматизировать рутинные процессы
• получить доступ к актуальной информации
• оптимизировать управление ассортиментом

Документация API предоставлена в формате Swagger OpenAPI и может быть использована для импорта в другие инструменты — например, Postman — или генерации клиентского кода на различных языках программирования с помощью Swagger CodeGen.

Для ручного тестирования API вы можете использовать:

• Под ОС Windows — PostMan
• Под ОС Linux — curl

1. Зарегистрируйтесь в личном кабинете Продавца.
2. Перейдите в настройки магазина и создайте API-токен. Токен позволит получить доступ к WB API. Система токенов позволит вам контролировать, кто и как взаимодействует с вашими данными через API.
3. Разработайте интеграцию с API с помощью собственных разработчиков или внешних специалистов. Вы также можете подключить партнёрские сервисы из нашего каталога решений для бизнеса.

Практические советы:

• Используйте документацию.
  Официальная документация WB API поможет разобраться в функциональности и возможностях API. В ней приводятся примеры возможных запросов и ответов, список возможных ошибок, лимиты запросов, правила безопасности и так далее.
• Регулярно проверяйте работу интеграции.
  Следите, корректно ли вы передаете данные и какие вы получаете ответы, чтобы вовремя дорабатывать интеграцию. Не забывайте про ограничения и учитывайте лимиты на количество запросов.
• Храните API-токен в безопасности.
  Не передавайте его третьим лицам без необходимости. Используйте только доверенные сервисы. При обнаружении подозрительной активности немедленно удалите и замените токен.
• При необходимости обращайтесь в техническую поддержку.
• Следите за новостями и изменениями WB API в:
  • журнале изменений
  • Telegram-канале
  • новостной ленте Wildberries

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

Основные статус-коды ответов на запросы в WB API:

Пример ошибки:

{
  "title": "path not found",
  "detail": "Please consult the https://dev.wildberries.ru/openapi/api-information",
  ...
  "status": 404,
  "statusText": "Not Found",
  "timestamp": "2025-04-24T07:25:28Z"
}

В WB API есть ограничения на скорость отправки запросов. Для равномерного распределения нагрузки используется алгоритм token bucket. Лимиты для конкретных методов API указаны в документации.

Например:

• Период — временной интервал, в течение которого можно отправить максимальное количество запросов по лимиту.
• Лимит — максимальное количество запросов за период. В примере за одну минуту можно отправить до 300 запросов. Запросы должны быть равномерно распределены по времени.
• Интервал — промежуток времени для пауз между запросами. В примере должен составлять 60 секунд/300 запросов — 200 миллисекунд или 0.2 секунды. Используйте интервал, чтобы равномерно распределить отправку запросов.
• Всплеск — burst, максимальное количество запросов, которое можно отправить одновременно, без интервальных пауз. Допустимый всплеск также возвращается в ответе в заголовке X-Ratelimit-Remaining. Он встречается во всех статусах ответов, кроме ошибки 429.

X-Ratelimit-Remaining — это количество запросов, которое можно выполнить на данный момент без пауз. Значение X-Ratelimit-Remaining уменьшается на единицу после каждого запроса. Если X-Ratelimit-Remaining равен 0 и вы сделали следующий запрос без задержки, в ответ вы получите ошибку 429. Значение X-Ratelimit-Remaining восстанавливается со временем.

Если вы превысите скорость выполнения запросов, вы получите ошибку 429. В этом случае следующий запрос вы сможете сделать только после небольшого ожидания. Чтобы понять, сколько времени вам нужно ждать, используйте заголовки ответа 429:

• X-Ratelimit-Retry — через сколько секунд вы можете повторить запрос. Если вы сделаете попытку раньше, вы все равно будете получать ошибку 429.
• X-Ratelimit-Limit — максимальное значение всплеска запросов — burst, которое будет восстановлено через X-Ratelimit-Reset секунд.
• X-Ratelimit-Reset — через сколько секунд допустимый всплеск запросов восстановится до максимального значения, указанного в X-Ratelimit-Limit.

Пример ответа:

HTTP/1.1 429 Too Many Requests
...
X-Ratelimit-Reset: 29
X-Ratelimit-Retry: 2
...
X-Ratelimit-Limit: 10

Чтобы авторизоваться в API, вам понадобится токен. Он действует 180 дней после создания. Добавляйте токен в заголовок запроса Authorization.

Для авторизации доступно четыре типа токенов:

Персональный токен

• Назначение: Эксклюзивный токен с расширенными возможностями. Предназначен для того, чтобы предоставлять доступ к данным продавца только вашим собственным программам — в том числе корпоративным системам (on-premise), развёрнутым на собственной или арендованной инфраструктуре.
  Расширенные возможности означают, что со временем по персональному токену появится доступ к дополнительным категориям данных продавца, которые недоступны в базовом токене. Мы заранее расскажем об этом в новостях.
• Подходит для:
  • собственных программных продуктов или систем компании, размещённых на своих или арендованных серверах
  • готовых ERP/CRM-систем в редакции on-premise, включая локальные (коробочные) версии 1С, развёрнутые на серверах компании или на компьютерах пользователей
• Ограничения: Персональный токен даёт доступ к чувствительной информации, поэтому его нельзя передавать третьим лицам или использовать в облачных сервисах. При создании токена система покажет предупреждение об ответственности — его нужно принять, чтобы продолжить.
  Настройки токена вы выбираете самостоятельно. Если не уверены, какие параметры указать, уточните у разработчика или IT-специалиста, который отвечает за подключаемую систему.

Сервисный токен

• Назначение: Специальный токен для подключения конкретного облачного сервиса из официального Каталога готовых решений для бизнеса на Wildberries.
• Особенности: При создании токена вы выбираете сервис из Каталога, после чего все необходимые настройки, в том числе категории данных и уровни доступа, заполняются автоматически. Вам останется только подтвердить создание токена и передать его сервису.
• Ограничения: Привязан к конкретному сервису и работает только с ним.

Базовый токен

• Назначение: Вспомогательный токен, который предоставляет доступ к ограниченному набору данных продавца и используется во всех случаях, когда не подходит сервисный или персональный токен.
• Подходит для:
  • тестирования интеграции на реальных данных перед запуском
  • остальных случаев, когда вы не можете использовать сервисный или персональный токен
• Ограничения: Можно работать с ограниченным набором данных.

Тестовый токен

• Назначение: Специальный токен для безопасного тестирования и отладки интеграций в изолированной среде — песочнице WB API.
• Подходит для:
  • разработки и отладки интеграций без риска для реальных данных
  • изучения возможностей API и экспериментов с методами
  • проверки новых функций перед запуском в рабочей среде
• Ограничения: Тестовый токен работает только с песочницей и даёт доступ к сгенерированным тестовым данным. Реальные данные магазина при этом недоступны. |

1. В личном кабинете перейдите в раздел Интеграции по API.
2. Нажмите + Создать токен. Откроется окно создания токена с двумя вкладками. Для всех типов токенов, кроме сервисного, выберите вкладку Для интеграции вручную.
3. Выберите тип токена.
4. Для базового и персонального токенов:

• Заполните название токена
• Выберите, с какими категориями API вы будете работать
• Задайте уровень доступа к данным: Чтение и запись или Только чтение

5. Добавьте комментарий к токену по желанию. Для персонального токена отметьте чекбокс Я понимаю, что не следует передавать токен третьим лицам.
6. Нажмите Создать. Появится окно с вашим токеном.
7. Нажмите кнопку Скопировать и закрыть — окно закроется, токен будет скопирован в буфер обмена. После этого токен нельзя будет посмотреть в личном кабинете.
8. Сохраните токен в безопасном месте. Если вы потеряли токен, создайте новый.

Токен представляет собой JWT согласно RFC 7519. Чтобы проверить, действителен ли ваш токен и какие категории методов API по нему доступны, вы можете декодировать его.

Поля токенов

Тип токена можно определить по списку полей из payload токена после декодирования:

Другие поля:

Остальные поля payload служебные и могут быть удалены.

Поле s

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

Подробнее про битовую маску

Значения бит

Позиция бита отсчитывается от 0, где 0 — это младший бит.

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