Shop Scanner API

Описание

Shop Scanner API — сервис для поиска товаров на маркетплейсах с возможностью фильтрации по категориям, рейтингу, скидкам и диапазону цен. API позволяет искать товары на Wildberries и возвращает результаты в удобном для использования формате.

Установка и запуск

Требования

• Node.js (версия 14 или выше)
• MongoDB (версия 4.4 или выше)

Установка

1. Клонируйте репозиторий:

git clone https://github.com/your-username/Shop-Scanner.git
cd Shop-Scanner

2. Установите зависимости:

npm install

3. Создайте файл .env в корне проекта со следующим содержимым:

PORT=3000
MONGODB_URI=mongodb://localhost:27017/shop_scanner
NODE_ENV=development

Запуск

Для запуска сервера в режиме разработки:

npm run start:api

Сервер будет доступен по адресу: http://localhost:3000

Структура API

Endpoints

Категории

GET /api/categories

Возвращает список доступных категорий.

Пример ответа:

{
  "categories": ["Одежда", "Обувь", "Детские товары", "Спорт", "Красота", "Ювелирные изделия"],
  "total": 6
}

Поиск товаров (создание задачи)

POST /api/search

Создает новую задачу поиска товаров с указанными параметрами фильтрации.

Параметры запроса (в теле JSON):

• categories (array): Список категорий для поиска
• minRating (number, опционально): Минимальный рейтинг товаров
• minDiscount (number, опционально): Минимальная скидка в процентах
• priceRange (object, опционально): Диапазон цен
  • min (number): Минимальная цена
  • max (number): Максимальная цена

Пример запроса:

{
  "categories": ["Детские товары"],
  "minRating": 4,
  "minDiscount": 20,
  "priceRange": {
    "min": 1000,
    "max": 5000
  }
}

Пример ответа:

{
  "taskId": "83ea3f72-c335-4047-807b-101d6c94b717",
  "status": "pending",
  "progress": 0
}

Получение результатов поиска

GET /api/search/{taskId}

Возвращает результаты задачи поиска по её ID.

Пример ответа:

{
  "taskId": "83ea3f72-c335-4047-807b-101d6c94b717",
  "status": "completed",
  "progress": 100,
  "results": [
    {
      "id": "test-детские-товары-1",
      "title": "Тестовый товар 1 для категории Детские товары",
      "brand": "Бренд 1",
      "category": "Детские товары",
      "price": 1000,
      "originalPrice": 1500,
      "discount": 33,
      "rating": 4.73,
      "imageUrl": "https://example.com/image1.jpg",
      "productUrl": "https://example.com/product1"
    },
    // Другие товары...
  ]
}

Поиск товаров по категории

GET /api/products/{category}

Возвращает товары для указанной категории с возможностью фильтрации.

Параметры запроса (query parameters):

• minRating (опционально): Минимальный рейтинг
• minDiscount (опционально): Минимальная скидка в процентах
• minPrice (опционально): Минимальная цена
• maxPrice (опционально): Максимальная цена

Пример:

GET /api/products/Спорт?minRating=4&minDiscount=20&minPrice=1000&maxPrice=5000

Обновление данных для всех категорий

POST /api/products/update-all

Запускает обновление товаров для всех категорий.

Параметры запроса (опционально в теле JSON):

• minRating (number): Минимальный рейтинг
• minDiscount (number): Минимальная скидка
• priceRange (object): Диапазон цен
  • min (number): Минимальная цена
  • max (number): Максимальная цена

Особенности работы

Модель асинхронных задач

API использует модель асинхронных задач для поиска товаров. Это означает:

1. При запросе поиска создается задача с уникальным taskId
2. Поиск выполняется в фоновом режиме
3. Статус и результаты можно получить по ID задачи
4. Результаты сохраняются в базе данных и доступны для повторного получения

Работа с категориями

Категории определены статически в конфигурационном файле src/config/marketplaces/wildberries.ts. Каждая категория имеет:

• Имя (например, "Одежда", "Обувь")
• ID категории на Wildberries
• Subject для запроса к API Wildberries

Тестовые данные

Если API Wildberries недоступен или возвращает ошибку, система генерирует тестовые данные для обеспечения работоспособности интерфейса.

Обновление данных

В текущей версии API нет автоматического обновления данных. Обновление происходит:

1. При первом запросе к категории, если данных нет в базе
2. При вызове эндпоинта /api/products/update-all

Очистка старых задач

API имеет функцию очистки старых задач поиска (старше 24 часов), но она не вызывается автоматически.

Примеры использования с Postman

Получение списка категорий

GET http://localhost:3000/api/categories

Поиск товаров (создание задачи)

POST http://localhost:3000/api/search

{
  "categories": ["Детские товары"],
  "minRating": 4,
  "minDiscount": 20,
  "priceRange": {
    "min": 1000,
    "max": 5000
  }
}

Получение результатов поиска

GET http://localhost:3000/api/search/83ea3f72-c335-4047-807b-101d6c94b717

Получение товаров по категории

GET http://localhost:3000/api/products/Спорт?minRating=4&minDiscount=20&minPrice=1000&maxPrice=5000

Обновление данных для всех категорий

POST http://localhost:3000/api/products/update-all

{
  "minRating": 4,
  "minDiscount": 20,
  "priceRange": {
    "min": 1000,
    "max": 5000
  }
}

Технические особенности

Структура проекта

• src/app.ts - точка входа приложения
• src/controllers/ - контроллеры для обработки запросов
• src/services/ - бизнес-логика и сервисы
• src/models/ - модели данных
• src/config/ - конфигурационные файлы
• src/api/ - интерфейсы для работы с внешними API

База данных

Приложение использует MongoDB для хранения результатов поиска. Основные коллекции:

• searchresults - результаты поиска товаров

Ограничения

1. API Wildberries может блокировать запросы (код 498) из-за защиты от ботов
2. Отсутствует автоматическое обновление данных
3. Ограниченный набор категорий, определенный в конфигурации

Дальнейшее развитие

Возможные улучшения:

1. Добавить авторизацию для API
2. Реализовать периодическое обновление данных с помощью планировщика задач
3. Расширить поддержку для других маркетплейсов
4. Реализовать обход защиты от ботов для стабильного получения данных
5. Добавить кеширование запросов для повышения производительности