WB SDK

Python SDK для работы с API Wildberries. Поддержка товаров, заказов, цен, складов, аналитики, рекламы, финансов и других разделов портала продавца.

Возможности

Встроенные механизмы:

• Синхронный и асинхронный клиенты — WBClient и AsyncWBClient
• Rate limiting по лимитам каждого API-домена WB
• Retry с exponential backoff при 429 (Too Many Requests)
• Типизированные исключения (401, 403, 422, 429 и др.)
• Типизированные ответы — методы возвращают Pydantic-объекты вместо словарей

Установка

pip install wbsdk

Или из исходников:

git clone https://github.com/RTHeLL/wbsdk.git
cd wbsdk
pip install -e .

Требования: Python 3.10+

Быстрый старт

Доступны синхронный (WBClient) и асинхронный (AsyncWBClient) клиенты. Все разделы API доступны через свойства клиента: content, prices, marketplace, general, orders_dbw, orders_dbs, click_collect, orders_fbw, warehouses, analytics, promotion, promotion_calendar, communications, reports, finances, documents, tariffs, user_management, wbd.

from wbsdk import WBClient

client = WBClient(token="YOUR_API_TOKEN")

# Проверка подключения и новости
client.general.ping()  # PingResponse
# client.general.get_news(from_date="2024-01-01")

# Категории и карточки (возвращаются Pydantic-объекты)
categories = client.content.get_parent_categories()  # ParentCategoriesResponse
cards = client.content.get_cards_list(settings={
    "cursor": {"limit": 100},
    "sort": {"ascending": True},
})

# Цены и скидки
client.prices.set_prices([{"nmID": 123, "price": 999, "discount": 30}])

# Заказы FBS
orders = client.marketplace.get_new_orders()  # OrdersNewResponse
supply = client.marketplace.create_supply(name="Поставка 1")  # SupplyCreateResponse
print(supply.id)  # доступ к полям через атрибуты (snake_case)

# Склады и остатки
warehouses = client.warehouses.get_warehouses()
client.warehouses.update_stocks(warehouse_id=1, stocks=[{"chrtId": 1, "sku": "123", "amount": 10}])

# Аналитика
funnel = client.analytics.get_sales_funnel_products(
    selected_period={"start": "2024-01-01", "end": "2024-01-31"},
)

Песочница

Для тестирования на случайных данных используйте песочницу WB. Нужен токен с опцией «Тестовый контур» в личном кабинете WB.

client = WBClient(token="YOUR_SANDBOX_TOKEN", sandbox=True)
# Вызовы идут на sandbox-хосты по разделам из таблицы на dev.wildberries.ru/sandbox:
# content, prices, dp_calendar → content-api-sandbox / discounts-prices-api-sandbox
# marketplace, orders_dbw, orders_dbs, click_collect, warehouses → marketplace-api-sandbox
# orders_fbw → supplies-api-sandbox; promotion, promotion_calendar → advert-api-sandbox
# communications → feedbacks-api-sandbox; reports → statistics-api-sandbox
categories = client.content.get_parent_categories()

В песочнице действуют свои лимиты (например, 1 запрос в секунду для многих разделов). Соответствие разделов и URL см. в таблице на странице песочницы.

Асинхронный клиент

Для неблокирующих запросов используйте AsyncWBClient.

import asyncio
from wbsdk import AsyncWBClient

async def main():
    async with AsyncWBClient(token="YOUR_API_TOKEN") as client:
        categories = await client.content.get_parent_categories()
        orders = await client.marketplace.get_new_orders()
        # Те же методы, что у WBClient — с await
    # Клиент корректно закрыт (async with или await client.close())

asyncio.run(main())

Используйте async with или явный await client.close() после работы, чтобы закрыть HTTP-соединения.

Типизированные ответы

Методы API возвращают Pydantic-объекты, а не сырые словари или списки. Все поля — в snake_case.

# Доступ к данным через атрибуты
categories = client.content.get_parent_categories()
for cat in categories.data:
    print(cat.name, cat.parent_id)

orders = client.marketplace.get_new_orders()
for order in orders.orders:
    print(order.id, order.nm_id, order.price)

supply = client.marketplace.create_supply(name="Тест")
print(supply.id)  # WB-GI-1234567

tags = client.content.get_tags()
for tag in tags.data:
    print(tag.id, tag.name, tag.color)

Схемы доступны в wbsdk.schemas для аннотаций и кастомной логики.

API по модулям

Content — контент и карточки

Prices — цены и скидки

General — общий раздел

Marketplace — заказы FBS

Warehouses — склады

Analytics — аналитика

User Management — управление пользователями

Tariffs — тарифы

Orders DBW — заказы доставки курьером WB

Доступ через client.orders_dbw. Новые и завершённые сборочные задания, статусы, даты доставки, отмена, метаданные (IMEI, УИН, GTIN, срок годности, ГТД и др.).

Orders DBS — заказы витрины

Доступ через client.orders_dbs. Новые и завершённые заказы DBS, группы, клиенты, даты доставки, статусы, отмена, подтверждение, доставка, получение, метаданные.

Click Collect — самовывоз

Доступ через client.click_collect. Новые заказы, подтверждение, готовность к выдаче, получение/отказ, проверка покупателя по коду.

Orders FBW — поставки на склад WB

Доступ через client.orders_fbw. Коэффициенты приёмки, опции приёмки, склады WB, транзитные тарифы, список поставок FBW.

Communications — вопросы, отзывы, чаты

Доступ через client.communications. Вопросы (количество, список, ответ), отзывы (количество, список, ответ, возврат), архив отзывов, пины, чаты, претензии.

Reports — отчёты поставок и продаж

Доступ через client.reports. Поставки (get_incomes), остатки (get_stocks), заказы (get_orders), продажи (get_sales), отчёт по реализации (get_report_detail_by_period).

Promotion — реклама и календарь акций

Доступ через client.promotion и client.promotion_calendar. Кампании (создание, запуск, пауза, ставки, бюджет, статистика), баланс рекламного счёта, нормзапросы, аукцион. Календарь: список акций, детали, номенклатуры, загрузка акций.

Finances и Documents

Доступ через client.finances и client.documents. Баланс продавца (get_balance). Категории документов, список документов, скачивание одного или нескольких документов.

WBD — цифровые товары

Доступ через client.wbd. Ключи API (список, погашенные), офферы (список, детали, ключи, цена, каталог), превью офферов.

Обработка ошибок

Исключения одинаковы для синхронного и асинхронного клиента.

from wbsdk import WBClient, AsyncWBClient
from wbsdk.exceptions import WBAuthError, WBRateLimitError, WBValidationError

# Синхронный клиент
try:
    with WBClient(token="...") as client:
        result = client.content.get_parent_categories()
except WBAuthError:
    print("Ошибка авторизации (401/403)")
except WBRateLimitError:
    print("Превышен лимит запросов (429)")
except WBValidationError:
    print("Ошибка валидации запроса (400/422)")

# Асинхронный клиент
async def fetch():
    try:
        async with AsyncWBClient(token="...") as client:
            return await client.content.get_parent_categories()
    except WBAuthError:
        print("Ошибка авторизации (401/403)")

Документация WB

• API Wildberries
• Песочница
• Общий раздел — ping, новости, информация о продавце
• Работа с товарами
• Заказы FBS
• Заказы DBW, Заказы DBS, Самовывоз, Поставки FBW
• Аналитика
• Реклама, Вопросы и отзывы, Отчёты, Финансы, WBD

Лицензия

MIT License. См. LICENSE.