• Документация
  • Журнал изменений
  • Песочница
  • База знаний
  • Документация
  • Журнал изменений
  • Песочница
  • База знаний
  • Документация
  • Журнал изменений
  • Песочница
  • База знаний

©Wildberries 2004–2026. Все права защищены.

Политика обработки персональных данныхПолитика в отношении cookies

Идентификация сервиса в WB API

Сервисный секрет, User-Agent и лимиты запросов: как платформа определяет, какой сервис отправляет запросы

0
content

Сервис отправляет запросы к WB API с токенами продавцов. Токен определяет, от имени какого продавца выполняется запрос, но в случае сервиса платформе также важно понимать, какой именно сервис отправляет этот трафик.

Для идентификации сервиса используются два признака:

  • сервисный секрет (ключ доступа), который передаётся вместе с запросами к WB API;
  • User-Agent, который помогает идентифицировать и диагностировать трафик сервиса.

Только по размеченному трафику платформа определяет сервис и предоставляет ему инструменты платформы, в том числе расширенные лимиты, если для сервиса доступна эта опция.

В этой статье разберём:

  • что такое сервисный секрет и как его получить;
  • как проверить секрет и где передавать его в запросах;
  • какие ошибки возвращает WB API при проблемах с секретом;
  • как сервис получает User-Agent и как его передавать;
  • как устроены лимиты запросов и что делать при ошибке 429.

Токены продавцов и OAuth 2.0 разобраны в статье «Доступ к данным продавца: токены и OAuth 2.0».


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

Что такое сервисный секрет и зачем он нужен

Сервисный секрет (ключ доступа) — собственный уникальный идентификатор сервиса на платформе WB API. Он подтверждает подлинность сервиса при каждом обращении к WB API. Секрет не привязан к отдельному продавцу: один и тот же секрет передаётся в запросах по всем подключённым продавцам. Срок действия секрета — 180 дней, а момент перевыпуска выбираете вы: новый секрет можно выпустить в любой день этого срока и даже после его окончания. Как только новый выпущен, срок старого сокращается до 30 дней, а если до его конца оставалось меньше — не меняется. Заменить секрет в конфигурации можно без простоя.

Токен продавца и сервисный секрет выполняют разные задачи:

  • токен определяет продавца и предоставленный им доступ;
  • сервисный секрет (ключ доступа) определяет сервис и доступные ему возможности на платформе WB API.

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

Секрет — признак зарегистрированного сервиса и следующий шаг к Каталогу решений для бизнеса на Wildberries: витрине сервисов для продавцов, где доступны Сервисный токен и подключение по OAuth 2.0.

Как получить сервисный секрет

Чтобы зарегистрировать сервис и получить сервисный секрет, напишите на business-solutions@rwb.ru и опишите сервис и задачу, которую он решает для продавцов. Если сервис уже соответствует требованиям Каталога решений, в том же письме можно подать заявку сразу на размещение.

Дальше порядок такой:

  1. В ответ команда WB API пришлёт инструкцию. Запрос секрета подтверждается гарантийным письмом от сервиса — отправьте его скан ответным письмом и укажите WB ID аккаунта, который будет управлять сервисом на портале WB API: по нему команда откроет доступ в Профиль компании.
  2. Команда зарегистрирует сервис и откроет доступ в Профиль компании на портале WB API — аккаунту с тем WB ID, который вы указали в письме. Как и где войти в Профиль, команда сообщит в том же письме.
  3. Сервисный секрет выпустите сами — в разделе «Ключи доступа» Профиля компании.

Перевыпуск и отзыв секрета делаются там же, в разделе «Ключи доступа», — обращаться в команду для этого не нужно. На один сервис доступно до двух ключей одновременно, поэтому новый секрет можно выпустить, не отзывая старый. Письмо на business-solutions@rwb.ru нужно, чтобы получить доступ в Профиль компании. Дальше все операции с секретом сервис выполняет сам, а команда отзывает секрет только по просьбе сервиса — например, если тот потерял доступ в Профиль.

Если сервис сразу подаёт заявку на авторизацию в Каталоге решений, отдельное письмо не нужно: инструкцию по получению секрета команда пришлёт в ответ на заявку.

Дата окончания действия указана в самом секрете, в поле exp (см. следующий раздел). Планируйте перевыпуск заранее, чтобы работа сервиса не прерывалась.

Храните сервисный секрет так же надёжно, как пароль: в переменных окружения или защищённом секрет-хранилище. Не публикуйте его в репозиториях и не передавайте третьим лицам. Если секрет скомпрометирован — отзовите его в Профиле компании и сразу выпустите новый.


Как проверить сервисный секрет

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

Шаг 1. Проверьте содержимое секрета

Сервисный секрет — JWT-⁠токен. Его payload можно прочитать стандартной JWT-⁠библиотекой без проверки подписи. Не передавайте сервисный секрет сторонним онлайн-декодерам.

{
  "exp": 1715840770,
  "id": "31ee022e-0663-4c75-bc78-a976a1fdd3bb",
  "asid": "0191c6da-597f-731d-bfc4-3f20cbe0a864",
  "typ": 2
}
ПолеЧто проверить
expСрок действия секрета (Unix time). Дата должна быть в будущем
idУникальный идентификатор секрета
asidВаш ID сервиса на платформе WB API. То же значение стоит в поле for Сервисных токенов, выпущенных для сервиса, — после префикса asid:
typТип токена: 2 — сервисный секрет

Не путайте asid с WB ID. WB ID — номер аккаунта на портале WB API: он виден на главной странице личного кабинета, и по нему команда открывает доступ в Профиль компании. asid — идентификатор самого сервиса.

Если payload не читается или в нём нет этих полей, секрет повреждён — например, при копировании потерялась часть символов. Скопируйте значение заново из источника, откуда он получен.

Шаг 2. Выполните контрольный запрос

Отправьте запрос к любому методу, который использует сервис, с токеном продавца и секретом — как описано в следующем разделе. Успешный ответ означает, что связка «токен + секрет» рабочая.

Если WB API возвращает:

  • 401 secret token expired — срок действия секрета истёк;
  • 401 secret token withdrawn — секрет отозван.

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


Где передавать сервисный секрет

Секрет передаётся в каждом запросе к WB API в заголовке X-Client-Secret. Токен продавца при этом передаётся отдельно в заголовке Authorization. Сервисный секрет дополняет токен продавца, а не заменяет его:

Authorization: {токен_продавца}
X-Client-Secret: {ваш_сервисный_секрет}

Пример запроса:

curl -H "Authorization: ${SELLER_TOKEN}" \
     -H "X-Client-Secret: ${SERVICE_SECRET}" \
     https://marketplace-api.wildberries.by/api/v3/orders/new

Зарегистрированный сервис передаёт сервисный секрет во всех запросах к WB API — ко всем используемым методам и категориям данных, и с Базовым токеном, и с Сервисным. Запрос без секрета платформа к сервису не относит.

Ошибки при передаче секрета и их решение

Точная причина ошибки указывается в поле detail тела ответа. Начинайте диагностику с него.

Код и detailПричинаРешение
401 secret token expiredИстёк срок действия сервисного секретаВыпустите новый секрет в Профиле компании и замените его в конфигурации
401 secret token withdrawnСервисный секрет отозванВыпустите новый секрет в Профиле компании. Если секрет отзывали не вы, причину уточните на business-solutions@rwb.ru
401 token expiredИстёк токен продавца. Ошибка не связана с сервисным секретомПопросите продавца создать новый токен и передать его сервису. Остальные ошибки токена продавца разобраны в статье «Доступ к данным продавца: токены и OAuth 2.0», раздел «Ошибки 401 и 403»
403 X-Client-Secret is missing for this token typeВ запросе отсутствует сервисный секрет или используется Сервисный токен другого сервисаДобавьте заголовок X-Client-Secret и убедитесь, что токен продавца выпущен именно для вашего сервиса
403 access token and X-Client-Secret are for different authorized servicesТокен продавца выпущен для другого сервисаПопросите продавца создать токен именно для вашего сервиса
403 X-Client-Secret is not allowed with private tokenВместе с секретом передан Персональный токен продавцаОблачный сервис не должен принимать Персональные токены. Попросите продавца создать подходящий токен. Виды токенов разобраны в статье «Доступ к данным продавца: токены и OAuth 2.0»

User-Agent

Зачем нужен User-Agent

Сервисный секрет говорит платформе, чей это трафик. Заголовок User-Agent дополняет картину — по нему команда WB API:

  • собирает аналитику по трафику сервиса и предоставляет её сервису;
  • проверяет трафик на соответствие требованиям при рассмотрении заявки;
  • помогает сервису разобрать инцидент, если в запросах нет ключа доступа.

Как сервис получает User-Agent

Значение User-Agent формирует WB API и присылает его сервису по электронной почте, когда сервис подаёт заявку на авторизацию в Каталоге решений для бизнеса. До подачи заявки значения нет — придумывать своё не нужно.

Для размещения в Каталоге решений передавать User-Agent обязательно: по нему платформа считает количество пользователей сервиса, а это одно из требований к размещению.

Зарегистрированному сервису, который работает без заявки в Каталог, User-Agent не присылают: платформа опознаёт такой сервис по сервисному секрету. Это верно и тогда, когда сервису уже открыт доступ в Профиль компании ради секрета.

Как передавать User-Agent

Передавайте полученное значение без изменений в заголовке User-Agent во всех запросах к WB API.

Не добавляйте в User-Agent токены продавцов, сервисный секрет и персональные данные. Заголовок попадает в логи и системы мониторинга WB API — это не место для секретов.


Лимиты запросов

WB API ограничивает частоту запросов — так платформа защищается от перегрузок и остаётся стабильной для всех. Лимит задаётся для отдельного метода или для группы методов: внутри одной категории данных значения различаются. Размер лимита зависит и от типа токена.

По каким лимитам идёт трафик сервиса, зависит от способа подключения:

Как подключён сервисКак считаются лимиты
Базовый токен, сервис ещё не зарегистрирован и секрета нетПлатформа не видит за запросами сервис: действуют лимиты Базового токена — те же, что у продавца с собственной интеграцией
Базовый токен с сервисным секретомПрименяются лимиты Базового токена с секретом — в документации они указаны у метода отдельной строкой; у части методов они выше, чем без секрета
Сервисный токен, доступный сервисам в Каталоге решенийЛимиты считаются отдельно по паре «сервис + продавец» и не зависят от других интеграций продавца. Запрос с Сервисным токеном без секрета не пройдёт

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

Точные значения указаны в описании каждого метода в документации WB API в блоке «Лимит запросов». В нём указаны параметры:

  • Период;
  • Лимит;
  • Интервал;
  • Всплеск (burst).

Заголовки ответа о лимитах

Следить за расходом лимита можно прямо по ответам API:

ЗаголовокКогда возвращаетсяЧто означает
X-Ratelimit-RemainingВо всех ответах, кроме 429Сколько запросов можно отправить без дополнительной паузы. Значение уменьшается по мере отправки запросов и восстанавливается со временем
X-Ratelimit-RetryТолько в ответе 429Через сколько секунд можно повторить запрос
X-Ratelimit-LimitТолько в ответе 429Максимальный доступный всплеск запросов
X-Ratelimit-ResetТолько в ответе 429Через сколько секунд всплеск восстановится полностью

Если X-Ratelimit-Remaining приближается к нулю, увеличьте паузу между запросами, не дожидаясь ошибки 429.

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

Превышение лимита возвращает ошибку 429 Too Many Requests:

  1. Прочитайте значение X-Ratelimit-Retry — оно показывает количество секунд до безопасного повторного запроса.
  2. Подождите указанное время и повторите запрос. Повтор раньше срока снова вернёт 429.
  3. Если ошибка возникает снова, увеличивайте паузу между следующими попытками.
  4. Ограничьте число попыток и распределяйте запросы равномерно во времени, а не пакетами.

В отдельных группах методов запрос с ошибкой может учитываться как несколько обычных запросов. В таком случае значение X-Ratelimit-Remaining уменьшается сразу на несколько единиц. Такие случаи отмечены в блоке лимитов метода в документации.


Что дальше

  • Виды сервисов и уровни работы с платформой → статья «WB API для сервисов»
  • Токены продавцов, OAuth 2.0 и правила работы с ними → статья «Доступ к данным продавца: токены и OAuth 2.0»
  • Точные лимиты, схемы и коды ответов каждого метода → документация WB API
  • Изменения в методах → Release Notes

Кейсы

Найдите решение по другим вопросам
WB API case
Доступ к данным продавца: токены и OAuth 2.0
WB API case
WB API для сервисов
WB API case
Карта вызовов WB API