> ## Documentation Index > Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Рефералы и клиенты > Реферальная программа (агенты, история начислений) и клиентская аналитика (список, отток, рост). Полный перечень полей — в [глоссарии](/ru/logic/metrics/referrals-clients-glossary). ## Обзор Страница «Рефералы и клиенты» объединяет два независимых блока аналитики: * **Реферальная программа** — сколько компания начислила вознаграждений агентам-рефералам за период, кто эти агенты и какова история отдельных начислений. * **Клиентская аналитика** — список клиентов с денежными показателями по каждому (прогноз, долг, оплаты), а также сводный обзор роста базы, оттока, LTV и демографии. Оба блока строятся поверх операционных данных аренд (заявок) и почти везде фильтруются по выбранному периоду дат. Способ выбора периода и его влияние на расчёты различаются между отдельными отчётами внутри страницы — это подробно описано в каждом разделе ниже. Все процентные и денежные показатели являются вычисляемыми — они не хранятся отдельно в базе, а собираются "на лету" по каждому запросу, исходя из связанных аренд, платежей и начислений. ## Реферальная программа ### Модель данных Реферальная программа держится на двух сущностях: | Сущность | Назначение | | ---------------------- | ---------------------------------------------------------------------------------------------- | | Реферальный агент | Партнёр, который приводит клиентов компании; хранит только имя и телефон | | Начисление по рефералу | Запись о вознаграждении агенту за конкретную аренду: сумма, статус выплаты, дата смены статуса | Начисление всегда привязано к конкретной аренде (заявке), а агент у начисления не обязателен — то есть можно зафиксировать вознаграждение без указания того, кому оно причитается (например, если агент ещё не выбран или начисление оформлено ошибочно и требует ручной донастройки). Статус начисления — это перечисление из двух значений: «Выплачено» и «Ожидает выплаты». Дата смены статуса заполняется отдельно и не связана автоматически с созданием начисления — то есть возможна ситуация, когда начисление уже существует, но дата смены статуса ещё не установлена. ### Период, по которому считается программа Все три отчёта реферальной программы (сводка, история начислений, список агентов) фильтруют начисления **по дате окончания аренды**, а не по дате создания самого начисления. Это значит, что начисление попадёт в отчёт за тот период, когда закончилась аренда, за которую оно выплачивается — независимо от того, когда фактически было создано начисление или изменён его статус. Период задаётся общими параметрами начала и конца диапазона дат (по умолчанию — текущий календарный месяц, если период не передан явно). ### Сводка по рефералам Сводный отчёт возвращает три агрегированных значения по всем начислениям, у которых аренда закончилась в выбранном периоде: | Показатель | Как считается | | --------------------- | --------------------------------------------------------------------------- | | Количество начислений | Число записей начислений, у которых дата окончания аренды попадает в период | | Сумма начислений | Сумма вознаграждений по этим начислениям | | Среднее начисление | Средняя сумма вознаграждения на одно начисление за период | Если за период нет ни одного подходящего начисления, все три значения возвращаются нулевыми (а не пустыми) — специально применяется подстановка нуля, чтобы отчёт не падал и не возвращал пустое значение при отсутствии данных. Сводка поддерживает дополнительную фильтрацию — по конкретному агенту, по статусу самой аренды и по статусу начисления. Полнотекстовый поиск по номеру заявки, имени или телефону агента для этого отчёта настроен на уровне полей, но фактически не работает: механизм поиска не подключён к сводному отчёту, поэтому такие параметры поиска будут проигнорированы. ### История начислений Отдельный отчёт возвращает построчную историю начислений за период (та же фильтрация по дате окончания аренды), отсортированную от новых к старым по дате создания начисления. Для каждой строки дополнительно подтягивается статус самой аренды (не путать со статусом начисления) — это позволяет видеть, находится ли аренда, за которую начислено вознаграждение, всё ещё в процессе, завершена или отменена. История поддерживает те же фильтры, что и сводка — по агенту, по статусу аренды, по статусу начисления, — а также (в отличие от сводки) действительно работающий полнотекстовый поиск и сортировку по сумме, статусу и номеру заявки. При добавлении или изменении начисления через историю действует отдельное бизнес-правило: если аренда уже завершена или отменена, менять её начисления может только пользователь с ролью суперпользователя компании или отдельным правом на изменение завершённых записей — иначе операция будет отклонена с ошибкой. Это защищает исторические начисления по закрытым арендам от случайного редактирования рядовыми сотрудниками. При удалении начисления эта проверка не выполняется — запись можно удалить независимо от статуса аренды. ### Список реферальных агентов Отчёт по агентам показывает каждого агента с двумя вычисляемыми показателями за выбранный период (снова по дате окончания аренды): | Показатель | Как считается | | ---------------------------- | ---------------------------------------------------------------------------------------------------- | | Сумма начислений за период | Сумма всех начислений агента, у которых аренда закончилась в периоде — независимо от статуса выплаты | | Сумма выплаченных начислений | То же самое, но только начисления со статусом «Выплачено» | Если у агента за период вообще нет начислений, попадающих в фильтр, оба показателя возвращаются пустыми (не нулём) — в отличие от сводного отчёта, где явно подставляется ноль. При сортировке или отображении такого агента это нужно трактовать как «нет данных за период», а не как «начислено на 0». Кроме того, сам отчёт по агентам не возвращает имя и телефон агента — только его идентификатор и два суммовых показателя; для отображения имени агента эти данные нужно получать отдельно. Список можно отфильтровать по статусу аренды, к которой относятся начисления агента, и отсортировать по сумме всех начислений или по сумме выплаченных. ## Клиентская аналитика ### Модель данных Базовая единица клиентской аналитики — клиент: физическое лицо или юридическое лицо (со своей организационно-правовой формой — ИП, ТОО, АО или производственный кооператив). У клиента есть дата создания (регистрации), а также отдельная связанная запись об отключении клиента — если такая запись существует, клиент считается деактивированным; сама запись хранит дату и способ отключения и не является просто датой в карточке клиента. Все отчёты клиентской аналитики (список, обзор, графики роста и оттока) учитывают только клиентов без записи об отключении. Деактивированные клиенты полностью исключаются из всех расчётов, включая исторические показатели роста — то есть, если клиент был отключён, он не будет учтён даже в подсчёте прошлых периодов. ### Список клиентов Список клиентов — это основная таблица с фильтрами (по типу, телефону, меткам, источнику привлечения, форме юрлица, статусу подписания, ИИН, БИН, имени) и полнотекстовым поиском по имени, комментарию, email, номеру договора, телефону, ИИН и БИН. Для каждого клиента дополнительно вычисляются денежные показатели: | Показатель | Смысл | Период | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | Прогноз (всего) | Сумма прогнозируемой выручки по учитываемым операциям клиента (аренды, продажи, работы) за всё время | без ограничения | | Прогноз за период | То же самое, но только по прогнозам, дата которых попадает в выбранный диапазон | по периоду | | Долг (всего) | Разница между прогнозом и фактически признанной прибылью по этим операциям клиента | без ограничения | | Долг за период | То же самое, но ограничено периодом | по периоду | | Сумма транзакций | Сумма фактических платежей клиента; если период не передан — считается за всё время, если передан — только платежи внутри периода | по периоду или за всё время | | Задолженность по оплате | Разница между прогнозом за период и фактически оплаченной суммой | по периоду | Период для списка клиентов задаётся отдельной парой параметров — по дате создания клиента, а не общими параметрами начала/конца диапазона, используемыми в остальных отчётах этой страницы. Если оба параметра периода для списка клиентов не переданы одновременно, сумма транзакций действительно считается без ограничения по датам, но показатели «за период» (прогноз за период, долг за период и задолженность по оплате) в этом случае приводят к ошибке запроса, а не к расчёту «без ограничения» — технически используемый способ построения условия периода не допускает отсутствия обеих дат одновременно. На практике это означает, что оба параметра периода для списка клиентов нужно передавать либо оба вместе, либо не передавать вовсе только в расчёте на показатель суммы транзакций, понимая, что остальные показатели за период при этом не отработают штатно. Все денежные показатели вычисляются заранее в самом запросе к базе (а не после получения данных), что позволяет сортировать список клиентов по любому из них — например, показать сначала клиентов с наибольшим долгом. Помимо перечисленного, в карточке клиента в списке также отображаются бонусы клиента и привязанные к нему метки. Поле баланса кошелька Kaspi присутствует в структуре ответа, но в этом отчёте оно не заполняется данными ни при каких условиях и всегда возвращается пустым — наполнение баланса подключено только в отдельной карточке клиента, не в этом списке. ### Обзор клиентской аналитики Обзорная карточка — это набор показателей за выбранный период, где почти каждый показатель оформлен в виде блока "текущее значение / значение за предыдущий период / изменение в процентах". Изменение в процентах считается по формуле: (текущее значение делить на предыдущее и умножить на 100) минус 100. Если предыдущего значения нет или оно равно нулю, изменение считается равным нулю — деление на ноль не допускается. Период сравнения для обзора по умолчанию — текущий календарный месяц (если конкретные даты не переданы), а не последние 30 дней и не произвольный период предыдущего запроса. Показатели обзора: **Количество клиентов** — общее число активных (не отключённых) клиентов, у которых дата создания не позже конца периода. Значение "предыдущее" считается точно так же, но по дате начала периода — то есть это фактически два среза базы клиентов на две контрольные даты, а не прирост за период. **Уникальные арендаторы** — число уникальных клиентов, у которых аренда закончилась в текущем периоде (без повторов одного клиента). Значение "предыдущее" считается за предшествующий период такой же длины, сдвинутый назад от начала текущего периода. **Отток клиентов** — рассчитывается по формуле: (число клиентов с арендой, закончившейся в предыдущем периоде, такой же длины, плюс число клиентов, зарегистрированных в текущем периоде, минус число клиентов с арендой, закончившейся в текущем периоде) делить на число клиентов с арендой, закончившейся в предыдущем периоде, и умножить на 100. Если знаменатель (число клиентов из предыдущего периода) равен нулю, отток считается равным нулю. Текущее и предыдущее значение оттока клиентов в обзоре всегда равны друг другу — оба поля заполняются одним и тем же вычисленным значением. Реальной динамики оттока (сравнения с действительно предыдущим периодом) в этом конкретном показателе сейчас нет, несмотря на общий вид блока "текущее/предыдущее/изменение". **Пожизненная ценность клиента (LTV)** — оценочный показатель, учитывающий аренды, закончившиеся не раньше чем за 90 дней до конца периода (соответственно от начала периода — для предыдущего значения), без верхней границы по дате, и исключающий заявки в статусах "заявка" и "отменена". Расчёт: средняя сумма одного платежа по этим арендам умножается на количество клиентов с более чем одной арендой за эти 90 дней и делится на утроенное общее число таких аренд. Если подходящих аренд не найдено, значение равно нулю. **Распределение по полу** — процентная разбивка клиентов на мужской, женский пол и "не определено". Пол здесь **не берётся из карточки клиента**, а вычисляется отдельно по чётности седьмой цифры ИИН физического лица (чётная цифра — женский пол, нечётная — мужской); если ИИН отсутствует или не подходит под шаблон, клиент попадает в категорию "не определено". Расчёт учитывает клиентов, зарегистрированных не позже конца периода. **Распределение по возрасту** — процентная разбивка по шести возрастным группам (0–17, 18–24, 25–34, 35–44, 45–54, 55 и старше), где возраст вычисляется как разница между текущим моментом и датой рождения из паспорта физического лица. Клиенты без даты рождения (например, юридические лица) в проценты не включаются — знаменателем служит только количество клиентов с известным возрастом. Поле "показатель роста повторных обращений" присутствует в структуре обзора, но всегда возвращает ноль и в текущем/предыдущем значении — расчёт для него ещё не реализован. ### График роста числа клиентов Показывает количество новых клиентов, зарегистрированных за каждую неделю периода: точки строятся с недельным шагом от начала до конца периода, и если за какую-то неделю новых клиентов не было, в графике всё равно появляется точка с нулевым значением (пропусков в датах нет). Поддерживается дополнительная фильтрация по типу клиента, источнику привлечения и меткам — при применении фильтров общее число клиентов на графике будет отражать только отфильтрованную группу. ### График оттока клиентов Показывает процент оттока клиентов на каждую неделю периода по формуле скользящего окна: для каждой недельной точки сравнивается число активных клиентов на конец 30-дневного окна, заканчивающегося в этой точке, с числом активных клиентов на конец такого же окна, начинающегося на 30 дней раньше. Изменение выражается в процентах от более позднего (текущего) значения, а не от более раннего; если более позднее значение равно нулю, используется единица вместо него, чтобы избежать деления на ноль. Точки строятся с шагом в неделю на всём протяжении периода. ## Как это используется Оба блока — реферальная программа и клиентская аналитика — рассчитаны на панель метрик компании, где руководитель или менеджер: * проверяет, сколько компания тратит на комиссии агентам за период и сколько из этого уже выплачено, чтобы спланировать выплаты и сверить историю начислений по конкретным арендам; * отслеживает рост клиентской базы и её отток, чтобы оценить эффективность привлечения и удержания; * находит клиентов с наибольшим долгом или задолженностью по оплате прямо в общем списке, отсортировав его по нужному денежному показателю; * изучает демографию клиентской базы (пол, возраст) для маркетинговых и коммерческих решений. Все отчёты этой страницы read-only: они ничего не изменяют в данных, а только агрегируют существующие аренды, платежи и начисления под выбранный период и фильтры. Все экраны страницы, включая обзор клиентской аналитики, требуют, чтобы пользователь был штатным сотрудником компании и имел хотя бы одно право из набора прав аналитики (см. [«Права доступа к аналитике»](/ru/logic/metrics/overview#права-доступа-к-аналитике-кратко)). Раньше сводка по клиентам открывалась без входа в систему — сейчас ни один экран раздела так не открывается. ## Особенности поведения * Полнотекстовый поиск по номеру заявки, имени и телефону агента заявлен в сводном отчёте по рефералам, но фактически не работает — в отличие от истории начислений, где такой поиск подключён и работает. * В списке реферальных агентов, если у агента нет начислений с арендой, закончившейся в периоде, оба денежных показателя возвращаются пустыми, а не нулём. Сам отчёт также не возвращает имя и телефон агента — только идентификатор и суммы. * Правило об ограничении изменения начислений по завершённым или отменённым арендам действует только при добавлении и изменении начисления; при удалении эта проверка не выполняется. * Период для списка клиентов задаётся отдельными параметрами по дате создания клиента и не совпадает с общими параметрами периода, которые использует обзор клиентской аналитики и оба графика. * Пол клиента в блоке распределения по полу вычисляется по чётности седьмой цифры ИИН, а не берётся из поля пола в карточке клиента — расхождение между вручную указанным и вычисленным полом возможно и ожидаемо. * Возрастные группы вычисляются через приблизительное количество дней в году без учёта високосных лет, что даёт небольшую погрешность в пограничных случаях. * Расчёт LTV не ограничен сверху по дате окончания аренды — учитываются все аренды, закончившиеся не раньше чем за 90 дней до контрольной даты, включая более поздние даты окончания. * Все отчёты клиентской аналитики учитывают только клиентов без записи об отключении — это может занижать исторические показатели при ретроспективном сравнении. * История начислений и сводка по рефералам фильтруют по дате окончания аренды, а не по дате создания или изменения статуса начисления, поэтому начисление может попасть в отчёт за период, далёкий от момента его фактического создания или оплаты. * В списке клиентов поле баланса кошелька Kaspi присутствует в структуре ответа, но никогда не заполняется данными в этом отчёте. ## Связанные страницы Полный перечень полей реферальной программы и клиентской аналитики. Общий обзор всех отчётов панели метрик компании. Дневная сводка по компании: доход, заявки и детализация — точка входа в аналитику. Финансовые отчёты компании: список операций, прибыли и убытки, движение денег. Сводка транзакций: разбивка по видам оплаты и постраничный список операций. Учёт штрафов по арендам: автоматическое начисление, штрафы вручную и статус оплаты. История применения скидок к арендам и сводная группировка по каждой скидке из справочника. Залоги по аренде: денежные и предметные, статусы и фактические платежи. Метрики дополнительных услуг: общая сводка, список по видам, по исполнителям и история. Расчёт зарплат по выполненным действиям и учёт субаренды инвентаря сотрудникам. Амортизация единиц инвентаря и накопленная окупаемость дохода по группам и единицам. Загрузка и простой инвентаря по комплектам, группам и отдельным единицам. Список и детализация рабочих смен персонала на точках проката. Отчётность прикладных модулей: доставки, мастерская, воронки продаж, продажи и инвентаризации. Баланс, история и общая сводка бонусных начислений клиентам.