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

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

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

Доступ к данным продавца: токены и OAuth 2.0

Какие токены может использовать сервис, что проверять перед подключением и как работает упрощённое подключение продавцов

0
content

У сервиса нет собственного доступа к данным магазина — доступ всегда выдаёт продавец. Есть два способа подключения:

Токен. Продавец создаёт его в личном кабинете WB Партнёры и передаёт сервису. Способ доступен любому решению — и коробочному, и облачному; тип токена зависит от того, как сервис работает с платформой.

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

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


Доступ по токену

Как устроен флоу

  1. Продавец создаёт токен в личном кабинете WB Партнёры: выбирает категории данных и уровень доступа.
  2. Продавец передаёт токен сервису — обычно вставляет его в форму подключения магазина в личном кабинете на стороне сервиса.
  3. Сервис проверяет токен: тип, срок действия, категории данных, уровень доступа.
  4. Сервис передаёт токен в запросах к WB API и работает с данными магазина в пределах предоставленного доступа.

Токен фиксирует границы доступа: категории данных — разделы данных, к которым сервис получает доступ (товары, заказы, цены, аналитика и другие), и уровень доступа — «Только чтение» или «Чтение и запись». Всё, что сервис делает по токену, он делает от имени продавца.

Для каждого подключённого магазина используется токен соответствующего продавца. Токен одного продавца не даёт доступа к данным другого.

Виды токенов

ТипДля чего используетсяОграничения
БазовыйДля подключения облачного сервиса, который ещё не опубликован в Каталоге решений, а также для проверки интеграции на реальных данныхДоступен ограниченный набор категорий данных
СервисныйДля подключения продавца к сервису из Каталога решенийПривязан к конкретному сервису и может использоваться только этим сервисом

Ещё два типа сервису принимать не нужно, но распознавать — обязательно.

Персональный предназначен только для собственных программ продавца и on-premise-решений на его инфраструктуре. Облачным сервисам запрещено принимать Персональные токены: запросы с ними не пройдут.

Тестовый работает только с песочницей WB API. Для работы с данными продавца он не подходит: если продавец прислал такой токен, отклоните его с понятным сообщением.

Особенность Сервисного токена

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

У части методов есть дополнительные требования: конкретный тип токена или сервисный секрет в запросе. Они указаны в описании метода в документации. Если требований нет, метод работает с токеном любого типа. Лимиты запросов тоже зависят от типа токена — точные значения смотрите в описании метода. Как устроены лимиты и что такое сервисный секрет — в статье «Идентификация сервиса в WB API».

Где продавец создаёт токен

Токены выпускает владелец личного кабинета WB Партнёры (seller.wildberries.by): в меню профиля — раздел Интеграции по API. При создании продавец выбирает тип токена, категории данных и уровень доступа, а для Сервисного — просто сервис из списка. Токен действует 180 дней, затем нужно выпустить новый.

Токен показывается один раз — сразу после создания. Повторно посмотреть его в кабинете нельзя: потерянный токен заменяют новым.


Когда сервису доступен Сервисный токен

Сервисный токен доступен облачным сервисам, опубликованным в Каталоге решений, — витрине готовых сервисов для продавцов Wildberries. Размещение в Каталоге открывает возможность подключения через Сервисный токен и OAuth 2.0. Подробнее об уровнях работы с платформой — в статье «WB API для сервисов».

Что это даёт сервису: продавцу не нужно разбираться в настройках — они заполняются автоматически по требованиям сервиса, а лимиты Сервисного токена собственные и не зависят от других интеграций продавца.

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

Сначала сервис размещается в Каталоге решений: напишите на business-solutions@rwb.ru — опишите сервис и задачу, которую он решает для продавцов.

После размещения тем же письмом запросите включение Сервисного токена для сервиса. Команда WB API согласует категории данных и уровень доступа — по ним заполняется форма создания токена у продавца — и пришлёт ссылку на эту форму.

Добавьте ссылку и инструкцию в свою документацию

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

  1. Перейти по ссылке — форма создания токена откроется с уже заполненными настройками.
  2. Подтвердить создание токена.
  3. Сразу скопировать токен — повторно он не показывается.
  4. Вставить токен в поле подключения магазина в кабинете сервиса.

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


Доступ по OAuth 2.0

Как работает подключение

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

Из Каталога решений:

  1. Продавец выбирает сервис в Каталоге решений и начинает подключение.
  2. Сервис запрашивает доступ только к тем данным, которые нужны ему для работы.
  3. Продавец видит список запрашиваемых данных и подтверждает доступ.
  4. Система генерирует токен и автоматически передаёт его сервису.

Из кабинета сервиса:

  1. Продавец в личном кабинете сервиса нажимает кнопку подключения к данным продавца Wildberries.
  2. Сервис перенаправляет продавца на портал WB Партнёры — на страницу со списком запрашиваемых данных. Если продавец ещё не авторизован на портале, он входит в аккаунт.
  3. Продавец подтверждает доступ к данным.
  4. Продавец автоматически возвращается в кабинет сервиса. Система генерирует токен и передаёт его сервису.

Второй путь для многих сервисов удобнее: продавцу не нужно уходить на портал и искать сервис в Каталоге — подключение начинается там, где он уже работает.

Главное преимущество — продавец не передаёт токен руками: нечего копировать и терять. Дальше интеграция обслуживает себя сама:

  • Токены обновляются автоматически. Не нужно следить за сроком действия и просить продавца о перевыпуске каждые 180 дней.
  • Подключение занимает пару кликов вместо создания токена по инструкции — меньше продавцов теряется на этом шаге.

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

Каким сервисам доступен

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

ПараметрСервисный токенOAuth 2.0
ПодключениеПродавец создаёт токен в кабинете и добавляет его в сервисПродавец подтверждает доступ — токен передаётся автоматически
Срок действияКаждые 180 дней, новый токен создаёт продавецТокены обновляются автоматически
Реализация на стороне сервисаПриём и проверка токенаOAuth-флоу: обмен кода на токены и их ротация. Полученный токен тоже проверяйте: продавец мог подтвердить не весь запрошенный доступ, а у давно подключённых продавцов набор данных может отличаться от текущего

Рекомендуем сделать OAuth 2.0 основным способом подключения, а Сервисный токен оставить запасным.

Как подать заявку

Напишите на business-solutions@rwb.ru: опишите сервис и задачу и укажите, что планируете OAuth 2.0. Документацию по OAuth 2.0 вышлют по запросу на ту же почту.


Работа с токеном на стороне сервиса

Проверьте токен продавца перед использованием

Токен WB API — это JWT (JSON Web Token, стандарт RFC 7519). Его полезная нагрузка (payload) читается проверенной JWT-⁠библиотекой без проверки подписи. В сторонние онлайн-декодеры чужой токен не вставляйте. Прежде чем сохранить токен и запустить интеграцию, проверьте четыре параметра.

1. Тип токена. Определяется по полям payload:

Типaccfort
Базовый1Поле отсутствуетfalse
Тестовый2Поле отсутствуетtrue
Персональный3selffalse
Сервисный4asid:{ID сервиса}false

Если вы облачный сервис, то принимайте Базовый токен или Сервисный, выпущенный именно для вашего сервиса: ID в поле for должен совпадать с ID сервиса. ID своего сервиса возьмите из сервисного секрета: это значение поля asid в его payload. Как прочитать секрет — в статье «Идентификация сервиса в WB API». Персональный, Тестовый и Сервисный токен другого сервиса отклоняйте с понятным сообщением, какой токен нужен.

2. Срок действия. Поле exp — время истечения, Unix timestamp. Истёкший токен возвращает ошибку 401 — по exp предупреждайте продавца о перевыпуске заранее.

3. Категории данных. Поле s — битовая маска, каждый бит — доступ к одной категории. Убедитесь, что токену доступны категории всех методов, которые вызывает сервис.

4. Уровень доступа. Отдельный бит маски s означает «токен только на чтение». Такой токен не выполнит методы, изменяющие данные (POST, PUT, DELETE), — для них нужен уровень «Чтение и запись».

Правила использования токенов — в разделе «Авторизация» документации WB API.

Как передавать токен в запросах

Токен передаётся в заголовке Authorization каждого запроса — целиком, без префикса Bearer:

curl -H "Authorization: {токен_продавца}" \
  https://common-api.wildberries.by/ping

Метод /ping есть у каждого хоста — им удобно проверять подключение: он подтверждает, что запрос доходит до WB API, токен действителен, а категория токена совпадает с сервисом хоста.

Ошибки 401 и 403

При ошибке авторизации WB API возвращает HTTP-код и JSON-тело ответа. Причина ошибки указана в поле detail. 401 Unauthorized — токен не принят: не передан, просрочен или отозван. 403 Forbidden — токен принят, но выполнить этот метод им нельзя: например, у токена нет категории данных метода, уровень доступа «Только чтение» или неподходящий тип токена.

КодПричинаЧто делать
401Токен не передан, обрезан или повреждёнПроверьте заголовок Authorization: токен должен передаваться целиком, без Bearer и лишних пробелов
401Срок действия токена истёкПопросите продавца выпустить новый токен и замените старый
401Токен отозван — продавец удалил его в кабинетеПопросите продавца выпустить новый токен
403У токена нет категории данных, к которой относится методИзменить уже созданный токен нельзя — продавцу нужно создать новый с необходимыми категориями
403Токен с уровнем доступа «Только чтение» используется в методе, изменяющем данные продавцаИзменить уже созданный токен нельзя — продавцу нужно создать новый с уровнем доступа «Чтение и запись»
403Используется неподходящий тип токена: Персональный, Сервисный токен другого сервиса или тип, не соответствующий требованиям методаЕсли метод требует определённый тип, это указано в его описании в документации — попросите у продавца токен нужного типа. Если пришёл Персональный или чужой Сервисный, описание метода не поможет: такой токен принимать нельзя, определяйте тип на приёмке по полям acc и for

При этих ошибках показывайте продавцу понятное сообщение: какой токен нужен и как его создать.


Что дальше

  • Понять платформу и уровни работы с ней → статья «WB API для сервисов»
  • Настроить идентификацию запросов и разобраться в лимитах → статья «Идентификация сервиса в WB API»
  • Правила авторизации и использования токенов → раздел «Авторизация» в документации
  • Изменения WB API → Release Notes

Кейсы

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