OZON Seller API SDK - Документация

Полная документация для SDK OZON Seller API с 278 endpoints в 33 категориях.

📚 Обзор

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

🎯 Основные возможности

  • Управление товарами - создание, редактирование, управление остатками и ценами
  • Обработка заказов - FBO/FBS заказы, доставка, отслеживание
  • Складская логистика - управление складами, поставками, возвратами
  • Финансовая отчетность - транзакции, комиссии, выплаты
  • Маркетинг и продвижение - акции, реклама, аналитика
  • Взаимодействие с клиентами - отзывы, вопросы, чат поддержка

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

Установка

npm install bmad-ozon-seller-api

Инициализация

import { OzonSellerAPI } from 'bmad-ozon-seller-api';

const api = new OzonSellerAPI({
  clientId: 'your-client-id',
  apiKey: 'your-api-key'
});

Первый запрос

// Получить информацию о продавце
const sellerInfo = await api.seller.getInfo();
console.log('Продавец:', sellerInfo.name);

// Получить список товаров
const products = await api.product.getList({ limit: 10 });
console.log(`Найдено товаров: ${products.total}`);

📖 Категории API

🛍️ Управление товарами

  • Product API - Основное управление товарами (23 endpoints)
  • Category API - Работа с категориями (6 endpoints)
  • Brand API - Управление брендами (1 endpoint)
  • Barcode API - Генерация штрих-кодов (2 endpoints)

📦 Заказы и логистика

🏭 Склады и инвентарь

💰 Финансы и платежи

  • Finance API - Финансовая отчетность (10 endpoints)
  • Report API - Бизнес-отчеты (8 endpoints)
  • Analytics API - Аналитические данные (2 endpoints)

🔄 Возвраты и отмены

🎯 Маркетинг и продвижение

  • Promos API - Акции и промо-кампании (8 endpoints)
  • Premium API - Premium сервисы (8 endpoints)
  • Pricing Strategy API - Стратегии ценообразования (12 endpoints)

👥 Взаимодействие с клиентами

  • Review API - Отзывы покупателей (7 endpoints) Premium Plus
  • Questions Answers API - Вопросы и ответы (8 endpoints) Premium Plus
  • Chat API - Чат с покупателями (8 endpoints)

📊 Рейтинги и качество

  • Seller Rating API - Рейтинги продавца (2 endpoints)
  • Quants API - Товары эконом-сегмента (2 endpoints)

🔧 Специализированные API

🧪 Экспериментальные и служебные

  • Beta Method API - Экспериментальные методы (9 endpoints)
  • Pass API - Пропуска и доступы (7 endpoints)
  • Polygon API - Тестовая среда (4 endpoints)

🛡️ Требования к подписке

Некоторые API требуют специальных подписок:

Premium Plus (требуется подписка)

  • Review API - Управление отзывами
  • Questions Answers API - Вопросы и ответы

Все остальные API доступны для всех продавцов

📋 Типовые сценарии использования

1. Создание и управление товарами

// Создание товара
const newProduct = await api.product.create({
  name: 'Новый товар',
  category_id: 12345,
  price: '1000',
  // ... другие параметры
});

// Обновление остатков
await api.pricesStocks.updateStocks([{
  product_id: newProduct.product_id,
  stock: 100
}]);

// Обновление цены
await api.pricesStocks.updatePrices([{
  product_id: newProduct.product_id,
  price: '1200'
}]);

2. Обработка заказов FBS

// Получение новых заказов
const orders = await api.fbs.getOrdersList({
  filter: { status: 'awaiting_packaging' },
  limit: 50
});

// Сборка заказа
for (const order of orders.result) {
  await api.fbs.packOrder({
    posting_number: order.posting_number,
    packages: [/* пакеты */]
  });
  
  // Передача в доставку
  await api.fbs.shipOrder({
    posting_number: order.posting_number,
    tracking_number: 'TRACK123'
  });
}

3. Управление финансами

// Получение транзакций за месяц
const transactions = await api.finance.getTransactionsList({
  filter: {
    date: {
      from: '2024-01-01T00:00:00Z',
      to: '2024-01-31T23:59:59Z'
    }
  }
});

// Анализ доходов и расходов
const totalIncome = transactions.result
  .filter(t => t.operation_type === 'ClientReturnAgentOperation')
  .reduce((sum, t) => sum + parseFloat(t.amount), 0);

console.log('Доход за месяц:', totalIncome);

4. Работа с отзывами (Premium Plus)

// Получение новых отзывов
const reviews = await api.review.getList({
  status: 'UNPROCESSED',
  limit: 20
});

// Ответ на отзыв
for (const review of reviews.reviews) {
  await api.review.createComment({
    review_id: review.id,
    text: 'Спасибо за отзыв! Учтем ваши пожелания.',
    mark_review_as_processed: true
  });
}

🔄 Интеграционные паттерны

Синхронизация товаров

class ProductSynchronizer {
  async syncProducts() {
    // 1. Получить товары из внешней системы
    // 2. Сравнить с товарами в OZON
    // 3. Создать/обновить товары
    // 4. Синхронизировать остатки и цены
    // 5. Обновить изображения и описания
  }
}

Автоматизация заказов

class OrderAutomation {
  async processOrders() {
    // 1. Получить новые заказы
    // 2. Проверить доступность товаров
    // 3. Собрать и упаковать заказы
    // 4. Передать в службу доставки
    // 5. Отправить уведомления покупателям
  }
}

Мониторинг рейтингов

class RatingMonitor {
  async monitorRatings() {
    // 1. Получить текущие рейтинги
    // 2. Сравнить с пороговыми значениями
    // 3. Отправить предупреждения при ухудшении
    // 4. Сгенерировать рекомендации по улучшению
  }
}

🛠️ Утилиты и хелперы

Batch операции

// Массовое обновление цен
const batchUpdatePrices = async (products: ProductPrice[]) => {
  const batches = chunkArray(products, 1000); // Разбиваем на батчи
  
  for (const batch of batches) {
    await api.pricesStocks.updatePrices(batch);
    await delay(1000); // Соблюдаем лимиты API
  }
};

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

const withRetry = async <T>(
  operation: () => Promise<T>,
  maxRetries: number = 3
): Promise<T> => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await delay(Math.pow(2, attempt) * 1000);
    }
  }
  throw new Error('All retries failed');
};

📊 Мониторинг и метрики

Основные метрики для отслеживания

  • Конверсия заказов - процент успешно обработанных заказов
  • Время обработки - среднее время от заказа до отгрузки
  • Рейтинг продавца - динамика основных показателей
  • Остатки товаров - контроль наличия популярных позиций
  • Финансовые показатели - доходы, расходы, рентабельность

Система алертов

  • Критическое снижение рейтинга
  • Заканчивающиеся остатки товаров
  • Проблемы с заказами
  • Финансовые аномалии

🔐 Безопасность

Управление API ключами

  • Регулярная ротация ключей
  • Ограничение доступа по IP
  • Логирование всех запросов
  • Мониторинг подозрительной активности

Лимиты запросов

  • Стандартные операции: 1000 запросов/минуту
  • Тяжелые операции: 100 запросов/минуту
  • Загрузка файлов: 50 запросов/минуту

Лучшие практики

  • Кэширование данных для снижения нагрузки
  • Batch операции для массовых обновлений
  • Асинхронная обработка для длительных операций
  • Graceful degradation при недоступности API

🐛 Отладка и диагностика

Логирование

const api = new OzonSellerAPI({
  clientId: 'your-client-id',
  apiKey: 'your-api-key',
  debug: true // Включение подробного логирования
});

Типичные проблемы и решения

401 Unauthorized

  • Проверьте корректность Client ID и API Key
  • Убедитесь, что ключи не истекли

429 Too Many Requests

  • Реализуйте exponential backoff
  • Используйте batch операции
  • Добавьте задержки между запросами

422 Validation Error

  • Проверьте корректность передаваемых данных
  • Используйте TypeScript для валидации типов
  • Изучите документацию конкретного метода

📞 Поддержка

Официальная документация

Сообщество разработчиков

Техническая поддержка

  • Email: api-support@ozon.ru
  • Форма обратной связи в личном кабинете продавца

📝 Лицензия

MIT License - см. файл LICENSE для деталей.

🤝 Вклад в развитие

Мы приветствуем вклад сообщества! См. CONTRIBUTING.md для инструкций по внесению изменений.

Версия документации: 1.0.0
Дата обновления: 2024-01-15
Покрытие API: 278 endpoints в 33 категориях
Совместимость: OZON Seller API v2/v3