dmitriipolushin/wildberries-api-mcp-server

Руководство по использованию Wildberries API MCP сервера

Содержание

1. Введение
2. Установка и запуск
3. Доступные инструменты API
4. Примеры использования
5. Типичные сценарии использования
6. Получение токена API
7. Устранение неполадок

Введение

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

MCP сервер выполняет следующие функции:

• Упрощает обращение к различным эндпоинтам API Wildberries
• Обрабатывает ошибки и ограничения частоты запросов
• Унифицирует формат ответов
• Обеспечивает централизованную аутентификацию

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

Необходимые предварительные требования

• Node.js (версия 14 или выше)
• npm или yarn
• Docker и Docker Compose (опционально, для контейнеризации)
• Токен API Wildberries с соответствующими разрешениями

Способ 1: Прямая установка через Node.js

# Клонирование репозитория
git clone https://github.com/yourusername/wb-api-mcp-server.git
cd wb-api-mcp-server

# Установка зависимостей
npm install

# Запуск сервера
npm start

Сервер запустится на порту 3000 по умолчанию. Вы можете указать другой порт, установив переменную окружения PORT:

PORT=8080 npm start

Способ 2: Использование Docker

# Создание Docker-образа
docker build -t wb-api-mcp-server .

# Запуск Docker-контейнера
docker run -p 3000:3000 -d --name wb-api-mcp wb-api-mcp-server

Способ 3: Использование Docker Compose

# Запуск сервера с Docker Compose
docker-compose up -d

# Остановка сервера
docker-compose down

Проверка установки

Вы можете проверить, что сервер работает правильно, отправив запрос к эндпоинту проверки работоспособности:

curl http://localhost:3000/health

Вы должны получить ответ, подобный следующему:

{
  "status": "ok",
  "timestamp": "2023-05-21T12:34:56.789Z"
}

Доступные инструменты API

MCP сервер предоставляет следующие группы эндпоинтов:

1. Статистика продвижения (Promotion Statistics)

• POST /api/adv/fullstats - Статистика рекламных кампаний
• GET /api/adv/auto/stat-words - Статистика автоматической кампании по кластерам ключевых фраз
• GET /api/adv/stat/words - Статистика кампаний по ключевым фразам
• GET /api/adv/stats/keywords - Статистика по ключевым словам для автоматических кампаний
• POST /api/adv/stats - Статистика медийных кампаний

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

• POST /api/nm-report/detail - Получение статистики карточек товаров за период
• POST /api/nm-report/detail/history - Получение статистики карточек товаров по дням
• POST /api/nm-report/grouped/history - Получение статистики карточек товаров, сгруппированных по категориям, брендам и тегам

3. Поисковые запросы (Search Queries)

• POST /api/search-report/report - Получение данных основного отчета по поисковым запросам
• POST /api/search-report/table/groups - Получение пагинации по группам для поисковых запросов
• POST /api/search-report/table/details - Получение пагинации по товарам внутри группы
• POST /api/search-report/product/search-texts - Получение поисковых текстов по товару
• POST /api/search-report/product/orders - Получение заказов и позиций по поисковым текстам товара

4. Отчет по остаткам (Stocks Report)

• POST /api/stocks-report/products/groups - Получение данных по группам товаров для отчета по остаткам
• POST /api/stocks-report/products/products - Получение данных по товарам для отчета по остаткам
• POST /api/stocks-report/products/sizes - Получение данных по размерам для отчета по остаткам
• POST /api/stocks-report/offices - Получение данных по складам для отчета по остаткам

5. CSV-отчеты продавца (Seller Analytics CSV)

• POST /api/nm-report/downloads - Создание CSV-отчета
• GET /api/nm-report/downloads - Получение списка отчетов
• POST /api/nm-report/downloads/retry - Повторная генерация отчета
• GET /api/nm-report/downloads/file/:downloadId - Получение файла отчета

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

Получение статистики рекламных кампаний

// Использование fetch
const response = await fetch('http://localhost:3000/api/adv/fullstats', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
  },
  body: JSON.stringify([
    {
      "id": 8960367,
      "dates": [
        "2024-04-07",
        "2024-04-06"
      ]
    }
  ])
});

const data = await response.json();
console.log(data);

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

// Использование axios
const axios = require('axios');

const response = await axios.post('http://localhost:3000/api/nm-report/detail', {
  "brandNames": ["ВашБренд"],
  "objectIDs": [358],
  "tagIDs": [123],
  "nmIDs": [1234567],
  "timezone": "Europe/Moscow",
  "period": {
    "begin": "2024-04-01 00:00:00",
    "end": "2024-04-15 23:59:59"
  },
  "orderBy": {
    "field": "ordersSumRub",
    "mode": "asc"
  },
  "page": 1
}, {
  headers: {
    'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
  }
});

console.log(response.data);

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

1. Мониторинг эффективности рекламных кампаний

Сценарий: Вы хотите регулярно отслеживать эффективность ваших рекламных кампаний и анализировать ключевые метрики.

Решение с использованием MCP:

1. Настройте ежедневную задачу, которая запрашивает статистику по всем активным кампаниям.
2. Сохраняйте полученные данные в базу данных для исторического анализа.
3. Создайте дашборд, отображающий ключевые метрики (CTR, конверсии, затраты).

Пример кода:

// Получение статистики кампаний
const campaigns = [123456, 789012]; // ID ваших кампаний
const dates = [getDateString(new Date())]; // Сегодняшняя дата

// Формирование запроса
const requestData = campaigns.map(id => ({
  id: id,
  dates: dates
}));

// Отправка запроса к MCP серверу
const campaignStats = await fetchFromMcp('/api/adv/fullstats', 'POST', requestData);

// Сохранение данных и генерация отчета
saveToDatabaseAndGenerateReport(campaignStats);

2. Анализ воронки продаж товаров

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

Решение с использованием MCP:

1. Запрашивайте детальную статистику по товарам за выбранный период.
2. Анализируйте конверсии на каждом этапе (просмотр → добавление в корзину → заказ → выкуп).
3. Выявляйте товары с низкими конверсиями для оптимизации.

Пример кода:

// Получение статистики воронки продаж
const response = await fetchFromMcp('/api/nm-report/detail', 'POST', {
  "nmIDs": [/* ваши номенклатуры */],
  "timezone": "Europe/Moscow",
  "period": {
    "begin": "2024-04-01 00:00:00",
    "end": "2024-04-30 23:59:59"
  },
  "page": 1
});

// Анализ конверсий
const products = response.data.cards;
const lowConversionProducts = products.filter(product => {
  const stats = product.statistics.selectedPeriod;
  return stats.conversions.addToCartPercent < 5 || 
         stats.conversions.cartToOrderPercent < 20 ||
         stats.conversions.buyoutsPercent < 80;
});

// Генерация отчета по проблемным товарам
generateLowConversionReport(lowConversionProducts);

3. Оптимизация поисковой видимости

Сценарий: Вы хотите улучшить видимость ваших товаров в поиске Wildberries.

Решение с использованием MCP:

1. Запрашивайте отчеты по поисковым запросам для своих товаров.
2. Анализируйте, по каким запросам ваши товары имеют хорошие позиции, а по каким - плохие.
3. Оптимизируйте карточки товаров для улучшения позиций.

Пример кода:

// Получение отчета по поисковым запросам
const searchReport = await fetchFromMcp('/api/search-report/report', 'POST', {
  "currentPeriod": {
    "start": "2024-04-01",
    "end": "2024-04-30"
  },
  "positionCluster": "all",
  "orderBy": {
    "field": "avgPosition",
    "mode": "desc"
  },
  "limit": 100,
  "offset": 0
});

// Получение поисковых текстов для конкретного товара
const searchTexts = await fetchFromMcp('/api/search-report/product/search-texts', 'POST', {
  "currentPeriod": {
    "start": "2024-04-01",
    "end": "2024-04-30"
  },
  "nmIds": [1234567],
  "topOrderBy": "openCard",
  "limit": 20
});

// Анализ результатов и формирование рекомендаций
analyzeSearchPositionsAndGenerateRecommendations(searchTexts);

4. Управление запасами на основе аналитики

Сценарий: Вы хотите оптимизировать уровень запасов товаров на складах на основе данных о продажах.

Решение с использованием MCP:

1. Регулярно запрашивайте отчеты по остаткам и продажам.
2. Рассчитывайте оптимальный уровень запасов на основе скорости продаж.
3. Выявляйте товары с избыточными или недостаточными запасами.

Пример кода:

// Получение отчета по остаткам
const stocksReport = await fetchFromMcp('/api/stocks-report/products/products', 'POST', {
  "nmIDs": [/* ваши номенклатуры */],
  "currentPeriod": {
    "start": "2024-04-01",
    "end": "2024-04-30"
  },
  "stockType": "",
  "skipDeletedNm": true,
  "orderBy": {
    "field": "avgOrders",
    "mode": "desc"
  },
  "offset": 0
});

// Анализ скорости продаж и остатков
const stockOptimizationReport = stocksReport.data.items.map(item => {
  const dailySales = item.metrics.avgOrders;
  const currentStock = item.metrics.stockCount;
  const daysOfSupply = currentStock / dailySales;
  
  return {
    nmId: item.nmID,
    name: item.name,
    dailySales,
    currentStock,
    daysOfSupply,
    stockStatus: daysOfSupply < 7 ? 'LOW' : daysOfSupply > 30 ? 'HIGH' : 'OPTIMAL'
  };
});

// Генерация рекомендаций по управлению запасами
generateStockManagementRecommendations(stockOptimizationReport);

5. Генерация и анализ расширенных CSV-отчетов

Сценарий: Вы хотите получить детальные данные для глубокого анализа в Excel или другом инструменте.

Решение с использованием MCP:

1. Создайте задачу на генерацию CSV-отчета через MCP.
2. Дождитесь завершения генерации и загрузите отчет.
3. Импортируйте данные в аналитические инструменты для анализа.

Пример кода:

// Создание задачи на генерацию отчета
const reportId = generateUUID();
const createReportResponse = await fetchFromMcp('/api/nm-report/downloads', 'POST', {
  "id": reportId,
  "reportType": "DETAIL_HISTORY_REPORT",
  "userReportName": "Аналитика по товарам за апрель",
  "params": {
    "nmIDs": [/* ваши номенклатуры */],
    "startDate": "2024-04-01",
    "endDate": "2024-04-30",
    "timezone": "Europe/Moscow",
    "aggregationLevel": "day",
    "skipDeletedNm": false
  }
});

// Проверка статуса генерации (через некоторое время)
setTimeout(async () => {
  const reportStatusResponse = await fetchFromMcp('/api/nm-report/downloads', 'GET', {
    'filter[downloadIds]': [reportId]
  });
  
  const reportStatus = reportStatusResponse.data[0].status;
  
  if (reportStatus === 'SUCCESS') {
    // Загрузка отчета
    downloadReport(reportId);
  } else if (reportStatus === 'FAILED') {
    // Повторная попытка генерации
    retryReport(reportId);
  }
}, 60000); // Проверка через 1 минуту

Получение токена API

Для работы с API Wildberries через MCP сервер вам потребуется токен API. Вот как его получить:

1. Войдите в личный кабинет продавца Wildberries

   Перейдите на seller.wildberries.ru и авторизуйтесь.

2. Перейдите в раздел настроек API

   После входа в систему перейдите в раздел "Настройки" (обычно доступен из меню или профиля).

3. Перейдите в раздел управления API

   Найдите раздел "API" или "Доступ к API" или "Интеграция".

4. Создайте новый токен API

   • Нажмите "Создать новый токен" или аналогичную кнопку
   • Выберите необходимые права доступа для токена:
     • Для MCP сервера WB API вам потребуются:
       • Разрешение категории Аналитика для воронки продаж и поисковых запросов
       • Разрешение категории Продвижение для статистики рекламы
   • Укажите имя для токена (для вашего удобства)
   • При необходимости установите срок действия (или оставьте постоянным)

5. Сгенерируйте и сохраните токен

   После заполнения необходимой информации нажмите "Сгенерировать" или "Создать" для генерации токена API.

   ВАЖНО: Обязательно скопируйте и надежно сохраните ваш токен! Полный токен будет показан только один раз в целях безопасности.

Устранение неполадок

Частые проблемы

1. Отказ в соединении: Убедитесь, что сервер запущен и порт доступен.
2. Ошибки аутентификации: Проверьте, что ваш токен API Wildberries действителен и имеет необходимые разрешения.
3. Ограничение частоты запросов: Сервер обрабатывает ограничения частоты запросов API Wildberries, но вам может потребоваться подождать, если вы превысили допустимое количество запросов.

Просмотр логов

При запуске с Docker или Docker Compose логи хранятся в директории logs, которая подключена как том.

Для просмотра логов в работающем Docker-контейнере:

docker logs wb-api-mcp

Коды ошибок

• 401 - Ошибка аутентификации (проверьте ваш токен API)
• 429 - Превышение лимита запросов (подождите некоторое время)
• 400 - Неверный запрос (проверьте параметры запроса)
• 403 - Доступ запрещен (проверьте разрешения вашего токена)