У сервиса нет собственного доступа к данным магазина — доступ всегда выдаёт продавец. Есть два способа подключения:
Токен. Продавец создаёт его в личном кабинете WB Партнёры и передаёт сервису. Способ доступен любому решению — и коробочному, и облачному; тип токена зависит от того, как сервис работает с платформой.
OAuth 2.0. Продавцу не нужно создавать и передавать токен: достаточно подтвердить доступ к данным своего аккаунта, дальше подключение выполняется автоматически. Способ доступен облачным сервисам, опубликованным в Каталоге решений для бизнеса на Wildberries.
В этой статье разберём, как работают оба способа, какие токены может использовать сервис, что нужно проверить перед началом работы и как разбирать основные ошибки подключения.
Токен фиксирует границы доступа: категории данных — разделы данных, к которым сервис получает доступ (товары, заказы, цены, аналитика и другие), и уровень доступа — «Только чтение» или «Чтение и запись». Всё, что сервис делает по токену, он делает от имени продавца.
Для каждого подключённого магазина используется токен соответствующего продавца. Токен одного продавца не даёт доступа к данным другого.
| Тип | Для чего используется | Ограничения |
|---|---|---|
| Базовый | Для подключения облачного сервиса, который ещё не опубликован в Каталоге решений, а также для проверки интеграции на реальных данных | Доступен ограниченный набор категорий данных |
| Сервисный | Для подключения продавца к сервису из Каталога решений | Привязан к конкретному сервису и может использоваться только этим сервисом |
Ещё два типа сервису принимать не нужно, но распознавать — обязательно.
Персональный предназначен только для собственных программ продавца и on-premise-решений на его инфраструктуре. Облачным сервисам запрещено принимать Персональные токены: запросы с ними не пройдут.
Тестовый работает только с песочницей WB API. Для работы с данными продавца он не подходит: если продавец прислал такой токен, отклоните его с понятным сообщением.
Сервисный токен создаётся по упрощённому сценарию. Продавец выбирает сервис из списка, а необходимые категории данных и уровень доступа заполняются автоматически по требованиям сервиса. Продавцу остаётся проверить настройки, подтвердить создание и передать токен сервису.
У части методов есть дополнительные требования: конкретный тип токена или сервисный секрет в запросе. Они указаны в описании метода в документации. Если требований нет, метод работает с токеном любого типа. Лимиты запросов тоже зависят от типа токена — точные значения смотрите в описании метода. Как устроены лимиты и что такое сервисный секрет — в статье «Идентификация сервиса в WB API».
Токены выпускает владелец личного кабинета WB Партнёры (seller.wildberries.by): в меню профиля — раздел Интеграции по API. При создании продавец выбирает тип токена, категории данных и уровень доступа, а для Сервисного — просто сервис из списка. Токен действует 180 дней, затем нужно выпустить новый.
Токен показывается один раз — сразу после создания. Повторно посмотреть его в кабинете нельзя: потерянный токен заменяют новым.
Сервисный токен доступен облачным сервисам, опубликованным в Каталоге решений, — витрине готовых сервисов для продавцов Wildberries. Размещение в Каталоге открывает возможность подключения через Сервисный токен и OAuth 2.0. Подробнее об уровнях работы с платформой — в статье «WB API для сервисов».
Что это даёт сервису: продавцу не нужно разбираться в настройках — они заполняются автоматически по требованиям сервиса, а лимиты Сервисного токена собственные и не зависят от других интеграций продавца.
Сначала сервис размещается в Каталоге решений: напишите на business-solutions@rwb.ru — опишите сервис и задачу, которую он решает для продавцов.
После размещения тем же письмом запросите включение Сервисного токена для сервиса. Команда WB API согласует категории данных и уровень доступа — по ним заполняется форма создания токена у продавца — и пришлёт ссылку на эту форму.
Ссылку на форму создания токена положите в свою документацию и в интерфейс подключения магазина. Путь продавца по Сервисному токену короткий, и инструкция сводится к четырём шагам:
Пока сервис подключает продавцов по Базовому токену, такой формы нет — продавец выбирает тип токена, категории данных и уровень доступа сам. Укажите в инструкции, что именно выбрать: без неё продавец приносит токен не того типа, без нужных категорий или только на чтение, а каждая такая ошибка — неработающая интеграция и обращение в поддержку сервиса.
Подключение можно начать с двух сторон: из Каталога решений или из кабинета сервиса. Согласие на доступ продавец в обоих случаях даёт на портале WB Партнёры, различаются только старт и финиш.
Из Каталога решений:
Из кабинета сервиса:
Второй путь для многих сервисов удобнее: продавцу не нужно уходить на портал и искать сервис в Каталоге — подключение начинается там, где он уже работает.
Главное преимущество — продавец не передаёт токен руками: нечего копировать и терять. Дальше интеграция обслуживает себя сама:
Продавец может в любой момент отключить сервис в личном кабинете. После этого доступ прекращается. Предусмотрите обработку отзыва доступа, чтобы интеграция завершала работу корректно.
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:
| Тип | acc | for | t |
|---|---|---|---|
| Базовый | 1 | Поле отсутствует | false |
| Тестовый | 2 | Поле отсутствует | true |
| Персональный | 3 | self | false |
| Сервисный | 4 | asid:{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, токен действителен, а категория токена совпадает с сервисом хоста.
При ошибке авторизации WB API возвращает HTTP-код и JSON-тело ответа. Причина ошибки указана в поле detail. 401 Unauthorized — токен не принят: не передан, просрочен или отозван. 403 Forbidden — токен принят, но выполнить этот метод им нельзя: например, у токена нет категории данных метода, уровень доступа «Только чтение» или неподходящий тип токена.
| Код | Причина | Что делать |
|---|---|---|
| 401 | Токен не передан, обрезан или повреждён | Проверьте заголовок Authorization: токен должен передаваться целиком, без Bearer и лишних пробелов |
| 401 | Срок действия токена истёк | Попросите продавца выпустить новый токен и замените старый |
| 401 | Токен отозван — продавец удалил его в кабинете | Попросите продавца выпустить новый токен |
| 403 | У токена нет категории данных, к которой относится метод | Изменить уже созданный токен нельзя — продавцу нужно создать новый с необходимыми категориями |
| 403 | Токен с уровнем доступа «Только чтение» используется в методе, изменяющем данные продавца | Изменить уже созданный токен нельзя — продавцу нужно создать новый с уровнем доступа «Чтение и запись» |
| 403 | Используется неподходящий тип токена: Персональный, Сервисный токен другого сервиса или тип, не соответствующий требованиям метода | Если метод требует определённый тип, это указано в его описании в документации — попросите у продавца токен нужного типа. Если пришёл Персональный или чужой Сервисный, описание метода не поможет: такой токен принимать нельзя, определяйте тип на приёмке по полям acc и for |
При этих ошибках показывайте продавцу понятное сообщение: какой токен нужен и как его создать.