API Wildberries для Python

Коротко. API Wildberries для Python: получаете токен в личном кабинете, дергаете нужный домен через библиотеку requests и складываете сырые данные в свою базу. Так собирается wildberries api аналитика без сторонних сервисов: продажи, заказы, остатки, воронка карточек и финансовый отчет. Ниже: рабочие эндпоинты, лимиты, готовый код и список граблей.

Зачем селлеру своя интеграция с API

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

Свой сбор через API решает три задачи. Первая: единое хранилище, где заказы, продажи и остатки лежат за все время. Вторая: свои метрики, которых нет в кабинете: маржа по SKU, оборачиваемость, ДРР по каждой карточке. Третья: автоматизация цен и остатков без ручного труда.

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

Что умеет wildberries api аналитика

API поделен на категории. Каждая отвечает за свой кусок бизнеса и живет на отдельном домене. Токен вы выпускаете под конкретные категории, а не один на все.

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

Основные категории и их домены

Домены могут дополняться: WB регулярно выкатывает новые методы. Актуальный список категорий всегда в официальной документации на dev.wildberries.ru. Но для 90% аналитических задач хватает трех первых строк таблицы.

Как получить токен: пошагово

Токен: это ваш пропуск. Без него любой запрос вернет 401. Выпускается он за минуту в кабинете продавца.

1. Зайдите в личный кабинет Wildberries под учеткой с правами.
2. Откройте раздел «Настройки», затем «Доступ к API».
3. Нажмите «Создать новый токен».
4. Отметьте нужные категории. Для аналитики: Статистика, Аналитика, Цены и скидки.
5. Выберите уровень доступа. «Только чтение» безопаснее: токен сможет читать данные, но не менять их.
6. Скопируйте токен сразу. Второй раз система его не покажет.

Уровень доступа: ключевой момент безопасности. Если задача только собирать аналитику, ставьте «только чтение». Тогда даже утекший токен не даст никому переписать ваши цены или карточки. Токен с правом записи выпускайте отдельно и только под конкретную задачу автоматизации.

Куда класть токен в коде

Токен идет в заголовок Authorization. Хранить его в коде нельзя. Держите в переменной окружения или в отдельном файле, который не попадает в git.

Первый запрос на Python: продажи и остатки

Вся связка wildberries python api строится на библиотеке requests. Ничего экзотического не нужно. Ставим одну зависимость и делаем GET-запрос с токеном в заголовке.

Базовый пример забирает продажи с указанной даты. Параметр dateFrom обязателен. Параметр flag управляет режимом выгрузки: об этом ниже, в разделе про ошибки.

• Продажи: GET на statistics-api.wildberries.ru/api/v1/supplier/sales
• Заказы: GET на statistics-api.wildberries.ru/api/v1/supplier/orders
• Остатки: GET на statistics-api.wildberries.ru/api/v1/supplier/stocks
• Поставки: GET на statistics-api.wildberries.ru/api/v1/supplier/incomes
• Финансовый отчет: GET на statistics-api.wildberries.ru/api/v5/supplier/reportDetailByPeriod

Каркас скрипта выглядит так. Токен из окружения, домен статистики, обработка кода ответа. На этом каркасе строится дальше все остальное.

1. Читаем токен из переменной окружения через os.environ.
2. Собираем заголовок: словарь с ключом Authorization и значением токена.
3. Формируем параметры: dateFrom в формате даты и при нужде flag.
4. Делаем requests.get с url, headers и params.
5. Проверяем response.status_code перед разбором тела.
6. Разбираем response.json в список словарей и пишем в базу.

Ответ приходит в JSON. Каждая строка: один факт продажи или заказа с полями по цене, скидке, складу, региону и артикулу. Дальше это удобно грузить в pandas и считать что угодно.

Воронка продаж по карточкам: главный метод аналитики

Домен seller-analytics-api дает то, чего нет в сырой статистике: воронку по каждой карточке. Метод /api/v2/nm-report/detail возвращает по товару показы, клики, добавления в корзину, заказы и выкупы за период.

Это сердце аналитики. По воронке видно, где теряются деньги. Мало показов: проблема в SEO карточки и рекламе. Много показов, мало кликов: слабое главное фото. Клики есть, корзины нет: цена или отзывы. Каждый этап: точка роста.

Метод работает через POST. В теле передаете период, фильтры по nmID, брендам или тегам и параметр limit. Максимум по limit подняли до 1000 строк на запрос, так что большой ассортимент выгружается пачками с пагинацией.

Сценарии применения для бизнеса

• Поиск проседающих SKU. Раз в день тянете воронку, сравниваете конверсию карточек с прошлой неделей, ловите падение до того, как оно ударит по выручке.
• Расчет ДРР по товару. Складываете выручку из статистики и расходы на рекламу из advert-api. Видите реальную рекламную долю по каждому артикулу, а не в среднем по кабинету.
• Оборачиваемость и неликвиды. Соединяете остатки и продажи за 30 дней. Товары, которые лежат мертвым грузом, видны сразу: их пора распродавать или вывозить со склада, чтобы не платить за хранение.
• Прогноз поставок. По скорости продаж и текущим остаткам считаете, на сколько дней хватит запаса, и планируете поставку заранее.

Лимиты запросов: как не словить бан

API строго ограничивает частоту. Превысите: получите код 429 и временную блокировку. Лимиты у методов разные, и это первое, обо что спотыкаются новички в wildberries python api.

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

Правила, которые спасают

Инкрементальный сбор: главный прием. Метод продаж по полю lastChangeDate отдает только изменения с нужной даты. Берете значение lastChangeDate из последней строки прошлой выгрузки и передаете его как dateFrom в следующей. Так вы не гоняете гигабайты каждый запуск.

Частые ошибки при работе с API

Одни и те же грабли повторяются у всех, кто собирает аналитику сам. Разберем их, чтобы вы не потеряли неделю на отладку.

Путаница с параметром flag

В методах продаж и заказов параметр flag меняет всю логику. При flag=0 или без него API отдает все строки, где lastChangeDate больше или равно dateFrom: это режим для инкрементального сбора. При flag=1 API отдает записи ровно за одну дату dateFrom. Перепутаете: получите не те данные и неверные отчеты.

Обрезка большой выгрузки

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

Локальное время вместо UTC

Даты в API завязаны на часовой пояс. Передадите московское время как есть: сместите период на три часа и недосчитаетесь заказов на стыке суток. Работайте с датами аккуратно и сверяйте пояс.

Один токен на все категории

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

Нет обработки кодов ответа

Код тянет json сразу, без проверки статуса. Прилетает 429 или 401, тело не JSON, скрипт падает с непонятной ошибкой. Всегда проверяйте status_code до разбора тела и логируйте, что именно вернул сервер.

Библиотека или свой код: что выбрать

Писать все с нуля не обязательно. Под Python есть готовые обертки, которые скрывают домены и заголовки за удобными методами. Но и у своего кода есть плюсы.

Критерии выбора

• Берите готовую библиотеку, если хотите быстро проверить гипотезу, а методы стандартные. Обертка сэкономит день на рутине.
• Пишите свой клиент, если нужна тонкая логика ретраев, свой формат хранения и полный контроль над каждым запросом.
• Проверяйте актуальность. WB меняет API часто. Заброшенная библиотека с последним обновлением год назад: риск отстать от новых методов и полей.
• Смотрите на requests под капотом. Даже с библиотекой стоит понимать, какой домен и эндпоинт она дергает: иначе отладка превратится в гадание.

Разумный путь: тонкий свой слой поверх requests с ретраями и кешем плюс pandas для расчетов. Тяжелые зависимости подключаете, только когда они реально экономят время.

Чек-лист запуска своей аналитики

1. Выпустили токен «только чтение» под категории Статистика и Аналитика.
2. Положили токен в переменную окружения, а не в код.
3. Сделали первый GET на продажи и убедились, что приходит JSON.
4. Настроили инкрементальный сбор по lastChangeDate.
5. Добавили паузы и ретрай на код 429.
6. Подключили метод воронки nm-report/detail для конверсий.
7. Свели данные в базу и посчитали первые метрики: маржу, оборачиваемость, ДРР.
8. Поставили скрипт на расписание, чтобы данные обновлялись сами.

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

Частые вопросы

Нужен ли программист, чтобы собрать аналитику через API?

Базовый сбор реально поднять самому на Python и requests за пару вечеров: логика простая, GET-запрос с токеном в заголовке. Но для стабильной системы с ретраями, хранилищем и расчетом метрик по всему ассортименту лучше привлечь разработчика. Иначе поддержка и рост числа методов быстро съедят время.

Токен Wildberries имеет срок действия?

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

Чем сырой API отличается от готовых сервисов аналитики?

Готовые сервисы дергают тот же самый API Wildberries, но показывают уже посчитанные отчеты за подписку. Свой сбор дает полный контроль: данные ваши, метрики любые, платить не нужно. Цена этого: время на разработку и поддержку кода. Выбор зависит от масштаба и наличия рук в команде.

Можно ли через API менять цены и остатки, а не только читать?

Да, категория «Цены и скидки» на домене discounts-prices-api позволяет массово менять ценники, а маркетплейс-методы управляют заказами. Для этого нужен токен с правом записи. Такой токен выпускайте отдельно от аналитического и берегите: с ним можно переписать данные вашего магазина.

Почему воронка продаж отдает данные с задержкой?

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