Как устроен WB API

WB API — это набор HTTP-методов, сгруппированных по категориям. Каждая категория отвечает за определённую область работы вашего магазина: товары, заказы, цены, аналитику и так далее.

Категории размещены на разных серверах (доменах). Например, методы для работы с товарами находятся на content-api.wildberries.ru, а методы для заказов — на marketplace-api.wildberries.ru. Это важно знать при настройке интеграции: запрос к методу нужно отправлять именно на тот домен, к которому он относится.

Подробнее о каждой категории — в статье «Категории WB API»

---

Что такое эндпоинт

Эндпоинт (endpoint) — это конкретный адрес (URL), по которому вы обращаетесь к определённой функции API. Каждый эндпоинт выполняет одну задачу: получить список заказов, обновить цену товара, создать карточку и так далее.

Эндпоинт состоит из двух частей:

• Домен — адрес сервера категории. Например: https://content-api.wildberries.ru
• Путь — конкретный метод на этом сервере. Например: /content/v2/cards/upload

Полный URL эндпоинта: https://content-api.wildberries.ru/content/v2/cards/upload

---

Из чего состоит запрос к API

Каждый запрос к WB API включает несколько элементов.

HTTP-метод

Определяет, какое действие вы хотите выполнить:

• GET — получить данные. Например, получить список заказов или информацию о товаре.
• POST — отправить данные или создать что-то новое. Например, создать карточку товара или отправить ответ на отзыв.
• PUT — обновить существующие данные. Например, изменить характеристики товара.
• PATCH — частично обновить данные.
• DELETE — удалить данные.

Заголовки (Headers)

Служебная информация, которая передаётся вместе с запросом. Обязательный заголовок для WB API — Authorization, в который передаётся ваш токен доступа:

Authorization: Bearer ваш_токен

Тело запроса (Body)

Данные, которые вы отправляете. Используется в запросах POST, PUT и PATCH. Формат — JSON.

Параметры запроса (Query Parameters)

Дополнительные параметры, которые передаются в URL после знака ?. Например, фильтр по дате или идентификатор товара.

---

Что возвращает API

В ответ на запрос API возвращает:

Код статуса — число, которое говорит об успехе или ошибке:

• 200 — запрос выполнен, данные в ответе
• 401 — ошибка авторизации (проверьте токен)
• 429 — превышен лимит запросов (подождите и повторите)
• 5XX — ошибка на стороне сервера (повторите позже)

Полная таблица кодов с описаниями и рекомендациями — в статье «Расшифровка кодов ошибок WB API».

Тело ответа — данные в формате JSON. Например, список заказов, информация о товаре или подтверждение операции.

Заголовки ответа — служебная информация. Например, заголовок X-Ratelimit-Remaining показывает, сколько запросов вы ещё можете отправить без паузы.

---

Пример: как выглядит запрос и ответ

Допустим, вы хотите проверить подключение к API. Для этого есть специальный метод /ping:

Запрос:

GET https://common-api.wildberries.ru/ping
Authorization: Bearer ваш_токен

Пример с cURL:

curl -H "Authorization: Bearer ваш_токен" \
     https://common-api.wildberries.ru/ping

Ответ (успех):

HTTP 200 OK

Если токен корректен и подключение работает — API вернёт код 200. Если что-то не так — вернётся ошибка с описанием проблемы.

---

Как читать документацию по методам

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

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

---

Типичные ошибки при первых запросах

• Неправильный домен. Каждая категория API размещена на своём домене. Запрос к методу товаров на домен заказов вернёт ошибку 404. Проверьте домен в документации метода.
• Отсутствует заголовок Authorization. Без токена API вернёт ошибку 401. Убедитесь, что заголовок передаётся в формате Authorization: Bearer ваш_токен.
• Неподходящий тип токена. Тестовый токен не даст доступа к реальным данным, а Персональный токен не будет работать в песочнице. Подробнее о типах — в статье «Способы подключения: токен и OAuth 2.0».
• JSON вместо query-параметров (и наоборот). Некоторые GET-методы принимают фильтры через URL (?dateFrom=2024-01-01), а POST-методы — через тело запроса в формате JSON. Формат указан в документации каждого метода.