Отчёты¶

Раздел «Отчёты» отвечает на вопрос «что получилось за период»: сколько клиентов пришло и было активно, сколько баллов начислено, потрачено и сгорело, как сработали акции, уровни и реферальная программа. Его числа переносят в отчёт для руководства или заказчика.

От раздела «Мониторинг» отчёты отличаются назначением. В мониторинге остаётся то, что разбирают построчно — аномалии, ручные начисления, конкретные операции. В отчётах — сводные величины за период. Величины местами называются одинаково, но считаются по-разному, поэтому всё, что относится к периоду, собрано здесь.

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

Где находится и кому доступен¶

Раздел открывается пунктом меню «Отчёты». Внутри — пять вкладок, у каждой свой адрес:

Вкладка	Что показывает
«Обзор»	Сводка: как себя чувствует программа и работают ли акции. Открывается первой.
«Баллы»	Движение баллов, обязательства программы, предстоящее сгорание.
«Уровни»	Переходы между уровнями и распределение клиентов по уровням.
«Акции»	Таблица акций за период с динамикой по дням и выгрузкой в файл.
«Рефералы»	Реферальная программа: срез состояния, величины периода, когорта.

Доступ ко всему разделу — роль LOYALTY_MONITORING_READ. Отдельной роли отчётности нет, вкладки между собой по ролям не разграничиваются. Без роли раздел не открывается.

Глубина¶

Период отчёта задаётся списком «Глубина» в шапке раздела: «7 дней», «30 дней», «90 дней», «Год». По умолчанию выбрано «30 дней». Окно отсчитывается назад от текущего момента и заканчивается «сейчас».

Глубина одна на весь раздел: при переключении вкладок она сохраняется, поэтому соседние вкладки всегда показывают один и тот же период. При повторном открытии раздела снова выбрано «30 дней».
Выбора произвольного диапазона дат и варианта «всё время» на экране нет.
Некоторые величины считаются на текущий момент и от глубины не зависят — предстоящее сгорание, распределение по уровням, срез состояния реферальной программы. На экране такие блоки подписаны.

Общие правила подсчёта

Тестовые клиенты не учитываются ни в одной величине отчётов.
Сгорание — не трата клиента. Сгоревшие баллы (по сроку и по кнопке оператора) показываются отдельной величиной «Сгорело» и не входят в «Списано клиентами».
Сторно — не трата клиента. Отменённые начисления показываются величиной «Сторнировано»; из «Начислено» они не вычитаются — там валовая эмиссия.
Прочерк «—» вместо доли означает, что считать было не от чего (например, за период ничего не начислено). Это не ноль.
Баллы подписаны в баллах, бюджет и выручка — в деньгах.

Обзор¶

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

Блок	Величины
«Программа»	«Клиентов в базе» (на конец периода, без удалённых), «Пришло за период» (заведено клиентов), «Активных», «Доля активных» — от базы.
«Баллы за период»	«Начислено», «Списано клиентами», «Сгорело».
«Эффективность акций»	«Акций работало», «Применений», «Начислено по акциям», «Израсходовано бюджета».

«Активных» — клиенты, совершившие за период операцию, изменившую бонусный счёт. Сгорание баллов активностью не считается — это повторяет подсказка у плитки. Любая другая операция по счёту, в том числе корректировка оператора и сторно начисления, клиента активным делает.
«Акций работало» — акции, чей период действия пересекается с окном отчёта; число совпадает с числом строк на вкладке «Акции». Щелчок по плитке открывает вкладку «Акции».
«Израсходовано бюджета» — деньги: начисления по акциям минус сторно, каждое по своему курсу.

Баллы¶

Блок	Величины
«Движение баллов за период»	«Начислено», «Списано клиентами», «Сгорело», «Сторнировано», «Скорректировано», «Доля погашения».
«Обязательства на конец периода»	«Непогашено баллов», «В деньгах», «Курс баллов».
«Предстоящее сгорание»	Таблица «Горизонт» — «Сгорит баллов» — «У скольких клиентов» для горизонтов 7, 30 и 90 дней.

«Списано клиентами» — без сгоревших и сторнированных баллов: их клиент не тратил.
«Сгорело» — плановое сгорание по сроку и сгорание, запущенное оператором.
«Скорректировано» — баллы, снятые корректировками оператора.
«Доля погашения» — списано клиентами от начисленного, в процентах. Прочерк — за период не начислено ничего.
«Непогашено баллов» считается по проводкам на конец периода по клиентским счетам в валюте баллов. «В деньгах» — та же величина по курсу баллов; прочерк, если курс баллов выражен не в базовой валюте: пересчёт был бы неверным.
«Предстоящее сгорание» считается на текущий момент и от выбранной глубины не зависит.

Уровни¶

Блок	Содержимое
«Переходы за период»	«Повышений», «Понижений», «Первых назначений», «Переносов системой».
«Распределение по уровням»	Таблица «Уровень» — «Код» — «Клиентов» по уровням активной конфигурации. Уровень без клиентов показан с нулём.
«Клиенты на прежних конфигурациях»	Таблица «Конфигурация» — «Клиентов». Блок показывается, только если такие клиенты есть.
«Переходы «уровень до → уровень после»»	Таблица «Уровень до» — «Уровень после» — «Направление» — «Клиентов»; колонка «Конфигурация» появляется, когда в выдаче переходы нескольких конфигураций.

Направления перехода: «Повышение», «Понижение», «Первое назначение», «Перенос системой». Направление определяется порядком уровней в конфигурации. У первого назначения колонка «Уровень до» пустая.
«Перенос системой» — переезд клиента на новую конфигурацию программы или перевод при удалении уровня. В повышения и понижения не входит: уровни разных конфигураций не сравниваются.
В переходы попадает и ручная работа оператора — назначение уровня, массовый перевод, снятие назначения, если они фактически сменили уровень клиента.
«Распределение по уровням» считается на текущий момент и от глубины не зависит.
«Клиенты на прежних конфигурациях» — клиенты, которые после активации новой конфигурации ещё живут по неактивной: перейдут на новую при первой покупке или списании баллов, а если операций не будет — в дату своего пересмотра.

Акции¶

Таблица строк по акциям за период. Строка — это акция целиком, со всеми её версиями: правка акции создаёт новую версию, и счёт по отдельной версии обнулял бы статистику кампании в момент правки. Название, статус и период берутся у последней версии.

В таблицу попадают акции, чей период действия пересекается с окном отчёта. Акция, которая шла весь период и ничего не дала, остаётся в таблице с нулями.

Колонка	Что показывает
«Акция»	Название акции.
«Статус»	Текущий статус акции.
«Период»	Даты начала и окончания действия акции.
«Применений»	Начислений по акции за период.
«Участников»	Различных клиентов с участием за период.
«Покупок»	Различных покупок, на которых сработала акция. Покупка, возвращённая целиком, не считается.
«Выручка»	Сумма покупок, на которых сработала акция, за вычетом возвратов, — в валюте покупок.
«Начислено»	Начислено баллов по акции за период.
«Израсходовано»	Расход бюджета в деньгах: начисления минус сторно, каждое по своему курсу.

Выручка не складывается по строкам

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

Сортировка. Все колонки сортируются, в том числе по нескольким колонкам сразу; порядок применяется на сервере ко всей выборке, а не к загруженной странице. «Период» сортируется по дате начала, «Выручка» — по сумме. Пустые значения всегда уходят в конец. Без выбранной сортировки первыми идут акции с наибольшим «Начислено». Состав колонок настраивается кнопкой-шестерёнкой «Настроить таблицу» над таблицей, ширина — перетаскиванием границы заголовка.

Динамика акции. Двойной щелчок по строке открывает боковую панель с названием акции и таблицей по дням: «Дата», «Применений», «Участников», «Начислено», «Израсходовано». В таблице только дни, в которые что-то происходило. Выручки в динамике нет.

Выгрузка таблицы¶

Кнопка «Скачать таблицу (CSV)» над таблицей выгружает файл за весь выбранный период, а не текущую страницу — это же говорит подсказка на кнопке. При сбое выводится «Не удалось выгрузить таблицу. Попробуйте ещё раз».

Графы файла: Акция, Статус, Начало, Окончание, Покупок, Выручка, Валюта выручки, Применений, Участников, Начислено, Израсходовано.
Суммы — в тех же единицах, что на экране (баллы и деньги, а не минорные единицы хранения), с двумя знаками после запятой и запятой в качестве разделителя дробной части; счётчики — целые числа. Статус выгружается кодом (например, ACTIVE), даты — днём в часовом поясе программы.
Пустая выручка (покупки в разных валютах) остаётся пустой графой вместе с валютой, а не нулём.
Разделитель полей — ;, кодировка UTF-8 с меткой порядка байтов: файл открывается числами в русской локали Excel.
Выгрузка есть только у таблицы акций: у сводных вкладок и у динамики акции кнопки выгрузки нет.

Рефералы¶

Блок	Величины
«Срез состояния»	«Всего связей», «Активировано», «Ждут первой покупки» — на момент запроса, от глубины не зависит.
«За период»	«Регистраций по коду», «Активаций».
«Когорта периода»	«Из зарегистрировавшихся по коду за период активировались» (доля), «Создано связей в периоде», «Из них активировалось».
«Начислено сторонам»	«Начислено пригласившим», «Начислено приглашённым».

«Регистраций по коду» считаются по дате регистрации: связь появляется, когда новый клиент уже зарегистрировался, указав чужой код. «Активаций» — по дате первой покупки приглашённого. Величины считаются по разным основаниям — активироваться в периоде может связь, созданная раньше, поэтому делить одну на другую нельзя. Об этом напоминает подпись под блоком.
Когорта — связи, созданные в периоде; «активировались» читается на момент запроса, а не на конец периода. Доля показана только здесь; прочерк — в периоде не создано ни одной связи.
«Ждут первой покупки» — ожидание не протухает: «ждёт» означает «ещё не купил», а не «потеряно».
Активация без начисления возможна: если на момент первой покупки активной реферальной акции не было. Поэтому число активаций и начислений не обязано совпадать.
Связь, где тестовый клиент оказался хотя бы с одной стороны, не учитывается.

Если отчёт не загрузился¶

Вместо блока выводится «Не удалось загрузить отчёт. Обновите страницу или выберите другую глубину» с кнопкой «Повторить». Шапка раздела и выбор глубины остаются доступны.

Программный интерфейс¶

Все точки — только чтение, роль LOYALTY_MONITORING_READ.

Метод и путь	Назначение
`GET /v1/reports/pulse`	Пульс программы: регистрации (итог и по дням), операции по типам движения с разрезом по источнику, активные клиенты и база.
`GET /v1/reports/points`	Баллы: движение за период, доля погашения, обязательства на конец периода, предстоящее сгорание по горизонтам 7/30/90 дней от конца окна.
`GET /v1/reports/promotions`	Акции за период, постранично (`page`, `size`, `sort`).
`GET /v1/reports/promotions/totals`	Итоги по всем акциям периода: работало акций, применений, начислено, израсходовано бюджета.
`GET /v1/reports/promotions/export`	Выгрузка отчёта по акциям в CSV за весь период.
`GET /v1/reports/promotions/{rootId}/dynamics`	Динамика одной акции (линии версий) по дням.
`GET /v1/reports/tiers`	Уровни: распределение, клиенты прежних конфигураций, переходы и их итоги.
`GET /v1/reports/referrals`	Реферальная программа: величины периода, срез `snapshot`, когорта `cohort`.

Окно задаётся параметрами from и to (ISO-8601, обе границы включительно). Без to конец окна — текущий момент, без from — конец минус 30 дней. Фактическое окно возвращается в ответе полями from и to. Начало позже конца — 422 invalid_period.
Отчёт по акциям сортируется по полям name, status, startsAt, endsAt, budgetMinor, participants, applications, purchases, revenueMinor, accruedMinor, spentInPeriodMinor, spentTotalMinor; неизвестное поле сортировки игнорируется. Строку отчёта с историей акции связывают по rootId, а не по коду: код у каждой версии свой.
Динамика неизвестной акции — 404 promotion_not_found, а не пустой ряд.
Все суммы в ответах — в минорных единицах (…Minor): баллы — у начислений и движения, деньги — у бюджета, выручки и денежной оценки обязательств.