Wildberries SDK

Русский

English

Русский

English

Оформление

Глоссарий ​

Быстрая навигация: Термины Wildberries | Компоненты SDK | Концепции API | Технические термины | Акронимы

Термины маркетплейса Wildberries ​

Баланс счета (Account Balance) ​

Текущие средства, доступные на счете продавца Wildberries. Включает выручку от продаж минус комиссии, сборы и другие расходы.

Связанные: Модуль Finances, Пример финансовых операций

Штрих-код (Barcode) ​

Идентификатор товара, используемый для управления запасами и выполнения заказов. Wildberries поддерживает несколько типов штрих-кодов: EAN-13, UPC, ITF-14, GTIN.

Типы:

  • EAN-13: Европейский артикульный номер (13 цифр)
  • UPC: Универсальный код товара
  • ITF-14: Чередующийся 2 из 5 (14 цифр)
  • GTIN: Глобальный номер товарной единицы

Связанные: Модуль Products

Название бренда (Brand Name) ​

Официальное название бренда товара. Обязательное поле для создания карточки товара на маркетплейсе Wildberries.

Пример: "Nike", "Adidas", "Samsung"

Связанные: Руководство по созданию товаров

Категория (Category) ​

Иерархическая классификация товаров на маркетплейсе Wildberries. Категории определяют обязательные и опциональные характеристики для товаров.

Структура:

  • Родительские категории: Верхний уровень (например, "Электроника", "Одежда")
  • Подкатегории: Вложенные уровни (например, "Электроника" → "Смартфоны")
  • Конечные категории: Финальный уровень, где создаются товары

Связанные: API категорий

Характеристика (Characteristic) ​

Атрибут товара, определяющий специфические свойства (размер, цвет, материал и т.д.). Категории определяют обязательные и опциональные характеристики.

Примеры:

  • Размер: "S", "M", "L", "XL"
  • Цвет: "Красный", "Синий", "Черный"
  • Материал: "Хлопок", "Полиэстер", "Шерсть"

Связанные: Характеристики товаров

Комиссия (Commission) ​

Сбор, взимаемый Wildberries за продажу товаров на маркетплейсе. Ставки комиссии варьируются по категориям и рассчитываются как процент от цены продажи.

Расчет: Комиссия = Цена продажи × Ставка комиссии

Связанные: Модуль Tariffs, Ставки комиссии

Покупатель (Customer) ​

Конечный пользователь, покупающий товары на маркетплейсе Wildberries. Информация о покупателе включает адрес доставки, контактные данные и предпочтения по заказам.

Связанные: Управление заказами

FBS (Выполнение продавцом) ​

Модель выполнения заказов, при которой продавец занимается хранением, упаковкой и отправкой. Продавец отвечает за доставку заказов покупателям или в пункты выдачи.

Обязанности:

  • Хранение товаров на складе продавца
  • Упаковка и маркировка заказов
  • Отправка покупателю или в пункт выдачи
  • Обработка возвратов и обслуживание клиентов

Связанные: Модуль OrdersFBS, Пример выполнения заказов FBS

FBW (Выполнение Wildberries) ​

Модель выполнения заказов, при которой Wildberries занимается хранением, упаковкой и отправкой. Продавец отправляет товары на склады WB, а WB управляет выполнением заказов.

Обязанности:

  • Продавец: Отправка товаров на склад WB, управление уровнями запасов
  • Wildberries: Хранение, упаковка, отправка, возвраты, обслуживание клиентов

Преимущества: Быстрая доставка, соответствие требованиям Prime, снижение логистической нагрузки на продавца

Связанные: Модуль OrdersFBW

NM ID (Номенклатурный идентификатор) ​

Уникальный идентификатор товара в системе Wildberries. Автоматически присваивается при создании новой карточки товара. Используется для отслеживания товаров во всех API.

Формат: Числовая строка (например, "12345678")

Связанные: Управление товарами

Заказ (Order) ​

Покупка клиента, требующая выполнения. Заказы содержат товарные позиции, количества, адрес доставки и платежную информацию.

Жизненный цикл заказа: new → confirmed → assembled → shipped → delivered

Типы:

  • Заказы FBS: Выполняются продавцом
  • Заказы FBW: Выполняются Wildberries

Связанные: Модуль Order, Рабочий процесс заказов

Выплата (Payout) ​

Перевод средств со счета Wildberries на банковский счет продавца. Выплаты производятся через запланированные интервалы (еженедельно, раз в две недели или ежемесячно).

Компоненты:

  • Выручка от продаж
  • Минус комиссии и сборы
  • Минус возвраты и возмещения
  • Перевод на банковский счет

Связанные: Модуль Finances, Интерфейс Payout

Пункт выдачи (Pickup Point) ​

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

Типы:

  • Пункты выдачи Wildberries
  • Партнерские пункты выдачи (например, почтовые отделения)

Связанные: Модуль InStorePickup

Ценообразование (Pricing) ​

Конфигурация цены продажи товара. Включает базовую цену, скидки и промо-цены.

Компоненты:

  • Базовая цена: Исходная цена товара
  • Скидка: Процентное или фиксированное снижение суммы
  • Финальная цена: Цена, показываемая покупателям

Связанные: Модуль Products - Ценообразование, Интерфейс PricingInfo

Карточка товара (Product Card) ​

Полное описание товара на маркетплейсе Wildberries. Содержит всю информацию о товаре: название, описание, изображения, цены, характеристики и запасы.

Обязательные поля:

  • Название бренда
  • Категория
  • Название и описание
  • Минимум одна характеристика
  • Информация о ценах

Связанные: Интерфейс ProductCard, Пример создания товара

Промо-акция/Кампания (Promotion/Campaign) ​

Маркетинговая активность, предлагающая скидки или специальные цены. Кампании могут быть ограничены по времени и применяться к конкретным товарам или категориям.

Типы:

  • Процентные скидки
  • Фиксированные скидки
  • Наборные предложения
  • Молниеносные распродажи

Связанные: Модуль Promotion

Возврат (Return) ​

Возврат товара, инициированный покупателем. Возвраты влияют на баланс счета и уровни запасов.

Процесс: Покупатель запрашивает возврат → Продавец одобряет/отклоняет → Товар возвращается → Возврат средств обрабатывается

Связанные: Обработка возвратов

Отзыв (Review) ​

Отзыв покупателя о товаре, включая рейтинг (1-5 звезд), текстовый комментарий и опциональные фото/видео.

Действия продавца:

  • Чтение отзывов
  • Ответ на отзывы
  • Отслеживание метрик отзывов

Связанные: Модуль Communications, Интерфейс Review

Воронка продаж (Sales Funnel) ​

Аналитика, показывающая конверсию от просмотров товаров к покупкам. Ключевые метрики: просмотры, добавления в корзину, покупки, коэффициент конверсии.

Формула: Коэффициент конверсии = (Покупки / Просмотры) × 100

Связанные: Модуль Analytics, Интерфейс SalesFunnel

Продавец (Seller) ​

Торговец, продающий товары на маркетплейсе Wildberries. Продавцы управляют каталогом товаров, запасами, заказами и коммуникациями с клиентами.

Обязанности:

  • Размещение товаров и управление каталогом
  • Управление запасами
  • Выполнение заказов (FBS) или отправка на склад (FBW)
  • Обслуживание клиентов и коммуникации

Запасы/Инвентарь (Stock/Inventory) ​

Количество товаров, доступных для продажи. Уровни запасов отслеживаются по складам для FBW или по местоположению продавца для FBS.

Состояния запасов:

  • Доступно: Готово к продаже
  • Зарезервировано: Выделено для ожидающих заказов
  • В пути: Перемещение между складами

Связанные: Управление запасами, Интерфейс StockInfo

Поставка (Supply) ​

Партия товаров, отправленная на склад Wildberries (только для FBW). Поставки должны быть созданы и промаркированы перед отправкой запасов в WB.

Процесс: Создание поставки → Добавление товаров → Генерация этикеток → Отправка на склад → WB принимает и хранит

Связанные: Модуль OrdersFBW - Поставки

Тариф (Tariff) ​

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

Типы:

  • Тарифы комиссий: Процент от цены продажи
  • Тарифы выполнения: За единицу товара (комплектация и упаковка)
  • Тарифы хранения: Ежемесячная плата за хранение (FBW)
  • Тарифы возврата: Обработка возвращенных товаров

Связанные: Модуль Tariffs

Транзакция (Transaction) ​

Финансовая запись о движении денег на счете продавца. Включает продажи, возвраты, комиссии, сборы и выплаты.

Типы:

  • Кредит: Выручка от продаж
  • Дебет: Комиссии, сборы, возвраты
  • Выплата: Перевод на банковский счет

Связанные: Модуль Finances, Интерфейс Transaction

Склад (Warehouse) ​

Складское помещение для товаров. Wildberries управляет несколькими складами в регионах для выполнения FBW.

Связанные: Интерфейс Warehouse

Компоненты SDK и архитектура ​

AuthManager ​

Компонент SDK, отвечающий за валидацию API ключа и внедрение заголовка аутентификации. Проверяет формат API ключа при инициализации и добавляет заголовок Authorization ко всем запросам.

Расположение: src/client/auth-manager.ts

Связанные: Руководство по аутентификации

BaseClient ​

Основной HTTP-клиент, обеспечивающий централизованную обработку запросов. Все модули API делегируют BaseClient HTTP-операции (GET, POST, PUT, PATCH, DELETE).

Возможности:

  • Внедрение заголовка аутентификации
  • Управление таймаутами
  • Трансформация ошибок
  • Интеграция лимита запросов
  • Интеграция логики повторных попыток

Расположение: src/client/base-client.ts

Связанные: Документ архитектуры

Классы ошибок (Error Classes) ​

Типизированная иерархия ошибок для обработки сбоев API. Все ошибки наследуются от базового класса WBAPIError.

Иерархия:

Error (native)
  └── WBAPIError
        ├── AuthenticationError (401, 403)
        ├── RateLimitError (429)
        ├── ValidationError (400, 422)
        └── NetworkError (timeouts, 5xx)

Расположение: src/errors/

Связанные: Руководство по обработке ошибок

Модули (Modules) ​

Группы конечных точек API, организованные по функциональности. SDK включает 11 модулей, соответствующих доменам API Wildberries.

Доступные модули:

  • general - Утилиты (ping, новости, информация о продавце)
  • products - Управление каталогом товаров
  • ordersFBS - Заказы с выполнением продавцом
  • ordersFBW - Заказы с выполнением Wildberries
  • finances - Баланс счета и транзакции
  • analytics - Метрики производительности продаж
  • reports - Асинхронная генерация отчетов
  • communications - Взаимодействия с клиентами (чат, Q&A, отзывы)
  • promotion - Маркетинговые кампании
  • tariffs - Информация о комиссиях и сборах
  • inStorePickup - Управление пунктами выдачи

Расположение: src/modules/[module]/

Связанные: Модули API

RateLimiter ​

Компонент, обеспечивающий соблюдение лимитов запросов для каждой конечной точки, используя алгоритм корзины токенов. Предотвращает нарушения лимитов запросов API, ставя запросы в очередь.

Алгоритм: Корзина токенов - токены пополняются с фиксированной скоростью, запросы потребляют токены

Расположение: src/client/rate-limiter.ts

Связанные: Руководство по лимиту запросов

RetryHandler ​

Компонент, реализующий логику повторных попыток с экспоненциальной задержкой для временных сбоев. Автоматически повторяет неудачные запросы с увеличивающимися задержками.

Условия повтора:

  • Таймауты сети
  • 5xx серверные ошибки
  • 429 ошибки лимита запросов

Без повтора:

  • 4xx клиентские ошибки (кроме 429)
  • Ошибки аутентификации
  • Ошибки валидации

Расположение: src/client/retry-handler.ts

Связанные: Руководство по логике повторов

SDKConfig ​

Объект конфигурации, передаваемый в конструктор SDK. Определяет API ключ, таймауты, поведение повторов, лимиты запросов и логирование.

Обязательно: apiKey

Опционально: timeout, retryConfig, rateLimitConfig, logLevel, baseUrls

Тип: Интерфейс SDKConfig

Связанные: Руководство по конфигурации

Определения типов (Type Definitions) ​

TypeScript интерфейсы, автоматически сгенерированные из OpenAPI схем. Обеспечивает полную типобезопасность для данных запросов/ответов.

Расположение: src/types/[module].types.ts

Связанные: Руководство по типобезопасности

WildberriesSDK ​

Основной класс SDK, служащий точкой входа и агрегатором модулей. Предоставляет все 11 модулей API в виде свойств.

Использование:

typescript
const sdk = new WildberriesSDK({ apiKey });
sdk.products.getProductList();
sdk.ordersFBS.getNewOrders();

Расположение: src/index.ts

Связанные: Инициализация SDK

Концепции и паттерны API ​

Async/Await ​

Современный паттерн JavaScript для обработки асинхронных операций. Все методы SDK возвращают Promises и работают с async/await.

Пример:

typescript
const balance = await sdk.finances.getBalance();

Связанные: Руководство по асинхронному программированию

Аутентификация (Authentication) ​

Процесс проверки API ключа и авторизации запросов. SDK использует аутентификацию Bearer token через HTTP заголовок.

Заголовок: Authorization: Bearer {api_key}

Связанные: Руководство по аутентификации

Базовый URL (Base URL) ​

Корневой URL для конечных точек API. Разные API Wildberries используют разные базовые URL (например, content-api.wildberries.ru, marketplace-api.wildberries.ru).

Конфигурация: Может быть переопределен для каждого модуля в SDKConfig.baseUrls

Связанные: Домены API

Экспоненциальная задержка (Exponential Backoff) ​

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

Формула: задержка = базовая_задержка × 2^(номер_попытки)

Пример: 1с → 2с → 4с → 8с

Связанные: Логика повторов

HTTP методы (HTTP Methods) ​

Типы запросов для операций API:

  • GET: Получение данных (только чтение)
  • POST: Создание новых ресурсов
  • PUT: Замена существующих ресурсов
  • PATCH: Обновление конкретных полей
  • DELETE: Удаление ресурсов

Связанные: RESTful API дизайн

JSON (JavaScript Object Notation) ​

Формат данных для API запросов и ответов. Человеко-читаемый текстовый формат, представляющий объекты и массивы.

Пример:

json
{
  "brandName": "Nike",
  "categoryId": "12345"
}

Пагинация (Pagination) ​

Паттерн для получения больших наборов данных по частям. API Wildberries используют пагинацию на основе смещения или курсора.

На основе смещения:

typescript
{ limit: 100, offset: 0 }

На основе курсора:

typescript
{ cursor: 'eyJpZCI6MTIzfQ==' }

Связанные: Руководство по пагинации

Лимит запросов (Rate Limiting) ​

Ограничение на количество API запросов в течение временного периода. Предотвращает злоупотребления и обеспечивает справедливое распределение ресурсов.

Формат: "X запросов за Y период времени" (например, "3 запроса в минуту")

Связанные: Руководство по лимиту запросов

Запрос/Ответ (Request/Response) ​

Паттерн коммуникации между клиентом и сервером:

  • Запрос: Клиент отправляет HTTP запрос с методом, URL, заголовками, телом
  • Ответ: Сервер возвращает HTTP ответ с кодом состояния, заголовками, телом

Связанные: Основы HTTP

REST (Representational State Transfer) ​

Архитектурный стиль для API, использующий HTTP методы и URL. API Wildberries следуют принципам REST.

Принципы:

  • Коммуникация без сохранения состояния
  • URL на основе ресурсов
  • Стандартные HTTP методы
  • Формат данных JSON

Логика повторов (Retry Logic) ​

Автоматическое повторное выполнение неудачных запросов. SDK повторяет временные сбои (таймауты, 5xx ошибки, 429 лимиты запросов).

По умолчанию: Максимум 3 повтора с экспоненциальной задержкой

Связанные: RetryHandler

Таймаут (Timeout) ​

Максимальное время, отведенное для завершения API запроса. Предотвращает бесконечное ожидание не отвечающих серверов.

По умолчанию: 30 секунд

Конфигурация: SDKConfig.timeout

Связанные: Конфигурация таймаутов

Алгоритм корзины токенов (Token Bucket Algorithm) ​

Алгоритм лимита запросов, использующий токены, представляющие емкость запросов. Токены пополняются с фиксированной скоростью, запросы потребляют токены.

Поведение:

  • Корзина содержит максимальное количество токенов (емкость всплеска)
  • Токены пополняются с постоянной скоростью
  • Запрос потребляет 1 токен
  • Если нет доступных токенов, запрос ожидает

Связанные: RateLimiter

Типобезопасность (Type Safety) ​

Функция TypeScript, обеспечивающая проверку типов во время компиляции. SDK обеспечивает полную типобезопасность через автоматически сгенерированные интерфейсы.

Преимущества:

  • Обнаружение ошибок во время компиляции
  • Автозавершение IDE и IntelliSense
  • Самодокументируемый код
  • Безопасность рефакторинга

Связанные: Определения типов

Технические термины ​

API (Application Programming Interface) ​

Набор конечных точек и протоколов для программного взаимодействия с маркетплейсом Wildberries.

API ключ (API Key) ​

Секретный токен для аутентификации запросов SDK. Получается с портала продавца Wildberries.

Безопасность: Никогда не коммитьте API ключи в систему контроля версий. Используйте переменные окружения.

Связанные: Аутентификация

Axios ​

Promise-based HTTP клиент для Node.js и браузеров. Используется внутри SDK для HTTP запросов.

Веб-сайт: axios-http.com

CommonJS (CJS) ​

Система модулей JavaScript, использующая require() и module.exports. SDK предоставляет CommonJS сборку для обратной совместимости.

Связанные: Системы модулей

Внедрение зависимостей (Dependency Injection) ​

Паттерн проектирования, при котором зависимости предоставляются компонентам, а не создаются внутри. SDK использует внедрение зависимостей для BaseClient.

ESM (ECMAScript Modules) ​

Современная система модулей JavaScript, использующая import и export. Основной формат сборки SDK.

Связанные: Системы модулей

Обобщенные типы (Generic Types) ​

Функция TypeScript, позволяющая использовать параметры типов для повторно используемого кода. SDK широко использует обобщения для типобезопасных API.

Пример:

typescript
async get<T>(url: string): Promise<T>

HTTP (Hypertext Transfer Protocol) ​

Протокол для передачи данных через интернет. Все запросы SDK используют HTTPS (безопасный HTTP).

IDE (Integrated Development Environment) ​

Программное обеспечение для написания и отладки кода. Примеры: VS Code, WebStorm, IntelliJ IDEA.

Интерфейс (Interface) ​

Конструкция TypeScript, определяющая форму объекта. SDK использует интерфейсы для типов запросов/ответов.

Пример:

typescript
interface ProductCard {
  id: string;
  brandName: string;
  categoryId: string;
}

JSON Schema ​

Формат для описания структуры данных JSON. OpenAPI спецификации Wildberries используют JSON Schema для валидации запросов/ответов.

Система модулей (Module System) ​

Функция JavaScript для организации кода в повторно используемые модули. SDK поддерживает как ESM, так и CommonJS.

Связанные: ESM, CommonJS

Node.js ​

JavaScript runtime для серверной разработки. SDK требует Node.js 18.x, 20.x или 22.x LTS.

Веб-сайт: nodejs.org

npm (Node Package Manager) ​

Менеджер пакетов для JavaScript. SDK распространяется через реестр npm.

Команда: npm install @daytona/wildberries-typescript-sdk

OpenAPI (Swagger) ​

Формат спецификации для описания RESTful API. Wildberries предоставляет 11 OpenAPI YAML файлов.

Связанные: Спецификация API

Promise ​

JavaScript объект, представляющий возможное завершение или сбой асинхронной операции. Все методы SDK возвращают Promises.

Связанные: Async/Await

SDK (Software Development Kit) ​

Библиотека, предоставляющая инструменты и интерфейсы для взаимодействия с платформой. Этот SDK упрощает интеграцию с API Wildberries.

Tree Shaking ​

Оптимизация сборки, удаляющая неиспользуемый код. Модули SDK поддерживают tree shaking для минимального размера бандла.

TypeScript ​

Типизированный надмножество JavaScript, добавляющее статическую проверку типов. SDK написан на TypeScript со включенным строгим режимом.

Веб-сайт: typescriptlang.org

UUID (Universally Unique Identifier) ​

128-битный идентификатор, гарантированно уникальный. SDK использует UUIDs для correlation IDs в логировании.

Акронимы и сокращения ​

АкронимПолный терминОписание
ACAcceptance CriteriaКритерии завершения истории
APIApplication Programming InterfaceПрограммный интерфейс для сервисов
CI/CDContinuous Integration/Continuous DeploymentАвтоматизированный конвейер тестирования и развертывания
CJSCommonJSСистема модулей JavaScript
CSVComma-Separated ValuesФормат файла для экспорта данных
DoDDefinition of DoneЧек-лист для завершения задачи
ESMECMAScript ModulesСовременная система модулей JavaScript
FBSFulfillment by SellerВыполнение заказов продавцом
FBWFulfillment by WildberriesВыполнение заказов Wildberries
GTINGlobal Trade Item NumberМеждународный идентификатор товара
HTTPHypertext Transfer ProtocolПротокол веб-коммуникации
HTTPSHTTP SecureЗашифрованный HTTP
IDEIntegrated Development EnvironmentРедактор кода с инструментами отладки
ISOInternational Organization for StandardizationОрган стандартизации (например, ISO 8601 даты)
JSONJavaScript Object NotationФормат обмена данными
LTSLong-Term SupportСтабильные релизы Node.js
MSWMock Service WorkerHTTP библиотека имитации для тестов
NM IDNomenclature IDИдентификатор товара Wildberries
npmNode Package ManagerРеестр пакетов JavaScript
P9595th PercentileМетрика производительности (95% запросов быстрее этого значения)
PIIPersonally Identifiable InformationПерсональные данные клиента
PRDProduct Requirements DocumentСпецификации проекта
RESTRepresentational State TransferАрхитектурный стиль API
SDKSoftware Development KitБиблиотека для интеграции разработчиков
TDDTest-Driven DevelopmentНаписание тестов перед реализацией
TTLTime To LiveДлительность истечения кэша
TypeDocTypeScript Documentation GeneratorДокументация API из JSDoc комментариев
UUIDUniversally Unique IdentifierУникальный 128-битный идентификатор
YAMLYAML Ain't Markup LanguageЧеловеко-читаемый формат данных

Смотрите также ​

Последнее обновление: 2025-10-27 Версия SDK: 1.0.0

Made with ❤️ for the Wildberries developer community

Copyright © 2025 Wildberries API TypeScript SDK Contributors | MIT License