Общее (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. Выберите способ интеграции:
   1. Самостоятельная интеграция с WB API с помощью собственных разработчиков или внешних специалистов. Для этого вы можете использовать спецификации в формате OpenAPI. Методы регулярно обновляются, поэтому для корректной работы интеграции необходимо следить за журналом изменений.
   2. Подключение партнёрских сервисы из Каталога решений для бизнеса. Сервисы сами поддерживают обновления WB API.
3. Создайте API-токен в настройках магазина. Токен позволит получить доступ к WB API. Система токенов позволит вам контролировать, кто и как взаимодействует с вашими данными через API.

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

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

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

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

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

{
  "title": "path not found",
  "detail": "Please consult the https://dev.wildberries.kg/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.

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

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

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

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

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

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

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

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

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

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

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

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

При создании базового и персонального токена вы можете выбрать категории методов, к которым у вас будет доступ:

Токен представляет собой JWT согласно RFC 7519.

Поля токенов

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

Другие поля:

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

Поле s

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

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

Значения бит

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

| 6| Доступ к категории Продвижение| | 7| Доступ к категории Вопросы и отзывы| | 9| Доступ к категории Чат с покупателями| | 10| Доступ к категории Поставки| | 11| Доступ к категории Возвраты покупателями| | 12| Доступ к категории Документы| | 13| Доступ к категории Финансы| | 16| Доступ к категории Пользователи| | 30| Токен только на чтение|

С помощью этих методов вы можете получить:

• информацию о продавце
• рейтинг продавца
• информацию о подписке Джем

С помощью этих методов вы можете:

• Создать приглашение для пользователя с доступом к профилю продавца
• Получить список активных или приглашённых пользователей продавца
• Изменить права доступа пользователей к профилю продавца
• Закрыть доступ пользователю к профилю продавца

Управлять доступом пользователей можно только с токеном активного владельца профиля продавца.