AI导哈

Wildberries API中间件服务

Wildberries API MCP服务器是一个中间件服务，简化与Wildberries API的交互，提供统一接口访问分析数据和推广统计信息。适用于电商数据分析、广告效果监控和库存管理。

  • by dmitriipolushin
  • JavaScript
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 dmitriipolushin/wildberries-api-mcp-server

使用说明

如何使用Wildberries MCP API

目录

  1. Введение
  2. 安装和启动
  3. 可用的API工具
  4. 使用示例
  5. 典型使用情况
  6. 获取API令牌
  7. Устранение неполадок

Введение

Wildberries API MCP服务器是一种中间服务，简化了与Wildberries API的交互。它提供了一个统一的接口，用于访问Wildberries API中的分析数据、促销统计数据和其他信息。

MCP服务器具有以下功能：

  • 简化了对Wildberries API的各种终端的访问
  • 处理错误和查询频率限制
  • 统一回复格式
  • 提供集中身份验证

安装和启动

必要的先决条件

  • Node.js（14或更高版本）
  • npm纱线
  • Docker和Docker Compose（可选，用于容器化）
  • 具有适当权限的Wildberries API令牌

方法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

方法二：使用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单词 -关键字组自动活动统计
  • GET/api/adv/stat/words -关键词活动统计
  • GET/api/adv/stats/关键字 -自动活动关键字统计
  • POST/api/adv/stats -媒体活动统计

2.销售漏斗（sales funnel）

  • POST/api/nm报告/详细信息 -获取期间商品卡统计
  • POST/api/nm报告/详细信息/历史记录 -按日检索商品卡统计数据
  • POST/api/nm报告/分组/历史 -获取按类别、品牌和标签分类的商品卡统计数据

3.搜索查询（Search Queries）

  • POST/api/搜索报告/报告 -通过搜索查询检索主报告数据
  • POST/api/搜索报告/表/组 -按搜索查询组进行搜索
  • POST/api/搜索报告/表/详细信息 -对集团内货物进行清关
  • POST/api/搜索报告/产品/搜索文本 -获取产品搜索文本
  • POST/api/搜索报告/产品/订单 -在产品搜索文本中获得订单和位置

4.余额报告（Stocks Report）

  • POST/api/库存报告/产品/组 -为余额报告获取产品组数据
  • POST/api/库存报告/产品/产品 -为余额报告获取货物数据
  • POST/api/库存报告/产品/尺寸 -获取余额报告的尺寸数据
  • POST/api/库存报告/办公室 -为余额报告获取库存数据

5.CSV-卖家分析CSV

  • POST/api/nm报告/下载 -创建CSV报告
  • GET/api/nm报告/下载 -获取报告列表
  • POST/api/nm报告/下载/重试 -重新生成报表
  • GET/api/nm报告/下载/文件/：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、转换、成本）的Dashboard。

Пример кода:

// Получение статистики кампаний
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. 创建一个任务以通过MCP生成CSV报告。
  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令牌

要通过MCP服务器使用Wildberries API，您需要一个API令牌。以下是如何获得它：

  1. 登录Wildberries卖家的个人帐户

    转到 seller.wildberries.ru 登录。

  2. 转到API设置部分

    登录后，转到“设置”部分（通常从菜单或配置文件中可用）。

  3. 转到API管理部分

    找到“API”或“API访问”或“集成”部分。

  4. 创建新的API令牌

    • 点击“创建新令牌”或类似按钮
    • 选择令牌的必要访问权限：
      • 对于WB API MCP服务器，您需要：
        • 类别分辨率 分析 用于销售和搜索漏斗
        • 类别分辨率 推广 广告统计
    • 请输入令牌的名称（以方便您）
    • 如有必要，请设定有效期（或保持永久性）

  5. 生成并保存令牌

    填写所需信息后，单击“生成”或“创建”以生成API令牌。

    重要：一定要复制并可靠地保存您的代币！出于安全原因，完整令牌只能显示一次。

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

常见问题

  1. 断接：验证服务器是否已启动，端口是否可用。
  2. 认证错误：验证您的Wildberries API令牌是否有效并具有必要的权限。
  3. 请求频率限制：服务器处理Wildberries API请求的频率限制，但您可能需要等待超过允许的请求数。

查看日志

从Docker或Docker Compose启动时，日志存储在目录中。 logs连接到汤姆。

要查看正在运行的Docker容器中的日志：

docker logs wb-api-mcp

Коды ошибок

  • 401 -身份验证失败（验证您的API令牌）
  • 429 -超过请求限制（等待一段时间）
  • 400 -请求无效（检查请求参数）
  • 403 -禁止访问（检查令牌的权限）

相关 MCP