Документация/Аналитика: данные, показатели, формулы и качество расчётов

Руководство по работе с магазином

Аналитика: данные, показатели, формулы и качество расчётов

Справочник аналитических запросов X-MP: от выбора периода и товаров до формул показателей, проверки покрытия и воспроизводимого вывода.

Зачем это нужно

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

Пример из работы магазина

«Найди товары, где рекламные расходы росли быстрее заказанного оборота. Покажи цифры, формулу и пробелы; не называй результат чистой прибылью без затрат».

Как начать

Проверьте agent.me, readiness.get и datasets.list: нужны analytics.read и соответствующие источники магазина.
Определите вопрос, период, товары и денежную базу.
Выберите analysis.query для агрегатов, metrics.query для KPI либо dataset.query для строк.
Прочитайте значения вместе с качеством и источниками; сохраните формулу и вывод.

Что вы получите

Проверяемый срез магазина или товаров, выбранные показатели и явные ограничения достаточности. Пропуски не заменяются нулём.

Что важно учитывать

Полнота зависит от дат, товаров и источников. Старый период не становится закрытым только по возрасту. Прибыль требует подтверждённых затрат; причинный эффект не выводится из одного сравнения.

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

Уровень	Содержание	Использование
Сохранённые ответы	Неизменяемые исходные результаты сбора.	Происхождение и приватная выгрузка.
Нормализованные записи	Товары, заказы, продажи и версии сущностей.	Детализация и связь с источником.
Дневная витрина	Наблюдения товара по дням с признаками наличия источника.	Агрегат analysis.query.
Реестр KPI	Формулы, входы, единицы, детализация и зрелость.	metrics.catalog и metrics.query.
Контроль качества	Покрытие, свежесть и недостающие входы.	Допустимость вывода.

Показатель, страница строк и исходный файл — разные продукты данных. Начинайте с минимального достаточного уровня. Тысячи строк не нужно переносить в чат ради одного итога.

Как выбрать метод

Метод	Назначение	Проверка
cabinet.overview	Общая картина и ведущие товары.	Период и входы; не полный финансовый аудит.
product.360	Один артикул за период.	Товар и денежная база.
finance.summary	Финансовая сводка.	Реализация, к перечислению, выплата и прибыль различаются.
analysis.query	Выбранные показатели по магазину, товарам и дням.	Поля, группировка, качество и сортировка.
metrics.catalog / metrics.query	KPI с зарегистрированной формулой.	Сначала определение, затем значения.
metrics.status / metrics.completeness	Состояние расчётов и пробелы.	Свежесть и недостающие входы.
dataset.query	Строки для проверки вывода.	Поля, дата события и пагинация.

Параметры analysis.query

Параметр	Формат	Правило
date_from, date_to	YYYY-MM-DD	Обязательные включённые границы,1–90 дней.
group_by	account / product / day / day_product	Магазин, товар, день или товар в день. По умолчанию product.
metrics	Массив имён	1–12 разных показателей.
nm_ids	Массив строк	До 20 артикулов; без фильтра — доступные товары.
sort_by	Выбранный показатель	Обязан входить в metrics. Задавайте явно при своём наборе.
sort_direction	asc / desc	Возрастание/убывание; по умолчанию desc.
limit	1–50	Размер страницы, по умолчанию 20.
offset	0–10000	Смещение для продолжения.

SQL, произвольные таблицы и чужой account_id запрещены. Магазин определяется ключом. Общую картину удобно читать несколькими тематическими срезами, затем детализировать отклонения.

Словарь всех полей analysis.query

Поле	Единица	Определение / формула	Как понимать
ordered_units	шт.	Количество заказанных единиц.	Заказ не равен выкупу или выплате.
ordered_gmv	₽	Наблюдаемый заказанный оборот.	Не реализованная выручка.
cancelled_units	шт.	Наблюдаемые отменённые единицы.	Не финансовые возвраты и не доказанная итоговая когорта.
sales_gmv	₽	Операционные продажи.	Предварительная база, отдельно от закрытой реализации.
ad_spend	₽	Рекламные расходы источника.	Учитывать окно и полноту данных.
ad_clicks	события	Рекламные клики.	Не уникальные покупатели.
ad_impressions	события	Рекламные показы.	Не уникальный охват.
ad_orders	шт.	Заказы, отнесённые WB к рекламе.	Не доказанный дополнительный эффект рекламы.
wb_for_pay	₽	Сумма к перечислению по доступной финансовой базе.	Не подтверждение прихода в банк.
contribution_profit	₽	Подтверждённая входами часть экономического результата.	При недостатке затрат — null; не полная чистая прибыль.
stock_units	шт.	Последнее известное наличие товара в срезе.	Не сумма остатков по дням; проверять дату источника.
opens	события	Открытия карточки из воронки.	Наблюдаемый поток источника.
carts	события	Добавления в корзину.	Не оплаченные покупки.
funnel_orders	шт.	Заказы из источника воронки.	Не смешивать автоматически с оперативными orders.
average_ordered_unit_price	₽/шт.	ordered_gmv / ordered_units	Цена единицы, не средний чек корзины.
average_order_value	₽/шт.	Старый псевдоним average_ordered_unit_price.	Для новых запросов используйте точное имя цены единицы.
cancelled_order_share	доля	cancelled_units / ordered_units	Наблюдаемое покрытие, не финальная доля возвратов.
ad_ctr	доля	ad_clicks / ad_impressions	0.025 = 2,5%.
cpm	₽/1000 показов	1000 × ad_spend / ad_impressions	Множитель 1000 применяется только здесь.
cpc	₽/клик	ad_spend / ad_clicks	Наблюдаемая стоимость клика.
cpo	₽/заказ	ad_spend / ad_orders	Стоимость атрибутированного заказа, не CAC покупателя.
cart_cr	доля	carts / opens	Открытие → корзина.
order_cr	доля	funnel_orders / opens	Открытие → заказ в одном источнике.
cart_to_order_cr	доля	funnel_orders / carts	Корзина → заказ.
ad_spend_to_ordered_gmv	доля	ad_spend / ordered_gmv	Не TACoS по реализации.
ad_spend_per_ordered_unit	₽/шт.	ad_spend / ordered_units	Все заказанные единицы, не только рекламные.
operational_contribution_margin	доля	contribution_profit / sales_gmv	Операционная маржинальность, не закрытая чистая маржа.

Доля переводится в проценты умножением на 100. Нулевой знаменатель даёт null. «Не определено» и «нулевая эффективность» — разные утверждения.

Итоги, покрытие и качество

Коэффициенты считаются из сумм числителя и знаменателя на совпадающих product-day наблюдениях, а не как среднее дневных процентов. Итоговый коэффициент может отличаться от деления отдельно показанных итогов при различном покрытии.

Признак	Что проверять
numerator / denominator / multiplier	Суммы и множитель формулы.
paired_observed_days	Дни одновременного наблюдения обеих сторон отношения.
observed_days	Дни отдельного входа; не доказательство полноты всех товаров/страниц.
null / not_ready	Недостаточный вход либо неопределённое значение.
Свежесть источника	Время исходных данных, а не только построения витрины.
Полнота периода	Пропущенные дни, страницы, товары и поздние исправления.

Для account/product остаток берётся по последнему наблюдению товара в срезе, а не суммируется за каждый день. day/day_product позволяет смотреть дневные значения. Уменьшение остатка не равно продаже: возможны перемещения и другие операции.

Пример:1 клик из 10 показов в первый день и 9 из 990 во второй. Итоговый CTR=10/1000=1%, а не среднее 10% и примерно 0,91%. Для рекламы к заказам дополнительно требуется совпадающее покрытие двух источников.

Рабочие примеры запросов

analysis.query

{
  "date_from": "2026-09-01",
  "date_to": "2026-09-07",
  "group_by": "product",
  "metrics": [
    "ordered_gmv",
    "ad_spend",
    "ad_spend_to_ordered_gmv",
    "cpo"
  ],
  "sort_by": "ad_spend",
  "limit": 10
}

Срез лидеров по расходу. Большой расход сам по себе не означает убыточность: проверьте качество и экономику.

analysis.query

{
  "date_from": "2026-09-01",
  "date_to": "2026-09-07",
  "group_by": "day_product",
  "nm_ids": [
    "123456"
  ],
  "metrics": [
    "opens",
    "carts",
    "funnel_orders",
    "cart_cr",
    "order_cr"
  ],
  "sort_by": "opens",
  "limit": 20
}

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

finance.summary

{
  "date_from": "2026-09-01",
  "date_to": "2026-09-07"
}

При неизвестной или смешанной валюте суммы могут быть подавлены. Сумма к перечислению не подтверждает банковскую выплату.

Библиотека KPI и дополнительные расчёты

Прочитайте metrics.catalog: смысл, формулу, входы, единицы и поддержанную детализацию.
Проверьте metrics.status и metrics.completeness.
Передайте metric_ids, период и нужные фильтры в metrics.query.
Сопоставьте значения с определением и происхождением; не смешивайте дневные и периодные записи.

metrics.query принимает до 50 ID, но это не обещает их готовность. Без grain применяется канонический уровень метрики. product_id — внутренний UUID, nm_id — артикул; campaign_id и warehouse_id нужны только поддерживающим их KPI. ID выбираются из каталога.

Для дополнительного анализа используйте разрешённую выгрузку в среде агента. Сохраняйте период, детализацию, формулу, checksum входа и ограничения. Новому расчёту нужно отдельное имя: нельзя изменять формулу существующего KPI под прежним названием.

От показателя к решению

Сравнивайте одинаковые товары, денежную базу, длительность и покрытие.
Отделяйте наблюдение от гипотезы: «расход вырос» — факт, «из-за ставки» — версия.
Проверьте цену, наличие, ассортимент, рекламу, сезонность и запаздывание данных.
Сохраните основания и предложите отдельный план действия.
После действия проверьте результат, не объявляя любое совпадение причинным эффектом.

Методы и параметры

Параметры ниже относятся к MCP arguments. Идентичность и ключ не передаются в них. Для полного объекта config следуйте руководству домена.

cabinet.overview product.360 finance.summary analysis.query metrics.catalog metrics.status metrics.completeness metrics.query dataset.query

`cabinet.overview`

Получить компактный обзор и ограниченное число ведущих товаров.

Параметр	Тип	Обязателен	Назначение и ограничения
top_limit	целое	нет	Количество ведущих товаров в обзоре. минимум: 1; максимум: 20; по умолчанию: 10

Точная JSON Schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "top_limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 10
    }
  }
}

`product.360`

Прочитать срез одного артикула за выбранный период.

Параметр	Тип	Обязателен	Назначение и ограничения
nm_id	строка	да	Артикул WB; соблюдайте тип именно этого метода. шаблон: "^[0-9]{1,19}$"
date_from	строка	да	Дата начала; смысл события или наблюдения зависит от метода. формат: "date"
date_to	строка	да	Включённая дата окончания; проверяйте допустимую длину периода. формат: "date"

Точная JSON Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "nm_id",
    "date_from",
    "date_to"
  ],
  "properties": {
    "nm_id": {
      "type": "string",
      "pattern": "^[0-9]{1,19}$"
    },
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    }
  }
}

`finance.summary`

Получить финансовую сводку с явными денежными базами и ограничениями.

Параметр	Тип	Обязателен	Назначение и ограничения
date_from	строка	да	Дата начала; смысл события или наблюдения зависит от метода. формат: "date"
date_to	строка	да	Включённая дата окончания; проверяйте допустимую длину периода. формат: "date"

Точная JSON Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "date_from",
    "date_to"
  ],
  "properties": {
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    }
  }
}

`analysis.query`

Рассчитать агрегаты и коэффициенты по магазину, товарам и дням с признаками качества.

Параметр	Тип	Обязателен	Назначение и ограничения
date_from	строка	да	Дата начала; смысл события или наблюдения зависит от метода. формат: "date"
date_to	строка	да	Включённая дата окончания; проверяйте допустимую длину периода. формат: "date"
group_by	строка	нет	Группировка данных; проверяйте разрешённые варианты. по умолчанию: "product"; варианты: ["account", "day", "product", "day_product"]
metrics	массив	нет	Список выбранных показателей; разные сервисы имеют собственный каталог. не менее элементов: 1; не более элементов: 12; по умолчанию: ["ordered_gmv", "sales_gmv", "ad_spend", "cancelled_units"]
nm_ids	массив	нет	Список артикулов WB в пределах выбранного магазина. не более элементов: 20
sort_by	строка	нет	Выбранный показатель для сортировки; должен присутствовать в запросе. по умолчанию: "ordered_gmv"; шаблон: "^[a-z][a-z0-9_]{1,63}$"
sort_direction	строка	нет	Направление сортировки. по умолчанию: "desc"; варианты: ["asc", "desc"]
offset	целое	нет	Смещение следующей страницы либо байтов медиа; используйте значение ответа. минимум: 0; максимум: 10000; по умолчанию: 0
limit	целое	нет	Число строк/событий за страницу, а не полнота всего источника. минимум: 1; максимум: 50; по умолчанию: 20

Точная JSON Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "date_from",
    "date_to"
  ],
  "properties": {
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    },
    "group_by": {
      "type": "string",
      "enum": [
        "account",
        "day",
        "product",
        "day_product"
      ],
      "default": "product"
    },
    "metrics": {
      "type": "array",
      "minItems": 1,
      "maxItems": 12,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "ordered_units",
          "ordered_gmv",
          "cancelled_units",
          "sales_gmv",
          "ad_spend",
          "ad_clicks",
          "ad_orders",
          "wb_for_pay",
          "contribution_profit",
          "stock_units",
          "opens",
          "carts",
          "ad_impressions",
          "funnel_orders",
          "average_ordered_unit_price",
          "cpm",
          "ad_spend_to_ordered_gmv",
          "ad_spend_per_ordered_unit",
          "operational_contribution_margin",
          "average_order_value",
          "cancelled_order_share",
          "ad_ctr",
          "cpc",
          "cpo",
          "cart_cr",
          "order_cr",
          "cart_to_order_cr"
        ]
      },
      "default": [
        "ordered_gmv",
        "sales_gmv",
        "ad_spend",
        "cancelled_units"
      ]
    },
    "nm_ids": {
      "type": "array",
      "maxItems": 20,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^[0-9]{1,20}$"
      }
    },
    "sort_by": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{1,63}$",
      "default": "ordered_gmv"
    },
    "sort_direction": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000,
      "default": 0
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  }
}

`metrics.catalog`

Прочитать определения KPI: формулы, входы, единицы, детализацию и зрелость.

Параметров нет: передайте {}.

Точная JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`metrics.status`

Проверить последнюю сборку метрик и пробелы покрытия.

Параметров нет: передайте {}.

Точная JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`metrics.completeness`

Получить матрицу достаточности определений, свежесть и недостающие входы.

Параметров нет: передайте {}.

Точная JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`metrics.query`

Прочитать значения зарегистрированных KPI по периоду и измерениям.

Параметр	Тип	Обязателен	Назначение и ограничения
metric_ids	массив	да	Список выбранных показателей; разные сервисы имеют собственный каталог. не менее элементов: 1; не более элементов: 50
date_from	строка	да	Дата начала; смысл события или наблюдения зависит от метода. формат: "date"
date_to	строка	да	Включённая дата окончания; проверяйте допустимую длину периода. формат: "date"
grain	строка	нет	Зарегистрированный уровень детализации метрики. шаблон: "^[a-z][a-z0-9_]{1,63}$"
product_id	строка	нет	Внутренний UUID товара; отличается от артикула WB. формат: "uuid"
nm_id	целое	нет	Артикул WB; соблюдайте тип именно этого метода. минимум: 1
campaign_id	целое	нет	Идентификатор рекламной кампании. минимум: 1
warehouse_id	строка	нет	Идентификатор склада из доступного источника. не менее символов: 1; не более символов: 128
limit	целое	нет	Число строк/событий за страницу, а не полнота всего источника. минимум: 1; максимум: 50; по умолчанию: 20
offset	целое	нет	Смещение следующей страницы либо байтов медиа; используйте значение ответа. минимум: 0; максимум: 1000000; по умолчанию: 0

Точная JSON Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "metric_ids",
    "date_from",
    "date_to"
  ],
  "properties": {
    "metric_ids": {
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_]{1,63}$"
      }
    },
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    },
    "grain": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{1,63}$"
    },
    "product_id": {
      "type": "string",
      "format": "uuid"
    },
    "nm_id": {
      "type": "integer",
      "minimum": 1
    },
    "campaign_id": {
      "type": "integer",
      "minimum": 1
    },
    "warehouse_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000,
      "default": 0
    }
  }
}

`dataset.query`

Прочитать страницу нормализованных строк с выбранными полями, без raw payload.

Параметр	Тип	Обязателен	Назначение и ограничения
dataset_key	строка	да	Зарегистрированное имя набора из datasets.list. шаблон: "^[a-z][a-z0-9_-]{1,127}$"
fields	массив	нет	Имена выбранных полей; допустимые имена зависят от набора. не менее элементов: 1; не более элементов: 16
nm_ids	массив	нет	Список артикулов WB в пределах выбранного магазина. не более элементов: 20
date_from	строка	нет	Дата начала; смысл события или наблюдения зависит от метода. формат: "date"
date_to	строка	нет	Включённая дата окончания; проверяйте допустимую длину периода. формат: "date"
limit	целое	нет	Число строк/событий за страницу, а не полнота всего источника. минимум: 1; максимум: 50; по умолчанию: 20
offset	целое	нет	Смещение следующей страницы либо байтов медиа; используйте значение ответа. минимум: 0; максимум: 10000; по умолчанию: 0

Точная JSON Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "dataset_key"
  ],
  "properties": {
    "dataset_key": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]{1,127}$"
    },
    "fields": {
      "type": "array",
      "minItems": 1,
      "maxItems": 16,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_]*$"
      }
    },
    "nm_ids": {
      "type": "array",
      "maxItems": 20,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "pattern": "^[0-9]{1,19}$"
      }
    },
    "date_from": {
      "type": "string",
      "format": "date"
    },
    "date_to": {
      "type": "string",
      "format": "date"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000,
      "default": 0
    }
  }
}

Связанные возможности

Аналитика магазина

Разбираться в расходах, продажах и причинах изменений

Доступно. Прибыль рассчитывается только при достаточных данных о себестоимости и расходах.

Техническая справка для агента и разработчика

Этот раздел предназначен для настройки интеграции. Для обычной работы начните с шагов выше.