Сервис отправляет запросы к WB API с токенами продавцов. Токен определяет, от имени какого продавца выполняется запрос, но в случае сервиса платформе также важно понимать, какой именно сервис отправляет этот трафик.
Для идентификации сервиса используются два признака:
Только по размеченному трафику платформа определяет сервис и предоставляет ему инструменты платформы, в том числе расширенные лимиты, если для сервиса доступна эта опция.
В этой статье разберём:
Токены продавцов и OAuth 2.0 разобраны в статье «Доступ к данным продавца: токены и OAuth 2.0».
Сервисный секрет (ключ доступа) — собственный уникальный идентификатор сервиса на платформе WB API. Он подтверждает подлинность сервиса при каждом обращении к WB API. Секрет не привязан к отдельному продавцу: один и тот же секрет передаётся в запросах по всем подключённым продавцам. Срок действия секрета — 180 дней, а момент перевыпуска выбираете вы: новый секрет можно выпустить в любой день этого срока и даже после его окончания. Как только новый выпущен, срок старого сокращается до 30 дней, а если до его конца оставалось меньше — не меняется. Заменить секрет в конфигурации можно без простоя.
Токен продавца и сервисный секрет выполняют разные задачи:
Так платформа отличает запросы сервиса от имени продавца от запросов самих продавцов в рамках собственных интеграций и от запросов других сервисов. Сервисный секрет позволяет WB API идентифицировать трафик зарегистрированного сервиса и применять к нему соответствующие лимиты.
Секрет — признак зарегистрированного сервиса и следующий шаг к Каталогу решений для бизнеса на Wildberries: витрине сервисов для продавцов, где доступны Сервисный токен и подключение по OAuth 2.0.
Чтобы зарегистрировать сервис и получить сервисный секрет, напишите на business-solutions@rwb.ru и опишите сервис и задачу, которую он решает для продавцов. Если сервис уже соответствует требованиям Каталога решений, в том же письме можно подать заявку сразу на размещение.
Дальше порядок такой:
Перевыпуск и отзыв секрета делаются там же, в разделе «Ключи доступа», — обращаться в команду для этого не нужно. На один сервис доступно до двух ключей одновременно, поэтому новый секрет можно выпустить, не отзывая старый. Письмо на business-solutions@rwb.ru нужно, чтобы получить доступ в Профиль компании. Дальше все операции с секретом сервис выполняет сам, а команда отзывает секрет только по просьбе сервиса — например, если тот потерял доступ в Профиль.
Если сервис сразу подаёт заявку на авторизацию в Каталоге решений, отдельное письмо не нужно: инструкцию по получению секрета команда пришлёт в ответ на заявку.
Дата окончания действия указана в самом секрете, в поле exp (см. следующий раздел). Планируйте перевыпуск заранее, чтобы работа сервиса не прерывалась.
Храните сервисный секрет так же надёжно, как пароль: в переменных окружения или защищённом секрет-хранилище. Не публикуйте его в репозиториях и не передавайте третьим лицам. Если секрет скомпрометирован — отзовите его в Профиле компании и сразу выпустите новый.
Прежде чем добавлять секрет в конфигурацию сервиса, убедитесь, что он рабочий. Проверка состоит из двух шагов.
Сервисный секрет — 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 не читается или в нём нет этих полей, секрет повреждён — например, при копировании потерялась часть символов. Скопируйте значение заново из источника, откуда он получен.
Отправьте запрос к любому методу, который использует сервис, с токеном продавца и секретом — как описано в следующем разделе. Успешный ответ означает, что связка «токен + секрет» рабочая.
Если 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 дополняет картину — по нему команда WB API:
Значение User-Agent формирует WB API и присылает его сервису по электронной почте, когда сервис подаёт заявку на авторизацию в Каталоге решений для бизнеса. До подачи заявки значения нет — придумывать своё не нужно.
Для размещения в Каталоге решений передавать User-Agent обязательно: по нему платформа считает количество пользователей сервиса, а это одно из требований к размещению.
Зарегистрированному сервису, который работает без заявки в Каталог, User-Agent не присылают: платформа опознаёт такой сервис по сервисному секрету. Это верно и тогда, когда сервису уже открыт доступ в Профиль компании ради секрета.
Передавайте полученное значение без изменений в заголовке User-Agent во всех запросах к WB API.
Не добавляйте в User-Agent токены продавцов, сервисный секрет и персональные данные. Заголовок попадает в логи и системы мониторинга WB API — это не место для секретов.
WB API ограничивает частоту запросов — так платформа защищается от перегрузок и остаётся стабильной для всех. Лимит задаётся для отдельного метода или для группы методов: внутри одной категории данных значения различаются. Размер лимита зависит и от типа токена.
По каким лимитам идёт трафик сервиса, зависит от способа подключения:
| Как подключён сервис | Как считаются лимиты |
|---|---|
| Базовый токен, сервис ещё не зарегистрирован и секрета нет | Платформа не видит за запросами сервис: действуют лимиты Базового токена — те же, что у продавца с собственной интеграцией |
| Базовый токен с сервисным секретом | Применяются лимиты Базового токена с секретом — в документации они указаны у метода отдельной строкой; у части методов они выше, чем без секрета |
| Сервисный токен, доступный сервисам в Каталоге решений | Лимиты считаются отдельно по паре «сервис + продавец» и не зависят от других интеграций продавца. Запрос с Сервисным токеном без секрета не пройдёт |
Персональные токены к облачным сервисам не относятся: их используют коробочные решения на стороне продавца, и сервисный секрет с ними не передаётся.
Точные значения указаны в описании каждого метода в документации WB API в блоке «Лимит запросов». В нём указаны параметры:
Следить за расходом лимита можно прямо по ответам API:
| Заголовок | Когда возвращается | Что означает |
|---|---|---|
X-Ratelimit-Remaining | Во всех ответах, кроме 429 | Сколько запросов можно отправить без дополнительной паузы. Значение уменьшается по мере отправки запросов и восстанавливается со временем |
X-Ratelimit-Retry | Только в ответе 429 | Через сколько секунд можно повторить запрос |
X-Ratelimit-Limit | Только в ответе 429 | Максимальный доступный всплеск запросов |
X-Ratelimit-Reset | Только в ответе 429 | Через сколько секунд всплеск восстановится полностью |
Если X-Ratelimit-Remaining приближается к нулю, увеличьте паузу между запросами, не дожидаясь ошибки 429.
Превышение лимита возвращает ошибку 429 Too Many Requests:
X-Ratelimit-Retry — оно показывает количество секунд до безопасного повторного запроса.429.В отдельных группах методов запрос с ошибкой может учитываться как несколько обычных запросов. В таком случае значение X-Ratelimit-Remaining уменьшается сразу на несколько единиц. Такие случаи отмечены в блоке лимитов метода в документации.