Sales API — документация

Данные продаж по товарам, брендам и датам. Все запросы к /api/* требуют передачу API-ключа в заголовке.

Базовые данные (для ИИ: подставь в каждый запрос)

Эндпоинты и примеры запросов

Во всех примерах ниже замени YOUR_API_KEY на ключ выше. Даты в формате YYYY-MM-DD.

GET /api/health

Проверка доступности API.

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/health"
Ответ
{
  "ok": true
}

GET /api/dates

Список всех дат, по которым есть продажи (для выбора диапазона from/to).

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/dates"
Ответ
{
  "dates": [
    "2025-01-04",
    "2025-01-05",
    "2025-01-09",
    "..."
  ]
}

GET /api/brands

Список брендов и количество товаров по каждому.

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/brands"
Ответ
{
  "brands": [
    {
      "brand": "KANGAROO",
      "products_count": 2625
    }
  ]
}

GET /api/products

Параметры: limit (1–500, по умолч. 50), offset (для пагинации), brand (опционально — фильтр по бренду).

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/products?limit=2&offset=0"
Ответ
{
  "total": 2625,
  "offset": 0,
  "limit": 2,
  "products": [
    {
      "articul": "320805",
      "name": "Choke&carb cleaner...",
      "brand": "KANGAROO",
      "code": 643
    },
    {
      "articul": "125219",
      "name": "Compound - полироль...",
      "brand": "KANGAROO",
      "code": 1660
    }
  ]
}

GET /api/products/:articul

Один товар и его продажи по дням. :articul — артикул в URL. Параметры: from, to (даты YYYY-MM-DD, опционально).

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/products/320805?from=2025-01-01&to=2025-01-31"
Ответ
{
  "articul": "320805",
  "name": "Choke&carb cleaner - Очист.карбюр...",
  "brand": "KANGAROO",
  "code": 643,
  "salesByDate": {
    "2025-05-10": 1437,
    "2025-05-30": -108.31,
    "2025-11-29": 596.79
  }
}

GET /api/sales

Детализация продаж по дням: по каждой дате список товаров с объёмом. Параметры: from, to (YYYY-MM-DD).

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/sales?from=2025-01-01&to=2025-01-07"
Ответ
{
  "from": "2025-01-01",
  "to": "2025-01-07",
  "byDate": {
    "2025-01-04": [
      {
        "articul": "310400",
        "name": "Cosmic - полироль...",
        "value": 912
      },
      {
        "articul": "320119-M",
        "name": "Fine glass...",
        "value": 294
      }
    ],
    "2025-01-05": []
  }
}

GET /api/aggregates/sales-by-date

Сумма продаж по периодам. Параметры: from, to, granularity=day|week|month|quarter.

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/aggregates/sales-by-date?from=2025-01-01&to=2025-03-31&granularity=month"
Ответ
{
  "from": "2025-01-01",
  "to": "2025-03-31",
  "granularity": "month",
  "data": [
    {
      "period": "2025-01-01",
      "total": 12345.67
    },
    {
      "period": "2025-02-01",
      "total": 15200.3
    },
    {
      "period": "2025-03-01",
      "total": 18900.12
    }
  ]
}

GET /api/aggregates/sales-by-brand

Продажи по брендам с гранулярностью по времени. Параметры: from, to, granularity (day|week|month|quarter), brand (опционально — один бренд).

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/aggregates/sales-by-brand?from=2025-01-01&to=2025-06-30&granularity=month"
Ответ
{
  "from": "2025-01-01",
  "to": "2025-06-30",
  "granularity": "month",
  "data": [
    {
      "brand": "KANGAROO",
      "period": "2025-01-01",
      "total": 45000.5
    },
    {
      "brand": "KANGAROO",
      "period": "2025-02-01",
      "total": 52100.2
    }
  ]
}

GET /api/aggregates/sales-by-product

Продажи по товарам с гранулярностью. Параметры: from, to, granularity, articul (опционально — один товар; без него до 10k строк). limit (по умолч. 10000, макс. 50000).

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/aggregates/sales-by-product?from=2025-01-01&to=2025-12-31&granularity=month&articul=320805"
Ответ
{
  "from": "2025-01-01",
  "to": "2025-12-31",
  "granularity": "month",
  "data": [
    {
      "articul": "320805",
      "name": "Choke&carb cleaner...",
      "brand": "KANGAROO",
      "period": "2025-05-01",
      "total": 1328.69
    },
    {
      "articul": "320805",
      "name": "Choke&carb cleaner...",
      "brand": "KANGAROO",
      "period": "2025-11-01",
      "total": 596.79
    }
  ]
}

GET /api/export — полный импорт данных (потоковый)

Эндпоинт для приложений: скачать все товары и продажи одним запросом. Ответ — NDJSON (одна строка = один JSON-объект), стримится батчами, сервер не держит весь датасет в памяти. Рекомендуется передавать Accept-Encoding: gzip (сжатие включено).

Параметры: batch (50–500, по умолч. 200 — размер батча на сервере), brand (опционально — только один бренд). Заголовок ответа X-Total-Products — общее число строк.

Запрос
curl -s -H "X-API-Key: 4103c53b4fccf207500581211db61ef5f45bc4e3fc01bd09" "https://sales-api.5-star-roi.ru/api/export?batch=200"
Ответ (NDJSON, фрагмент)
{"articul":"320805","name":"Choke&carb cleaner...","brand":"KANGAROO","code":643,"sales":[["2025-05-10",1437],["2025-05-30",-108.31]]}
{"articul":"125219","name":"Compound - полироль...","brand":"KANGAROO","code":1660,"sales":[["2025-01-04",120],["2025-02-01",85.5]]}

Краткая справка для ИИ