Wildberries Python SDK

Professional, contract-oriented Python client for Wildberries API.

Features

• Async/Sync support - Works with both async and synchronous code using httpx
• Type-safe - Full Pydantic V2 models with validation
• Rate limiting - Intelligent token-based rate limiting with category isolation
• Error handling - Typed exception hierarchy for all API errors
• Registry-based - YAML configuration for easy endpoint extension
• Sandbox/Production - Support for both WB environments
• Pagination - Built-in async/sync page iterators

Installation

pip install wildberries-python-sdk

Or with development dependencies:

pip install wildberries-python-sdk[dev]

Quick Start

Async Client

import asyncio
from wildberries_python_sdk import BaseClient, Registry, RateLimiter, GeneralService

async def main():
    registry = Registry("config/endpoints")
    ratelimiter = RateLimiter()

    client = BaseClient(
        token="your-api-token",
        registry=registry,
        ratelimiter=ratelimiter
    )

    service = GeneralService(client)
    info = await service.get_seller_info()
    print(f"Seller: {info.name}")

    await client.close()

asyncio.run(main())

Sync Client

from wildberries_python_sdk import SyncClient, Registry, RateLimiter, GeneralService

with SyncClient("token", registry, ratelimiter) as client:
    service = GeneralService(client)
    info = service.get_seller_info()
    print(info.name)

Services

Products API Example

from wildberries_python_sdk import ProductsService

service = ProductsService(client)

# Get categories
categories = await service.get_parent_categories()
for cat in categories.data:
    print(f"{cat.id}: {cat.name}")

# Get product cards
cards = await service.get_cards_list(
    settings={"cursor": {"limit": 100}}
)

Error Handling

from wildberries_python_sdk import WBAPIError, TooManyRequestsError

try:
    result = await service.get_data()
except TooManyRequestsError as e:
    print(f"Rate limited! {e.detail}")
except WBAPIError as e:
    print(f"API Error {e.status}: {e.detail}")

Configuration

from wildberries_python_sdk import Config, DomainType, set_default_locale

# Set global configuration
set_default_locale("en")

# Or use Config class
config = Config(locale="en", domain=DomainType.SANDBOX)

Development

# Clone and install
git clone https://github.com/wildberries/wildberries-python-sdk
cd wildberries-python-sdk
pip install -e ".[dev]"

# Run tests
pytest tests/

# Type checking
mypy src/

# Linting
ruff check src/

License

MIT License - see LICENSE file for details.