Skip to main content

Products API

API для управления товарами и услугами в маркетплейсе.

Обзор​

Products API позволяет создавать, редактировать и управлять каталогом товаров. Поддерживает как физические товары, так и цифровые услуги.

Структура товара​

interface Product {
  id: string;
  marketplace_id: string;
  supplier_id: string;
  name: string;
  description: string;
  price: number;
  currency: string;
  category_id: string;
  images: ProductImage[];
  variants: ProductVariant[];
  attributes: ProductAttribute[];
  inventory: Inventory;
  status: ProductStatus;
  created_at: string;
  updated_at: string;
}

Типы товаров​

Физические товары​

  • Требуют управления запасами
  • Настройки доставки
  • Физические характеристики

Цифровые товары​

  • Мгновенная доставка
  • Файлы для скачивания
  • Лицензии и коды

Услуги​

  • Бронирование времени
  • Календарь доступности
  • Локация оказания услуг

Статусы товара​

  • draft - Черновик
  • active - Активный
  • inactive - Неактивный
  • out_of_stock - Нет в наличии
  • discontinued - Снят с производства

Основные операции​

Создание товара​

// POST /api/products
{
  "name": "Смартфон iPhone 15",
  "description": "Последняя модель iPhone",
  "price": 89990,
  "currency": "RUB",
  "category_id": "uuid",
  "images": [
    {
      "url": "https://...",
      "alt": "Основное фото"
    }
  ],
  "attributes": [
    {
      "name": "Цвет",
      "value": "Черный"
    },
    {
      "name": "Память",
      "value": "128GB"
    }
  ]
}

Поиск товаров​

// GET /api/products?search=iPhone&category=electronics&price_min=50000
{
  "products": [...],
  "total": 150,
  "filters": {
    "categories": [...],
    "price_range": [1000, 200000],
    "brands": [...]
  }
}

Варианты товара​

{
  "variants": [
    {
      "id": "uuid",
      "name": "iPhone 15 128GB Черный",
      "sku": "IP15-128-BLK",
      "price": 89990,
      "inventory": {
        "quantity": 10,
        "reserved": 2
      }
    }
  ]
}

Категории​

interface Category {
  id: string;
  name: string;
  parent_id?: string;
  attributes: CategoryAttribute[];
  children: Category[];
}

Атрибуты товаров​

interface ProductAttribute {
  name: string;
  value: string;
  type: 'text' | 'number' | 'boolean' | 'select';
  required: boolean;
  searchable: boolean;
}

Управление запасами​

// PATCH /api/products/{id}/inventory
{
  "quantity": 100,
  "operation": "set" | "add" | "subtract"
}

Семантический поиск​

Система поддерживает поиск по смыслу с использованием AI:

// GET /api/products/search/semantic?query=красивый телефон для фото
{
  "products": [...],
  "relevance_scores": [0.95, 0.87, 0.76]
}