API Wildberries для продавцов: токен, OAuth 2.0 и категории данных

API Wildberries позволяет передавать данные между кабинетом продавца и внешней системой без ручных выгрузок. Через интеграцию можно получать заказы, продажи, остатки, отчёты и данные по карточкам, работать с продвижением. Для подключения нужны способ авторизации, подходящие разрешения и порядок поддержания доступа.

Если подключаемый сервис поддерживает OAuth 2.0, предпочтителен этот способ. Токен подходит для собственных программ и разработок, а также для стороннего сервиса без OAuth 2.0. Тип токена выбирают по размещению системы, допустимому получателю доступа и среде тестирования.

Что такое API Wildberries и зачем он продавцу

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

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

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

Персональный токен или OAuth 2.0: что выбрать

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

Персональный токен: собственная или локальная система

Персональный токен предназначен для собственных программ и корпоративных систем на своей или арендованной инфраструктуре. К этому сценарию относятся готовые ERP/CRM в редакции on-premise, включая коробочную 1С на серверах компании или компьютерах пользователей. Часть категорий доступна только через персональный токен — например, управление пользователями.

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

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

Сервисный токен: облачный сервис из каталога

Для облачного сервиса из «Каталога готовых решений для бизнеса» Wildberries выбирайте сервисный токен. Он привязан к конкретному сервису и работает только с ним. При создании выберите сервис из каталога: необходимые категории данных и уровни доступа заполнятся автоматически. Затем подтвердите создание и передайте токен этому сервису.

Базовый и тестовый токены: разные среды

Базовый токен подходит для тестирования интеграции на реальных данных перед запуском и для случаев, когда нельзя использовать сервисный или персональный токен. Категории данных и уровень доступа — только чтение или чтение и запись — вы выбираете самостоятельно. Ограниченный набор данных для базового токена предусмотрен на будущее.

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

Как подключиться по API через OAuth 2.0

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

Как создать токен Wildberries и подключить систему

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

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

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

Как создать, обновить или удалить токен WB API

Категории данных API Wildberries

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

Сопоставьте доступ с задачей интеграции. Для персонального токена неясные настройки уточните у отвечающего за систему IT-специалиста; для сервисного настройки заполняются после выбора сервиса.

Для анализа спроса данные API полезно соединять с поисковыми запросами Wildberries, а конверсию — с воронкой продаж. Это помогает связать событие в учёте с этапом выбора и покупки товара.

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

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

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

Что делать после смены телефона владельца

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

В разделе «Интеграции по API» появится предупреждение, а на токенах будет указана дата отключения. Ориентируйтесь на эту дату при обновлении всех подключений. За 3 дня до окончания карантина также придёт уведомление. После карантина токены, выпущенные до смены телефона, автоматически отзываются, а интеграции отключаются.

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

Как устроить безопасное подключение

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

• Храните токены в защищённом месте. Используйте менеджер паролей или защищённое хранилище, а не текстовый файл, мессенджер или общую таблицу.
• Ограничьте круг сотрудников. Доступ к ключу нужен только ответственным за API-интеграцию.
• Ведите учёт подключений. Запишите назначение каждого токена и дату прекращения действия; при необходимости — дату создания.
• Удаляйте ненужный доступ. При прекращении сотрудничества со сторонним сервисом или разработчиком немедленно удалите токен. Удаление выполняет владелец кабинета.

Не публикуйте токен в коде, скриншоте, инструкции или журнале запросов. Если секрет попал в открытый канал, отзовите его, создайте новый и обновите подключение.

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

• Выдавайте минимум прав. Если система только анализирует данные, ей достаточно чтения; права на изменение цен и карточек для этой задачи не нужны.
• Разделяйте среды. Для изолированной отладки используйте тестовый токен песочницы. Тестирование на реальных данных с базовым токеном планируйте отдельно.
• Храните секрет отдельно от кода. Приложение получает его из защищённой конфигурации во время запуска.
• Фиксируйте вызовы без секрета. В журнале нужны время, метод, результат и идентификатор операции.
• Ограничивайте повторы. При ошибке предусмотрите паузу и обработку повторного запроса: бесконечный цикл создаёт лишнюю нагрузку и может привести к дублям.
• Готовьте отзыв доступа. Команда должна знать, какой токен отключить и какие процессы после этого остановятся.

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

Для ревизии доступа к кабинету пригодится отдельный разбор защиты продавца от мошенничества на Wildberries.

Ограничения, которые нужно учесть разработчику

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

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

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

Как проверить интеграцию перед запуском

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

1. Проверьте ключ и срок. Убедитесь, что в настройках введён правильный токен и срок его действия не истёк.
2. Проверьте получение данных. Измените в кабинете продавца данные, которые интеграция должна получать. Результат проверки — появление этого изменения в подключённом сервисе.
3. Проверьте передачу данных, если она предусмотрена. Измените в своей системе только те сведения, которые должны поступать на WB Partners. Результат — появление изменения в кабинете продавца.

Например, если сервис поддерживает работу с отзывами, подготовьте и опубликуйте в нём ответ на отзыв. Затем проверьте, появился ли ответ в кабинете WB Partners. Этот сценарий подходит только для интеграции, которая действительно выполняет такую операцию.

Дополнительная приёмка собственной разработки

1. Сверьте права. Каждый разрешённый раздел должен соответствовать реальной функции.
2. Пройдите один объект целиком. Возьмите заказ или товар и проследите его от ответа API до конечного отчёта.
3. Смоделируйте повтор. Повторная загрузка той же записи не должна создавать дубль.
4. Проверьте восстановление соединения. В тестовой среде прервите обмен и убедитесь, что после восстановления система продолжает работу с предусмотренной контрольной точки.
5. Проверьте обработку отзыва доступа. Для отдельного тестового подключения убедитесь, что после удаления его токена система показывает понятную ошибку и прекращает защищённые операции. Удаление выполняет владелец кабинета.
6. Сверьте итог. Сопоставьте остатки, продажи и финансы с контрольной выгрузкой кабинета за тот же период и по тем же объектам.

Финальную прибыль проверяйте через юнит-экономику Wildberries: исправная передача данных ещё не означает, что товар приносит прибыль.

Что делать, если интеграция не работает

Сначала проверьте правильность токена и срок действия. Если прошло 180 дней, создайте новый ключ и замените его в сервисе. При общем токене обновите все использующие его интеграции. Если владелец менял телефон, проверьте предупреждение и дату отключения в разделе «Интеграции по API», затем перевыпустите токены и обновите подключения.

После замены повторите проверку передачи изменений. Если проблема сохраняется, выберите адресата по тому, где возник сбой.

Плюсы и ограничения API

• Скорость против сложности. Данные поступают без ручной выгрузки, зато интеграцию нужно поддерживать при изменениях методов.
• Полнота против нагрузки. Частые запросы дают более свежую картину, но упираются в лимиты и требуют управления очередью.
• Автоматизация против ответственности. Система выполняет больше операций, поэтому нужны роли, журналы и согласование опасных изменений.
• Единый отчёт против различий источников. Данные можно объединить, но у заказов, продаж и финансов разные моменты признания.

Для продавца ценность API появляется, когда автоматизация сокращает конкретную операцию: обновление остатков, сбор заказов, контроль рекламы или сверку финансов. Подключение «на всякий случай» добавляет расходы на сопровождение.

Кому подходит API Wildberries

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

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

Для сравнения способов анализа используйте обзор показателей и инструментов аналитики Wildberries. Он помогает отделить задачи интеграции от тех, которые уже закрывает кабинет.

Хотите познакомиться с SelSup для работы на маркетплейсах? Запишитесь на демонстрацию SelSup.

Частые ошибки

• Персональный токен для облачного сервиса. Такой способ использования запрещён. Проверяйте тип токена по размещению системы и допустимому получателю доступа.
• Один токен для всех сервисов. При его удалении остановятся все зависимые подключения. Создавайте отдельный ключ для каждой интеграции; при перевыпуске общего ключа заменяйте его везде.
• Пропущенный срок обновления. Через 180 дней доступ по токену прекращается. Храните дату окончания в защищённом учёте и обновляйте ключ в подключённой системе.
• Смена телефона без обновления подключений. Во время карантина часть запросов выполняется с ошибками, а после его окончания старые токены отзываются. Перевыпустите ключи до указанной даты отключения.
• Максимальные права без необходимости. Система, которой нужно только чтение, получает лишнюю возможность менять данные. При самостоятельной настройке выдавайте только нужные категории и уровень доступа.
• Секрет в общей таблице. Ключ могут скопировать люди, которые не отвечают за интеграцию. Используйте защищённое хранилище и ограничивайте доступ.
• Повтор без дедупликации. Один заказ или расход может учитываться дважды. В собственной системе предусмотрите уникальный идентификатор и идемпотентную запись.
• Отсутствие контрольной сверки. Обмен работает технически, но отчёт может расходиться с кабинетом. Сопоставляйте контрольную выгрузку и суммы за один период.

Итог: с чего начать

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

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