Daytona OZON Seller API TypeScript SDK

Daytona OZON Seller API TypeScript SDK

Полнофункциональный TypeScript/JavaScript SDK для работы с OZON Seller API. Построен на базе официальной MCP документации с полной типизацией и современными возможностями.

✨ Особенности

• 🎯 Полное соответствие MCP документации — все методы и типы синхронизированы с официальной схемой OZON
• 🔒 Строгая типизация TypeScript — автодополнение и проверка типов во время разработки
• 🏗️ Модульная архитектура — каждая категория API в отдельном модуле для оптимизации bundle
• 🚀 Современный ES2022+ — поддержка всех современных возможностей JavaScript
• ⚡ Высокая производительность — оптимизированные HTTP-запросы с переиспользованием соединений
• 🔄 Автоматические повторы — встроенная обработка временных сбоев и rate limiting
• 📝 Подробная документация — примеры для каждого метода с реальными use cases
• 🌍 Полная локализация — поддержка русского и английского языков в документации

📚 Архитектура SDK

SDK организован в виде модульной архитектуры с 278+ методами в 33 категориях:

import { OzonSellerApiClient } from 'daytona-ozon-seller-api';

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

// Основные модули
client.products        // 📦 Управление товарами (23+ методов)
client.finance         // 💰 Финансовые операции (10+ методов)  
client.analytics       // 📊 Аналитика и отчеты (2+ методов)
client.warehouse       // 🏪 Управление складами (2+ методов)
client.returns         // 📦 Возвраты товаров (8+ методов)
client.review          // ⭐ Отзывы и рейтинги (7+ методов)
client.promos          // 🎯 Акции и скидки (8+ методов)
client.report          // 📄 Бизнес-отчеты (8+ методов)
// ... и многие другие

🎯 Ключевые возможности

• 🛍️ Управление каталогом — создание товаров, управление ценами/остатками, категории, бренды
• 📋 Обработка заказов — FBO/FBS заказы, доставка, отслеживание, отмены
• 🏭 Складская логистика — управление складами, поставками, инвентаризация
• 💰 Финансовая аналитика — транзакции, комиссии, отчеты, выплаты
• 🎯 Маркетинг и продвижение — акции, промо-кампании, ценовые стратегии
• 👥 Работа с клиентами — отзывы, вопросы, чат поддержка, рейтинги

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

Установка

# npm
npm install daytona-ozon-seller-api

# yarn  
yarn add daytona-ozon-seller-api

# pnpm
pnpm add daytona-ozon-seller-api

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

import { OzonSellerApiClient } from 'daytona-ozon-seller-api';

// Базовая инициализация
const client = new OzonSellerApiClient({
  apiKey: 'your-api-key',
  clientId: 'your-client-id'
});

// Расширенная конфигурация
const client = new OzonSellerApiClient({
  apiKey: process.env.OZON_API_KEY!,
  clientId: process.env.OZON_CLIENT_ID!,
  baseUrl: 'https://api-seller.ozon.ru', // по умолчанию
  timeout: 30000, // 30 секунд по умолчанию
  retries: 3, // количество повторов по умолчанию
  userAgent: 'MyStore/1.0 (https://mystore.com)'
});

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

// Проверка соединения
const connectionStatus = await client.testConnection();
if (connectionStatus.success) {
  console.log('✅ Успешное подключение к OZON API');
} else {
  console.error('❌ Ошибка подключения:', connectionStatus.message);
}

// Получить список товаров с типизированным ответом
const products = await client.products.getList({
  filter: {
    visibility: 'VISIBLE',
    offer_id: ['SKU-001', 'SKU-002']
  },
  limit: 100
});

// TypeScript автоматически подсказывает доступные поля
products.result?.items?.forEach(product => {
  console.log(`${product.name}: ${product.price} руб`);
});

📖 Категории API

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

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

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

• FBO API - Fulfillment by OZON (13 endpoints)
• FBS API - Fulfillment by Seller (22 endpoints)
• FBO Supply Request API - Заявки на поставку FBO (19 endpoints)
• Delivery FBS API - Доставка FBS (18 endpoints)
• Delivery RFBS API - Доставка rFBS (8 endpoints)

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

• Warehouse API - Управление складами (2 endpoints)
• Prices Stocks API - Цены и остатки (9 endpoints)
• Pricing Strategy API - Стратегии ценообразования (12 endpoints)

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

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

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

• Return API - Управление возвратами (8 endpoints)
• Returns API - Список возвратов (1 endpoint)
• RFBS Returns API - Возвраты rFBS (8 endpoints)
• Cancellation API - Отмены заказов (7 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

• Digital API - Цифровые товары (4 endpoints)
• FBS RFBS Marks API - Маркировка товаров (13 endpoints)
• Certification API - Сертификация товаров (12 endpoints)
• Supplier API - Интеграция с поставщиками (4 endpoints)

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

• 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 для валидации типов
• Изучите документацию конкретного метода

📞 Поддержка

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

• OZON Seller API
• Центр помощи продавцов

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

• Telegram канал
• GitHub Issues

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

• 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