Карта вызовов WB API

Какие методы вызывать и в каком порядке для основных задач продавца — от карточек товаров и цен до заказов, продвижения, финансов и поисковой аналитики.

17
content

Личный кабинет и токен

Все вызовы в этой статье выполняются с токеном, созданным в личном кабинете WB Партнёры. Ещё нет кабинета? Начните со статьи «Как начать работать с WB API: от регистрации до токена».

Категории должны совпадать

Категории данных токена определяют, какие методы доступны. Если категория токена не совпадает с категорией метода, API вернёт 403.

Единого базового адреса нет

Методы разных разделов работают на разных хостах домена wildberries.kg. Хост указан на странице каждого метода в документации.

Эта карта показывает, какие методы WB API вызывать и в каком порядке для основных задач продавца. Здесь приведены названия методов и последовательность вызовов. Параметры, тела запросов, схемы ответов и лимиты описаны в документации — обращайтесь к ней, когда нужны подробности конкретного вызова.

Выберите задачу в оглавлении. В каждом разделе вызовы перечислены в нужном порядке и отмечена типичная ошибка.

Перед началом

Вам нужны личный кабинет и токен. API позволяет программно работать с личным кабинетом WB Партнёры, поэтому сначала нужен кабинет. Если его ещё нет, начните со статьи «Как начать работать с WB API: от регистрации до токена». Все дальнейшие вызовы выполняются с токеном, созданным в этом кабинете.

У токена фиксированный набор категорий данных, которые определяют доступ к методам. Поэтому токен, с которым доступны заказы, может возвращать 403 при обращении к методам продвижения. Чтобы добавить нужную категорию, потребуется создать новый токен. Выбирайте категории под методы, которые планируете вызывать: см. Авторизация.

Единого базового адреса нет. Методы разных разделов работают на разных хостах домена wildberries.kg. Хост для запроса указан на странице каждого метода в документации.

Прежде чем строить интеграцию, проверьте токен двумя вызовами:

  • GET /ping — вызовите на хосте сервиса, с которым собираетесь работать. Метод проверяет, что запрос доходит до API, токен действителен и его категория соответствует сервису. Он не предназначен для проверки общей доступности сервисов WB. См. Проверка подключения к WB API.
  • GET /api/v1/seller-info — проверьте, что токен относится к нужному личному кабинету.

401 — токена нет, он некорректен или истёк. 403 — токен принят, но этот метод с ним недоступен: например, у токена нет категории нужного раздела или метод требует другой тип токена. Повтор того же запроса не поможет — проверьте токен и доступ к методу.

Ещё не работали с WB API? В статье «Первый запрос за 15 минут» эти два вызова разобраны пошагово.

Общий порядок

Первую интеграцию обычно строят в таком порядке:

  1. Сначала каталог. Всё связано с карточками товаров. Создайте их или получите уже существующие, прежде чем настраивать цены, остатки и продвижение.
  2. Цены и остатки. Установите цены и поддерживайте остатки в актуальном состоянии — эти данные приходится обновлять регулярно.
  3. Заказы — постоянно. Когда товары поступают в продажу, заказы приходят в разное время. Цикл FBS «опрос → сборка → передача в доставку» работает, пока вы продаёте. Параллельно можно получать оперативную статистику продаж.
  4. Затем продвижение и аналитика. Кампании, общение с покупателями, финансы и поисковая аналитика используют данные уже существующих карточек, поэтому их подключают в последнюю очередь.
Общий порядок интеграции с WB API: карточки товаров, затем цены и остатки, постоянный цикл обработки заказов и параллельно статистика продаж, затем продвижение, общение с покупателями, финансы и поисковая аналитика
Общий порядок интеграции с WB API: карточки товаров, затем цены и остатки, постоянный цикл обработки заказов и параллельно статистика продаж, затем продвижение, общение с покупателями, финансы и поисковая аналитика
Предпросмотр

Как обрабатывается запись данных

Массовая запись в WB API — создание карточек и загрузка цен — выполняется асинхронно: 200 означает, что задание принято, а не что изменение применено. У карточек и цен есть методы чтения и проверки статуса — они названы в разделах ниже и позволяют проверить результат. При загрузке медиа ответ 200 тоже не гарантирует, что файлы загрузились. Различайте состояния «принято» и «применено» и проверяйте результат перед следующим шагом. В разделах ниже это правило не повторяется на каждом шаге — учитывайте его там, где после записи следует проверка статуса.

Карточки товаров

  1. Получите существующие карточки — POST /content/v2/get/cards/list. Метод возвращает одну страницу: по умолчанию 10 карточек, максимум 100 (settings.cursor.limit). Чтобы получить весь каталог, передавайте cursor (updatedAt + nmID) из предыдущего ответа, пока страница не придёт неполной.
  2. Выберите категорию и предмет — карточка создаётся внутри предмета со своим набором характеристик: родительские категории GET /content/v2/object/parent/all → предметы GET /content/v2/object/all → характеристики предмета GET /content/v2/object/charcs/{subjectId}.
  3. Создайте карточки — POST /content/v2/cards/upload.
  4. Проверьте результат — созданные карточки появятся в POST /content/v2/get/cards/list, а несозданные карточки с причинами ошибок — в POST /content/v2/cards/error/list.
  5. Добавьте медиа — файлом через POST /content/v3/media/file или ссылками через POST /content/v3/media/save: новый набор ссылок полностью заменяет прежние медиафайлы карточки.

При редактировании существующих карточек через POST /content/v2/cards/update порядок тот же: после записи проверьте результат. См. Карточки товаров, Категории, предметы и характеристики и Медиафайлы.

Цены и скидки

  1. Получите товары с ценами — GET /api/v2/list/goods/filter.
  2. Установите цены и скидки — POST /api/v2/upload/task.
  3. Проверьте результат — состояние обработанной загрузки: GET /api/v2/history/tasks; состояние необработанной загрузки: GET /api/v2/buffer/tasks; детализация обработанной загрузки с ошибками отдельных товаров: GET /api/v2/history/goods/task.

Типичная ошибка: если скидка снижает цену ниже порога карантина, товар попадает в карантин цен. Загрузка возвращает успех, но товар продолжает продаваться по старой цене. Ошибка товара видна в деталях загрузки (GET /api/v2/history/goods/task), а товары в карантине — в GET /api/v2/quarantine/goods. Проверяйте их после резкого снижения цены. Для товаров с поразмерной установкой цен карантин не применяется. См. Цены и скидки.

Заказы FBS

Цикл при отгрузке со своего склада: опрос → сборка → передача в доставку.

Здесь описан цикл FBS. Для заказов DBS, самовывоза и поставок FBW — свои разделы документации: DBS, Самовывоз, Поставки FBW.

  1. Получайте новые сборочные задания — вызывайте GET /api/v3/orders/new по расписанию. Уведомлений о новых заданиях FBS нет: метод возвращает все новые задания на момент запроса.
  2. Объедините задания в поставку — создайте её через POST /api/v3/supplies и добавьте сборочные задания через PATCH /api/marketplace/v3/supplies/{supplyId}/orders.
  3. Распечатайте стикеры — POST /api/v3/orders/stickers.
  4. Передайте поставку в доставку — PATCH /api/v3/supplies/{supplyId}/deliver.
  5. Отслеживайте статусы сборочных заданий — POST /api/v3/orders/status, по ID заданий. Сами списки заданий не содержат их актуальных статусов.

Параллельно поддерживайте остатки в актуальном состоянии: список складов продавца — GET /api/v3/warehouses, обновление остатков товаров — PUT /api/v3/stocks/{warehouseId}.

Типичная ошибка: передавайте поставку в доставку явно через deliver. Если этого не сделать, поставка автоматически закроется при сканировании её QR-⁠кода или приёмке первого товара на ПВЗ. Неотсканированные товары спустя некоторое время потребуется отгрузить повторно: найдите соответствующие задания через GET /api/v3/supplies/orders/reshipment и перенесите их в другую активную поставку.

Цикл обработки заказов FBS: получить новые задания, объединить в поставку, распечатать стикеры, явно передать в доставку — без вызова deliver поставка закроется при первом сканировании, а неотсканированные товары потребуют повторной отгрузки
Цикл обработки заказов FBS: получить новые задания, объединить в поставку, распечатать стикеры, явно передать в доставку — без вызова deliver поставка закроется при первом сканировании, а неотсканированные товары потребуют повторной отгрузки
Предпросмотр

См. Сборочные задания FBS и Поставки FBS.

Статистика продаж

Оперативные данные о продажах обновляются раз в 30 минут, до появления итогового финансового отчёта:

  • Заказы — GET /api/v1/supplier/orders.
  • Продажи и возвраты — GET /api/v1/supplier/sales.

Оба метода используют пагинацию по времени. Без flag или с flag=0 действует условное ограничение в 80 000 строк на ответ. Передавайте lastChangeDate последней строки в параметр dateFrom следующего запроса, пока не получите пустой массив ([]). Эти данные предварительные и служат для оперативного контроля. Итоговые данные для бухгалтерии берите из финансового отчёта, описанного ниже. См. Основные отчёты.

Продвижение

  1. Получите список кампаний — количество: GET /adv/v1/promotion/count, информация о кампаниях: GET /api/advert/v2/adverts.
  2. Создайте кампанию — POST /adv/v2/seacat/save-ad.
  3. Пополните бюджет кампании — POST /adv/v1/budget/deposit. Перед запуском проверьте бюджет кампании и при необходимости пополните его.
  4. Управляйте кампанией — запуск: GET /adv/v0/start, пауза: GET /adv/v0/pause, изменение ставок: PATCH /api/advert/v1/bids.
  5. Получите статистику — GET /adv/v3/fullstats.

Типичная ошибка: бюджет кампании и баланс — разные вещи. Вы пополняете бюджет конкретной кампании через POST /adv/v1/budget/deposit. Метод GET /adv/v1/balance возвращает данные на уровне кабинета WB Продвижение: счёт, автоматически рассчитываемый баланс и бонусы. Это не пополнение бюджета кампании.

Чтобы участвовать в акциях площадки, получите список через GET /api/v1/calendar/promotions и добавьте подходящие товары через POST /api/v1/calendar/promotions/upload. Методы календаря акций относятся к категории токена «Цены и скидки», а не «Продвижение». См. Кампании и Финансы.

Отзывы, вопросы, чаты и возвраты

GET /api/v1/new-feedbacks-questions показывает, есть ли непросмотренные отзывы и вопросы. Новые события чатов получают через GET /api/v1/seller/events, заявки на возврат — через GET /api/v1/claims. Для работы с обращениями:

  • Отзывы — список: GET /api/v1/feedbacks, ответ: POST /api/v1/feedbacks/answer.
  • Вопросы — список: GET /api/v1/questions, ответ или отклонение: PATCH /api/v1/questions.
  • Чаты с покупателями — список чатов: GET /api/v1/seller/chats, новые события: GET /api/v1/seller/events, отправка сообщения: POST /api/v1/seller/message.
  • Заявки на возврат — список: GET /api/v1/claims, ответ: PATCH /api/v1/claim.

Типичная ошибка: ответ на отзыв или вопрос можно отредактировать только один раз в течение 60 дней после отправки. Доступно ли редактирование, показывает поле editable в объекте answer. Проверяйте ответ до отправки. См. Отзывы и соседние подразделы на той же странице.

Получение данных о бизнесе

Два направления показывают, как идут дела у бизнеса, но отражают разные периоды:

  • Финансы — итоговые данные. Баланс продавца: GET /api/v1/account/balance; список отчётов реализации: POST /api/finance/v1/sales-reports/list; детализации к отчётам реализации за период: POST /api/finance/v1/sales-reports/detailed. Требования к типу токена проверяйте в описании соответствующего метода. Отчёты содержат итоговые данные за период и служат источником для бухгалтерского учёта. См. Баланс и Финансовые отчёты.
  • Поисковая аналитика — как покупатели находят ваши товары. Основной отчёт: POST /api/v2/search-report/report; поисковые запросы по конкретному товару: POST /api/v2/search-report/product/search-texts. Для этих методов нужна подписка «Джем». См. Поисковые запросы по вашим товарам.

Лимиты и ошибки

Лимит запросов указан в документации каждого метода. 429 означает, что он превышен. Заголовок X-Ratelimit-Retry показывает, сколько секунд нужно подождать до повторного запроса — выдержите эту паузу. Особенность категории «Маркетплейс», к которой относятся заказы и поставки: запрос с ответом 4XX учитывается как 10 запросов. Поэтому цикл с постоянными ошибками расходует лимит в десять раз быстрее успешных запросов. Исправьте запрос, прежде чем повторять его.

Ошибки возвращаются со стандартными HTTP-кодами. Возможные коды ответа перечислены на странице каждого метода в документации.

Если метод устаревает

Об устаревании методов сообщают в Release Notes. Если запись касается метода, который вы используете, найдите в записи или в документации метод на замену, сверьте параметры и поля ответа и проверьте переход реальным запросом до даты отключения. Добавление нового поля в ответ не помешает работе программы, если она игнорирует неизвестные поля.

Только знакомитесь с WB API? Какие задачи API автоматизирует и как устроен доступ, рассказано в статье «WB API: обзор для бизнеса».