WB: получить товар по URL

GET /wb/api/v1/item/by-url

Парсит один товар Wildberries по URL и возвращает JSON c данными карточки.

Параметры запроса

ПараметрТипОбязательныйОписание
url string да URL детальной карточки WB: https://www.wildberries.ru/catalog/<nm_id>/detail.aspx.

Заголовки

ЗаголовокОбязательныйОписание
X-API-Token да Ваш API‑токен портала. Передавайте только в заголовке.

Пример запроса

cURL
curl -X GET \
  "https://bhapi.ru/wb/api/v1/item/by-url?url=https://www.wildberries.ru/catalog/12345/detail.aspx" \
  -H "X-API-Token: ВАШ_API_TOKEN"

Успешный ответ 200 OK

JSON
{
  "status": "ok",
  "data": {
    "code": 200,
    "msg": "success",
    "data": {
      "item_id": 770596537,
      "product_url": "https://www.wildberries.ru/catalog/770596537/detail.aspx?targetUrl=MI",
      "title": "Смартфон M17 Pro Max 22+2048ГБ 2 nano-SIM+micro-SD",
      "currency": "RUB",
      "price_info": { },
      "main_imgs": [
        "https://basket-36.wbbasket.ru/vol7705/part770596/770596537/images/big/1.webp",
        "... другие URL ..."
      ],
      "additional_imgs": [ ],
      "complectation": "смартфоны; защитный чехол; кабель USB Type-C; зарядное устройство; ...",
      "category_name": "Смартфоны",
      "category_path": "Смартфоны и гаджеты",
      "product_props": {
        "Модель": "17 Pro Max",
        "Цвет": "черный",
        "Объем встроенной памяти (Гб)": "2 ТБ",
        "Суммарный объем оперативной памяти (Гб)": "22ГБ",
        "...": "..."
      },
      "shop_info": {
        "shop_name": "",
        "shop_id": "250077302",
        "seller_id": "250077302"
      },
      "review_info": { },
      "desc": "Модель: M17 Pro Max\nЗадняя крышка: ...",
      "source": "wildberries",
      "availability": "in_stock"
    }
  },
  "saved_path": null
}

WB: метаданные пресетов категорий

GET /wb/api/v1/search/presets

Возвращает стабильные имена полей для трёх готовых пресетов: обувь (footwear), одежда (clothing) и головные уборы (headwear). Список не означает, что пресет подготовлен для каждой категории WB.

Пример запроса

cURL
curl -X GET "https://bhapi.ru/wb/api/v1/search/presets" \
  -H "X-API-Token: ВАШ_API_TOKEN"

Структура ответа

ПолеТипОписание
data.presets[].namestringИмя для поля preset.
data.presets[].labelstringРусское название категории.
data.presets[].fields[].namestringИмя поля для preset_filters.
data.presets[].fields[].labelstringПонятное название поля.
data.presets[].fields[].multiplebooleanМожно ли передать несколько значений.
Квота: метаданные пресетов расходуют 0 запросов. Нужен действующий токен WB, но поиск товаров не запускается.

WB: динамические фильтры запроса

POST /wb/api/v1/search/filters

Возвращает актуальные группы характеристик и допустимые значения для конкретного поискового запроса. Фильтры зависят от запроса, региона и времени; полученный ID не следует считать постоянным глобальным словарём.

Тело запроса

ПолеТипОбязательныйОписание
querystringдаТовар или категория для исследования.
characteristic_filtersobjectнетУже выбранные ID для контекстного уточнения списка.

Пример cURL

cURL
curl -X POST "https://bhapi.ru/wb/api/v1/search/filters" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{"query":"лыжи классические"}'

Пример Python

Python — requests
import requests

response = requests.post(
    "https://bhapi.ru/wb/api/v1/search/filters",
    json={"query": "лыжи классические"},
    headers={"X-API-Token": "ВАШ_API_TOKEN"},
    timeout=210,
)
response.raise_for_status()
for group in response.json()["data"]["filters"]:
    print(group["key"], group["name"], group["values"])

Таймаут клиента должен быть больше фактического таймаута reverse proxy. В примере оставлен запас над рекомендуемыми 180 секундами.

Структура ответа

ПолеТипОписание
data.querystringИсходный поисковый запрос.
data.totalintegerЧисло товаров в текущем контексте.
data.filters[].keystringКлюч группы WB; поле итогового поиска выбирается по таблице ниже.
data.filters[].values[].idintegerSigned ID; отрицательный знак копируется без изменения.
data.filters[].values[].namestringОтображаемое значение.
data.filters[].values[].countinteger | nullДоступное число товаров, если оно известно.

Как перенести группу в поиск

Не переносите все группы механически в characteristic_filters. Используйте назначение по ключу или типу группы.

Группа discoveryПоле поискаПравило
Только ключи вида f<цифры>characteristic_filtersСохраните ключ и signed ID без изменения.
fbrandbrand_idsПередайте выбранные ID брендов массивом.
Цена / базовая цена (priceU)min_price, max_priceПередайте границы в рублях, а не ID значений группы.
faction / распродажаsale_type: trueПоддерживается только значение «Распродажа» с ID 1024637.
Другое значение faction или иная служебная группа не поддерживается публичным поиском. Не переписывайте такой ключ в characteristic_filters: используйте документированное поле, пресет или пропустите группу.
Успешный discovery расходует 1 успешный запрос. Последующий успешный поиск расходует ещё один, поэтому двухшаговый flow — 2 успешных запроса.

Сценарии дополнительных фильтров

Значения внутри одного массива объединяются как OR внутри одной группы, а разные ключи — как AND между группами. Пресеты и raw-ID можно сочетать с ценой, распродажей и brand_ids в одном POST-поиске.

Обувь: коричневые мужские лоферы, размер 45

cURL — footwear
curl -X POST "https://bhapi.ru/wb/api/v1/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "query":"лоферы мужские",
    "page":1,
    "preset":"footwear",
    "preset_filters":{
      "color":["коричневый"],
      "size":["45"],
      "gender":["мужской"]
    }
  }'

Для raw-ID сценария тот же коричневый цвет задаётся как "characteristic_filters":{"f1000000888":[-1000025867]}. Отрицательный знак сохраняется; raw-ID и пресет можно объединять.

Одежда: женская футболка, размер 46, оверсайз

cURL — clothing
curl -X POST "https://bhapi.ru/wb/api/v1/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "query":"футболка женская",
    "preset":"clothing",
    "preset_filters":{
      "size":["46"],
      "fit":["оверсайз"],
      "gender":["женский"]
    }
  }'

Головные уборы: женская шапка, размер 56

Python — headwear
import requests

payload = {
    "query": "шапка женская",
    "preset": "headwear",
    "preset_filters": {"size": ["56"], "gender": ["женский"]},
}
response = requests.post(
    "https://bhapi.ru/wb/api/v1/search",
    json=payload,
    headers={"X-API-Token": "ВАШ_API_TOKEN"},
    timeout=210,
)
response.raise_for_status()

Произвольная категория: классические лыжи

Сначала выполните discovery с {"query":"лыжи классические"}, затем скопируйте выбранные signed ID без изменения в канонический POST-поиск:

cURL — characteristic_filters
curl -X POST "https://bhapi.ru/wb/api/v1/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{
    "query":"лыжи классические",
    "characteristic_filters":{
      "f1000000896":[-1000041358],
      "f13649":[143021],
      "f121981":[121983]
    }
  }'
Один успешный вызов POST /wb/api/v1/search, в том числе с пресетом, расходует 1 успешный запрос.

WB: каталог продавца по ссылке

POST /wb/api/v1/seller/catalog

Возвращает каталог товаров конкретного продавца Wildberries по ссылке на магазин /seller/<id>.

Тело запроса

ПолеТипОбязательныйОписание
url string да URL продавца WB: https://www.wildberries.ru/seller/<supplier_id>.
page integer нет Номер страницы каталога продавца, по умолчанию 1.

Заголовки

ЗаголовокОбязательныйОписание
X-API-Token да Ваш API‑токен портала. Передавайте только в заголовке.

Пример запроса

cURL
curl -X POST "https://bhapi.ru/wb/api/v1/seller/catalog" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{"url":"https://www.wildberries.ru/seller/4190071","page":1}'

Успешный ответ 200 OK

JSON
{
  "status": "ok",
  "data": {
    "code": 200,
    "msg": "success",
    "data": {
      "supplier_id": 4190071,
      "page": 3,
      "products_count": 100,
      "per_page": 100,
      "max_pages": 5,
      "total": 490,
      "wb": {
        "products": [
          {
            "id": 277304775,
            "name": "Мотор насос омывателя 2101-2107 2121"
          }
        ]
      }
    }
  }
}

WB: теги и статистика отзывов по imt_id

POST /wb/api/v1/item/review_scope

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

Тело запроса

ПолеТипОбязательныйОписание
imt_id integer да WB imtId товара из feedbacks/tags API. Это не всегда то же самое, что nm_id карточки.
lang string нет Язык ответа, по умолчанию ru.

Заголовки

ЗаголовокОбязательныйОписание
X-API-Token да Ваш API‑токен портала. Передавайте только в заголовке.

Пример запроса

cURL
curl -X POST "https://bhapi.ru/wb/api/v1/item/review_scope" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{"imt_id":733309467,"lang":"ru"}'

Успешный ответ 200 OK

JSON
{
  "status": "ok",
  "data": {
    "code": 200,
    "msg": "success",
    "data": {
      "imt_id": 733309467,
      "lang": "ru",
      "summary": [
        { "tag_id": 8, "name": "Качество", "plus_count": 47, "minus_count": 0 }
      ],
      "items": [
        { "nm_id": 537724276, "summary": [] }
      ],
      "valuation": 4.8,
      "valuationSum": 55350,
      "valuationDistribution": { "1": 193, "2": 71, "3": 137, "4": 461, "5": 10552 },
      "nmValuationDistribution": [],
      "feedbackCount": 1036,
      "photo_links": [
        "https://feedback-01.wbbasket.ru/example/ms.webp"
      ],
      "wb": {
        "summary": [ ],
        "items": [ ]
      }
    }
  },
  "saved_path": null
}

Ключевые поля ответа

ПолеОписание
summaryОбщие теги отзывов по товару: название тега, tag_id, количество плюсов и минусов.
itemsДетализация тегов по конкретным nm_id, если WB вернул такую разбивку.
valuation, valuationSumСредняя оценка и суммарное количество оценок.
valuationDistributionРаспределение оценок от 1 до 5.
nmValuationDistributionРаспределение оценок по отдельным nm_id.
photo_linksГотовые URL пользовательских фото из отзывов.
wbСырой ответ WB по тегам отзывов.

Обёртка ответа парсера WB

Ответы WB API в BHAPI возвращаются в единой обёртке: статус, полезная нагрузка и путь сохранения, если он был запрошен.

ПолеТипОписание
status string Статус верхнего уровня портала: обычно "ok" или "error".
data object Полезная нагрузка. Для одиночного товара содержит поля code, msg, data.
saved_path string | null Поле совместимости; публичный BHAPI не сохраняет ответы на сервере и возвращает null.

Во внутреннем объекте data для одиночного товара структура такая:

ПолеТипОписание
codeintegerКод результата парсера (200 — успех, другие — ошибки на стороне WB/парсера).
msgstringТекстовое описание результата ("success" или сообщение об ошибке).
dataobjectКарточка товара WB (см. раздел «Карточка товара» ниже).

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

Ниже приведена укрупнённая структура объекта data для одиночного товара.

ПолеТипОписание
item_idintegerИдентификатор товара WB (nm_id).
product_urlstringURL детальной карточки товара.
titlestringНазвание товара.
currencystringКод валюты, как правило RUB.
price_infoobjectЦеновая информация (может быть пустым объектом, структура зависит от версии WB API).
main_imgsstring[]Массив URL основных изображений товара.
additional_imgsstring[]Дополнительные изображения (если есть).
complectationstringКомплектация из карточки товара.
category_namestringНазвание категории.
category_pathstringПуть до категории (цепочка разделов).
product_propsobjectСловарь характеристик «название → значение» (объём памяти, цвет, ОС и т.п.).
shop_infoobjectИнформация о продавце (см. ниже).
review_infoobjectИнформация по отзывам (может быть пустым объектом).
descstringТекстовое описание товара.
sourcestringИсточник данных, обычно "wildberries".
availabilitystringСтатус наличия: "in_stock", "not_available" и т.п.

ShopInfo — информация о продавце

ПолеТипОписание
shop_namestringОтображаемое название магазина (может быть пустой строкой).
shop_idstringИдентификатор магазина WB.
seller_idstringИдентификатор продавца (может совпадать с shop_id).

Структура результата поиска

Объект data в ответе на /wb/api/v1/search детализированно описан ниже.

ПолеТипОписание
querystringИсходный поисковый запрос.
pageintegerНомер текущей страницы.
totalintegerОбщее число найденных товаров по всем страницам.
linksstring[]Массив URL карточек товаров на текущей странице.
countintegerКоличество элементов в массиве links.
productsobject[]Массив кратких описаний товаров.

Элемент products[i]

ПолеТипОписание
idintegernm_id товара WB.
linkstringURL детальной карточки товара.
pricefloat | nullТекущая цена в рублях (может быть null).
ratingfloat | nullРейтинг по отзывам.
feedbacksinteger | nullКоличество отзывов/оценок.
descriptionstring | nullКраткое текстовое описание товара.

Коды ошибок

Типичные коды ошибок при работе с парсером WB через портал BHAPI:

Код APIHTTP-статусОписаниеЧто делать
401 Токен не передан или невалиден. Проверьте заголовок X-API-Token, при необходимости создайте новый токен.
403 Токен деактивирован, Free WB завершён или платная подписка WB не действует. Проверьте тарифы и статус токена в личном кабинете.
404 Товар не найден (удалён, скрыт или неверный URL). Убедитесь, что URL ведёт на существующую карточку WB и содержит корректный nm_id.
422 Ошибка валидации параметров запроса. Проверьте обязательные параметры (url или query), числовые фильтры и формат значений.
preset_field_unknown 422 Поле отсутствует в выбранном пресете. Получите текущий список полей через GET /wb/api/v1/search/presets.
preset_filter_value_unavailable 422 Запрошенное friendly-значение сейчас недоступно. Выберите другое значение или используйте динамический discovery.
search_filters_timeout 502 Получение актуальных фильтров не уложилось в срок. Повторите запрос позднее; операция не считается успешным расходом квоты.
429 Превышен лимит запросов по тарифу или ограничение скорости. Уменьшите частоту запросов, используйте кэширование и проверьте лимиты в кабинете.
500 Внутренняя ошибка сервиса. Повторите запрос позже, при постоянной проблеме свяжитесь с поддержкой.

Лимиты и квоты

Парсер WB использует token limits и отдельную тарифную квоту аккаунта для WB.

Тип лимитаОписаниеСброс / поведение
Дневной лимит Максимальное количество запросов к парсеру WB в сутки. Сбрасывается ежедневно по UTC. После исчерпания возвращается ошибка 429.
Общий лимит Суммарное количество запросов за всё время жизни токена. Не сбрасывается. При достижении лимита необходимо создать новый токен или изменить тариф.
Платный тариф WB Успешные запросы всех WB-ключей аккаунта в текущем месяце. Сбрасывается в начале календарного месяца, пока действует оплаченный период WB.
Free WB 50 успешных запросов всех WB-ключей за 30 суток с первого ключа WB. Не сбрасывается и не перезапускается новым ключом; затем нужна платная подписка WB.
Rate limit Защита от слишком частых запросов подряд (ограничение скорости). Рекомендуется делать паузу 1–2 секунды между запросами, особенно при массовом парсинге.
Фильтры и пресеты Метаданные пресетов — 0 запросов; успешные discovery и search — по 1 запросу. Двухшаговый discovery + search расходует 2 успешных запроса.
Совет. Используйте поиск и массовый сбор ссылок батчами, а затем обрабатывайте их с задержками, чтобы не упираться в ограничения WB и квоты портала.

Примеры: Python

Получить один товар по URL

Python — requests
import requests

API_URL = "https://bhapi.ru/wb/api/v1/item/by-url"
TOKEN = "ВАШ_API_TOKEN"

params = {
    "url": "https://www.wildberries.ru/catalog/770596537/detail.aspx",
}

response = requests.get(API_URL, params=params, headers={"X-API-Token": TOKEN}, timeout=30)
payload = response.json()

if payload["status"] == "ok" and payload["data"]["code"] == 200:
    item = payload["data"]["data"]
    print("ID товара:", item["item_id"])
    print("Название:", item["title"])
    print("Категория:", item["category_name"])
    print("Картинок:", len(item["main_imgs"]))
else:
    print("Ошибка:", payload)

Поиск по каталогу и вывод топа

Python — поиск
import requests

SEARCH_URL = "https://bhapi.ru/wb/api/v1/search"
TOKEN = "ВАШ_API_TOKEN"

payload = {
    "query": "аэрогриль объем 8 литров",
    "page": 1,
    "max_links": 10,
    "sort": "rate",
}

response = requests.post(
    SEARCH_URL,
    json=payload,
    headers={"X-API-Token": TOKEN},
    timeout=210,
)
payload = response.json()

data = payload["data"]
print(f"Всего найдено товаров: {data['total']}")
print(f"Показано на странице: {data['count']}")

for product in data["products"]:
    print(
        f"{product['id']}: {product['price']} ₽, "
        f"рейтинг {product['rating']}, отзывов {product['feedbacks']}"
    )

Примеры: cURL

Получить товар по URL

cURL
curl -X GET \
  "https://bhapi.ru/wb/api/v1/item/by-url?url=https://www.wildberries.ru/catalog/770596537/detail.aspx" \
  -H "X-API-Token: ВАШ_API_TOKEN"

Поиск по каталогу

cURL
# Базовый поиск
curl -X POST "https://bhapi.ru/wb/api/v1/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{"query":"кроссовки"}'

# Страница 2, ограничение по количеству ссылок
curl -X POST "https://bhapi.ru/wb/api/v1/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: ВАШ_API_TOKEN" \
  -d '{"query":"зимние ботинки","page":2,"max_links":50}'

Примеры: JavaScript

Fetch API (браузер / Node.js 18+)

JavaScript
const TOKEN = "ВАШ_API_TOKEN";
const BASE_URL = "https://bhapi.ru";

async function getWbItem(productUrl) {
  const params = new URLSearchParams({ url: productUrl });

  const response = await fetch(`${BASE_URL}/wb/api/v1/item/by-url?${params}`, {
    method: "GET",
    headers: { "X-API-Token": TOKEN },
  });

  const payload = await response.json();

  if (payload.status === "ok" && payload.data.code === 200) {
    return payload.data.data;
  }

  console.error("Ошибка WB:", payload);
  return null;
}

getWbItem("https://www.wildberries.ru/catalog/770596537/detail.aspx")
  .then((item) => {
    if (!item) return;
    console.log("Название:", item.title);
    console.log("Категория:", item.category_name);
    console.log("Первая картинка:", item.main_imgs[0]);
  });

Примеры: PHP

Получить товар по URL (PHP + cURL)

PHP
<?php

$apiUrl = "https://bhapi.ru/wb/api/v1/item/by-url";
$token  = "ВАШ_API_TOKEN";

$productUrl = "https://www.wildberries.ru/catalog/770596537/detail.aspx";

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => $apiUrl . "?" . http_build_query(["url" => $productUrl]),
    CURLOPT_HTTPHEADER     => ["X-API-Token: " . $token],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);

$response = curl_exec($ch);
curl_close($ch);

$payload = json_decode($response, true);

if ($payload["status"] === "ok" && $payload["data"]["code"] === 200) {
    $item = $payload["data"]["data"];
    echo "Товар: " . $item["title"] . PHP_EOL;
    echo "Категория: " . $item["category_name"] . PHP_EOL;
} else {
    var_dump($payload);
}

Пакетная обработка (пример скрипта)

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

Python — поиск + детали
import time
import requests

BASE_URL = "https://bhapi.ru"
TOKEN = "ВАШ_API_TOKEN"

def search(query: str, page: int = 1, limit: int = 10):
    resp = requests.post(
        f"{BASE_URL}/wb/api/v1/search",
        json={"query": query, "page": page, "max_links": limit},
        headers={"X-API-Token": TOKEN},
        timeout=210,
    )
    return resp.json()["data"]

def get_item(url: str):
    resp = requests.get(
        f"{BASE_URL}/wb/api/v1/item/by-url",
        params={"url": url},
        headers={"X-API-Token": TOKEN},
        timeout=30,
    )
    payload = resp.json()
    if payload["status"] == "ok" and payload["data"]["code"] == 200:
        return payload["data"]["data"]
    return None

data = search("аэрогриль объем 8 литров", page=1, limit=5)

items = []
for link in data["links"]:
    print("Парсим:", link)
    item = get_item(link)
    if item:
        items.append(item)
        print("  ✓", item["title"][:60])
    else:
        print("  ✗ не удалось получить данные")
    time.sleep(1.5)  # пауза, чтобы не превышать rate limit

print(f"Всего подробно получено товаров: {len(items)}")

Нужен готовый процесс, а не только API?

Соберём вокруг данных WB мониторинг, Telegram-бота, отчёт или рабочий кабинет. Начать можно с короткого описания ручной задачи — готовое ТЗ не требуется.

Обсудить автоматизацию WB