💰 API: Выручка

Получение данных о выручке, заказах и финансовых показателях

📌 Важно для работы с выручкой

Для корректного отображения выручки необходимо помечать события-заказы метаданными:

{
  "event": "purchase",
  "user_id": "user_123",
  "properties": {
    "revenue": 1499.99,
    "order_id": "ORD-001"
  },
  "_metadata": {
    "is_order": true,
    "order_revenue_field": "revenue",
    "order_id_field": "order_id"
  }
}

По умолчанию система ищет поле revenue в properties, но вы можете указать другое поле через метаданные.

Основные понятия

Метаданные для заказов

Метаданные Описание По умолчанию
is_order Помечает событие как заказ (обязательно) false
order_revenue_field Поле в properties, содержащее сумму заказа "revenue"
order_id_field Поле с уникальным ID заказа "order_id"
order_status_field Поле со статусом заказа "status"
order_items_field Поле с массивом товаров "items"

Пример с кастомными полями

json 
{
  "event": "order_completed",
  "user_id": "user_123",
  "properties": {
    "total_amount": 5499,
    "order_number": "ORD-2025-001",
    "payment_status": "paid",
    "products": [...]
  },
  "_metadata": {
    "is_order": true,
    "order_revenue_field": "total_amount",
    "order_id_field": "order_number",
    "order_status_field": "payment_status",
    "order_items_field": "products"
  }
}

Эндпоинты

1. Получение данных о выручке

GET /api/revenue?from=...&to=...&period=... — основной эндпоинт для получения выручки и заказов.

Параметры запроса

Параметр Описание По умолчанию
from Начальная дата (YYYY-MM-DD) -30 дней
to Конечная дата (YYYY-MM-DD) сегодня
period Тип периода (today, yesterday, week, month, quarter, year) —

Автоматическая гранулярность

Система автоматически выбирает оптимальную гранулярность в зависимости от длины периода:

Длина периода Гранулярность
1-2 дня По часам
3-30 дней По дням
31-90 дней По неделям
90+ дней По месяцам

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

bash 
curl -X GET "https://api.instantbase.online/api/revenue?from=2026-03-01&to=2026-03-19" \
  -H "Cookie: session_id=ваша_сессия"

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

{
  "daily": [
    {
      "date": "2026-03-01",
      "label": "01.03",
      "revenue": 15420.50,
      "orders": 45
    },
    {
      "date": "2026-03-02",
      "label": "02.03",
      "revenue": 18230.00,
      "orders": 52
    }
  ],
  "totals": {
    "total_revenue": 324567.89,
    "avg_daily_revenue": 10818.93,
    "days_with_sales": 19,
    "total_orders": 945,
    "avg_order_value": 343.46
  },
  "period": {
    "from": "2026-03-01",
    "to": "2026-03-19"
  },
  "granularity": "day"
}

Поля ответа

Поле Описание
daily[].date Дата периода
daily[].revenue Выручка за период
daily[].orders Количество заказов за период
totals.total_revenue Общая выручка за весь период
totals.avg_daily_revenue Средняя дневная выручка
totals.days_with_sales Количество дней с продажами
totals.total_orders Общее количество заказов
totals.avg_order_value Средний чек

2. Почасовая выручка

GET /api/revenue/hourly?date=YYYY-MM-DD — детализация по часам для конкретного дня.

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

curl -X GET "https://api.instantbase.online/api/revenue/hourly?date=2026-03-19" \
  -H "Cookie: session_id=ваша_сессия"

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

[
  {
    "hour": 0,
    "orders": 2,
    "revenue": 4500.00
  },
  {
    "hour": 10,
    "orders": 5,
    "revenue": 12500.00
  },
  {
    "hour": 18,
    "orders": 15,
    "revenue": 37500.00
  }
]

3. Метрики заказов

GET /api/orders/metrics?from=...&to=... — детальные метрики по заказам.

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

{
  "success": true,
  "total_orders": 945,
  "first_order_conversion": 23.5,
  "avg_order_value": 343.46,
  "repeat_orders": 12.8,
  "new_customers": 156,
  "first_order_customers": 37,
  "total_customers": 1250,
  "customers_with_orders": 312,
  "repeat_customers": 40
}
Поле Описание
total_orders Всего заказов за период
first_order_conversion % новых клиентов, совершивших первую покупку
avg_order_value Средний чек
repeat_orders % клиентов с повторными покупками (от всех клиентов)
new_customers Количество новых клиентов
first_order_customers Клиенты, совершившие первую покупку
total_customers Всего уникальных клиентов
customers_with_orders Клиенты, совершавшие покупки
repeat_customers Клиенты с >1 покупкой

4. Топ клиентов по заказам

GET /api/orders/top-customers?from=...&to=... — клиенты с наибольшим количеством заказов.

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

[
  {
    "name": "user_12345",
    "orders": 12,
    "revenue": 45600.00
  },
  {
    "name": "user_67890",
    "orders": 8,
    "revenue": 23400.00
  }
]

5. Популярные товары

GET /api/orders/popular-products?from=...&to=... — товары, отсортированные по количеству продаж.

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

{
  "success": true,
  "products": [
    {
      "product_id": "prod_1",
      "product_name": "Футболка",
      "total_quantity": 245,
      "orders_count": 120,
      "total_revenue": 367500,
      "avg_price": 1500
    },
    {
      "product_id": "prod_2",
      "product_name": "Джинсы",
      "total_quantity": 89,
      "orders_count": 78,
      "total_revenue": 311500,
      "avg_price": 3500
    }
  ]
}

6. Последние заказы

GET /api/orders/recent?limit=10 — последние заказы с информацией о клиентах.

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

{
  "orders": [
    {
      "id": 12345,
      "occurred_at": "2026-03-19 15:30:00",
      "customer_id": "user_123",
      "customer_email": "user@example.com",
      "amount": 5499.00,
      "order_id": "ORD-001",
      "status": "completed",
      "items_count": 3
    }
  ]
}

Фильтрация по приложениям

Ко всем эндпоинтам можно добавить параметр app_id для фильтрации данных по конкретному приложению:

GET /api/revenue?from=2026-03-01&to=2026-03-19&app_id=13

ID приложений можно получить из личного кабинета или через API /api/apps/list.

Воронка продаж

Получение данных воронки

GET /api/funnels/get-data?from=...&to=... — данные для построения воронки продаж.

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

{
  "success": true,
  "data": [
    {
      "step": 1,
      "name": "page_view",
      "display_name": "Просмотр товара",
      "count": 15420,
      "percentage": 100,
      "drop_percentage": 0
    },
    {
      "step": 2,
      "name": "add_to_cart",
      "display_name": "Корзина",
      "count": 2341,
      "percentage": 15.2,
      "drop_percentage": 84.8
    },
    {
      "step": 3,
      "name": "purchase",
      "display_name": "Покупка",
      "count": 945,
      "percentage": 6.1,
      "drop_percentage": 59.6
    }
  ]
}

Настройка шагов воронки

POST /api/funnels/update-steps — обновление шагов системной воронки.

Тело запроса

{
  "steps": ["page_view", "add_to_cart", "purchase"]
}

Работа с товарами (order_items)

Структура таблицы товаров

Для детального анализа товаров используется таблица order_items, которая создается автоматически при первой отправке товаров.

Поле Тип Описание
product_id string Уникальный ID товара
product_name string Название товара
category string Категория товара
price decimal Цена за единицу
quantity int Количество
total decimal Общая сумма (price * quantity)

Пример передачи товаров

{
  "event": "purchase",
  "user_id": "user_123",
  "properties": {
    "order_id": "ORD-2025-001",
    "revenue": 5499,
    "items": [
      {
        "id": "prod_1",
        "name": "Футболка",
        "category": "Одежда",
        "price": 1999,
        "quantity": 2
      },
      {
        "id": "prod_2",
        "name": "Джинсы",
        "category": "Одежда",
        "price": 3500,
        "quantity": 1
      }
    ]
  },
  "_metadata": {
    "is_order": true
  }
}

Коды ошибок

Код Описание Решение
400 Invalid date format Проверьте формат дат (YYYY-MM-DD)
400 Application not found Проверьте переданный app_id
401 Unauthorized Требуется авторизация через сессию
404 No order events defined Не найдены события, помеченные как заказы
500 Internal server error Повторите запрос позже

Рекомендации

  • Всегда помечайте заказы метаданными — "is_order": true
  • Используйте единое поле для суммы — например, всегда revenue или всегда total
  • Передавайте товары в поле items — это включит аналитику по товарам
  • Указывайте статус заказа — для фильтрации завершенных и отмененных заказов
  • Проверяйте средний чек — резкие изменения могут указывать на проблемы

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

Получение выручки за сегодня

fetch('https://api.instantbase.online/api/revenue?period=today', {
  credentials: 'include'
})
.then(r => r.json())
.then(data => {
  console.log('Сегодняшняя выручка:', data.totals.total_revenue);
});

Сравнение с прошлым месяцем

const today = new Date();
const firstDay = new Date(today.getFullYear(), today.getMonth(), 1);
const lastMonth = new Date(today.getFullYear(), today.getMonth() - 1, 1);

Promise.all([
  fetch(`/api/revenue?from=${formatDate(firstDay)}&to=${formatDate(today)}`),
  fetch(`/api/revenue?from=${formatDate(lastMonth)}&to=${formatDate(firstDay - 1)}`)
])
.then(responses => Promise.all(responses.map(r => r.json())))
.then(([current, previous]) => {
  const growth = ((current.totals.total_revenue - previous.totals.total_revenue) 
    / previous.totals.total_revenue * 100).toFixed(1);
  console.log(`Рост выручки: ${growth}%`);
});

Что дальше?

📈 Удержание

Когортный анализ и возвращаемость клиентов

Перейти →

🎯 Метаданные

Настройка воронок и метаданных событий

Перейти →

Нужна помощь с настройкой выручки?

Напишите нам, и мы поможем настроить метаданные для заказов

support@instantbase.online Telegram