Roistat Reports Api

---
name: roistat-reports-api
description: "Чтение отчётов Roistat, воспроизводимая сверка с сырыми сделками и коллтрекингом, а также строго ограждённая запись сохранённых отчётов."
---

# Отчёты Roistat

## Если Roistat не подключён

Roistat необязателен. Нет проекта или ключа — не создавайте их и не просите у пользователя ради чужой задачи: продажи берутся из CRM (выгрузка файлом или навык `amocrm-api-control`) или из целей Метрики, а выводы помечаются «продажи не проверены». В общих сценариях сбора вызывайте `roistat_query.sh --if-configured`: без доступа шаг пропускается, а не роняет пакет; на месте файла результата остаётся `{"status": "skipped"}`, и такой файл не считается выгрузкой продаж.

## Обязательный порядок

1. Доступ бери из `ROISTAT_PROJECT` и `ROISTAT_API_KEY` либо из указанного закрытого файла JSON с правами `0600`. Никогда не передавай ключ аргументом.
2. Точно задай период, окно, модель атрибуции, канал, фильтры и валюту.
3. Считай три источника разными: аналитический отчёт, сырые сделки и коллтрекинг. У каждого есть собственное состояние полноты.
4. Сырые сделки и коллтрекинг запрашивай только с явным `--include-personal-data`; полученные пакеты остаются закрытыми.
5. Проходи всю постраничную выдачу. Статус `partial` не превращай в полный отчёт.
6. Каждое число должно воспроизводиться из сохранённых ответов и `report-context.json`.

## Чтение и сверка

Используй `scripts/build_roistat_report_pack.py`. Он сохраняет исходный ответ аналитики, нормализованные строки, параметры и отдельный расчёт расхождений.

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

## Запись

`scripts/save_roistat_report.py` до сетевого вызова проверяет:

- точную контрольную сумму спецификации;
- закрытое подтверждение владельца не старше 24 часов;
- точное совпадение проекта, действия и целевого отчёта;
- `ROISTAT_WRITE_ARMED=1` и отдельный `ROISTAT_WRITE_API_KEY`;
- чтение до записи, чтение после записи, неизменность посторонних отчётов и кандидат на откат.

Без `--apply` выполняется только местная проверка. Любой откат требует нового подтверждения.

## Правила из практики

**Коллтрекинг** — отдельный живой контур, не равный отчётам и доставке заявок. Перед изменением подмены номеров, пулов, сценариев или ключей телефонии сначала инвентаризация на чтение через API. Раздельно держать ключ кода отслеживания, номер проекта, ключ API, ключ телефонии, пул номеров, сценарий, область доменов и путь доставки заявок; один идентификатор не подставляется вместо другого, даже если запрос где-то прошёл. Запись в коллтрекинг — отдельное разрешение: снимок сценария и пула до изменения, понятное название пула и области, чтение сразу после записи.

**Звонки.** Исходный статус ответа, общая длительность вызова и длительность разговора хранятся раздельно, включая нулевые и пустые значения; их смысл у конкретного поставщика выясняется до выводов. Статус ответа и общая длительность не доказывают разговора; нулевая длительность разговора не доказывает ни его, ни его отсутствия.

**Клиентские сводки.** Каждая цифра привязана к источнику и каналу до финального текста: отчёт или метрика, окно дат, модель атрибуции, граница канала. Видимая метрика Roistat или выгрузки источника предпочтительнее реконструированной формулы CRM; формула-гипотеза помечается непроверенной. Блок про один канал (Директ, соцсеть, SEO, мессенджер) не включает продажи, выручку, заявки и расходы всех каналов; общие итоги — в отдельном явно названном блоке.

**Подписи колонок.** В отчётах для руководителя пользовательские колонки называются по-русски, и в заголовке указан источник логики: «Roistat, системный расчёт», «CRM, ручная отметка менеджера», «Диагностика расхождений». Старые дубли без подписи источника убираются. Если просят «сделать колонки шире», сначала проверить живой JSON сохранённого отчёта: полей ширины в контракте может не быть, и тогда менять ширину через API не обещать.

**Поздние события CRM.** Часть поздних неоплаченных сделок привязывается к старым визитам, поэтому `integration/order/list` может вернуть больше строк, чем `analytics/data`. Это не обязательно ошибка формулы: расхождение показывается, а не маскируется переименованием метрики; причина (старые визиты, поздние события, модель атрибуции, нет идентичности) подтверждается доказательствами.

**Исторический отчёт.** Для отчёта, уже сверённого за период, фиксируются набор заказов и полный исходный снимок атрибуции до свежего обогащения. Если CRM или Roistat позже изменили источник, кампанию, метку или визит, историческая атрибуция молча не переписывается: присоединяются только неатрибуционные свежие поля, строки с изменённой атрибуцией фиксируются отдельно, и доказывается, что исключённые каналы не попали в зависимые агрегаты.

**Модели атрибуции рядом.** Задача не выполнена, пока значения не проверены живым `analytics/data`: сохранённый отчёт может принимать разные `attributionModel` и возвращать одинаковые числа. Ложные дубли в боевом отчёте не оставлять. У встроенных метрик колонка — `{id, attributionModel, isAvailable}` без редактируемой подписи; легенда моделей — в названии отчёта или сопроводительном тексте. Формульные обёртки над встроенными метриками могут игнорировать атрибуцию — для таблицы нескольких моделей их без проверки не использовать. Продажи, оплаченные в периоде, но созданные раньше, — отдельным сохранённым отчётом с `date_filter_type=payment`, сверенным с сырыми заказами.

**Процентные метрики и `custom_N`.** У пользовательских метрик с «%», «доля», «конверсия» в названии или долевой формулой проверить `type` через `metrics/custom/list` и при необходимости поставить `percent`, затем перечитать тип из API. `N` в `custom_N` — идентификатор метрики, а не значение: сначала разрешить его по актуальному списку и перечитать `title`, `type`, `formula`.

**Граница отчёта при нескольких источниках.** Для отчётов, совмещающих Roistat, CRM и таблицы, сначала журнал границ: окно заявок, окно продаж и оплат, моменты чтения Roistat и CRM, источник расходов, количества заявок, новизна и повторность, менеджер, квалификация, статус, выручка. Если пользователь ограничил Roistat ролью «расходы и число заявок», новизна, менеджер, квалификация, продажи и выручка берутся из CRM или базы продукта либо остаются неразрешёнными.

**Доказательный пакет таблицы Roistat + CRM.** Кроме агрегатов сохраняются: сырой охват заказов и источников Roistat, свежая схема CRM, граф идентичности по компаниям, контактам и сделкам, правило приоритета типа клиента, отсечка связанных сделок `0 < created_at < report_cutoff`, источник каждого значения типа клиента (`primary`, `fallback`, `conflict`, `no_data`), счётчики неразрешённого и конфликтов, проверка итоговой таблицы после вставки или перестановки колонок (формулы, диапазоны, заголовки, выборочные строки). Пустой тип клиента — не подтверждённый ноль.

**Имена источников — не доказательство.** Название источника, вложенная метка или похожее имя канала не доказывают включения. Перед включением канала доказать область клиента, точный путь источника или метку, окно дат и связь с заказами.

**Удалённые и недоступные сделки** различаются как `confirmed_zero`, `unknown_missing_amount`, `deleted_inaccessible`, `not_in_scope`, `not_sale`. Успешная сделка с неизвестной суммой — не ноль: зависимые ячейки выручки и ROI блокируются или остаются неразрешёнными с явным счётчиком.

**Проверка боевого отчёта** — четыре уровня: формула (метрика читается через API с ожидаемыми `title`, `type`, `formula`); агрегат (`analytics/data` вернул значения по окну и срезам, итоги сохранены); сырые сделки (`integration/order/list` с `extend=["visit"]` подтверждает продажи и выручку, расхождения по заявкам записаны); формат (процентные колонки с `type=percent`, нет ложных пометок в названиях, одинаковые по названию колонки не скрывают разные модели).

**Ручные поля CRM** («новый лид», «повторный клиент») — диагностический сигнал, а не истина. Слой истины строится по фактической истории: `had_prior_lead`, `had_prior_paid_sale`, возраст визита.

**Решение о запуске рекламы** не опирается на одну сводку Roistat. Сохраняются сырой `integration/order/list` с `extend=["visit"]`, окно дат, посылка атрибуции и фильтры. Принятые состояния заказа сначала формулируются человеческим языком и сопоставляются с полями CRM на образцах строк. Если запуск использует вывод Roistat — компактный артефакт: источник, диапазон дат, принятые статусы, число принятых и отклонённых строк, путь и хеш сырого файла.

**Расходы Директа меньше, чем в Roistat** (или наоборот): сначала сопоставить один завершённый день в часовом поясе клиента и одинаковые кампании; Директ читать отдельно с НДС и без. Проверить полную выдачу меток, но не приравнивать разметку визитов к импорту расходов. Через `GET /project/health/indicator/list` (`roistat_query.sh … --http-method GET`) сравнить сообщения процессов загрузки расходов и обновления аналитики. Разницу не вводить ручным расходом. Восстановление синхронизации — только с разрешения и только нужные процессы; суммы до и после сохраняются, успешный запуск не означает завершения пересчёта.

Порядок новой задачи по умолчанию: документация → обзор сохранённых отчётов, метрик, полей заказа и моделей атрибуции → новая спецификация → срезы атрибуции → проверка сырыми сделками → запись при необходимости → пакет отчёта. Контракты методов и проверенные приёмы — в [справочнике методов](references/reporting-endpoints.md).

## Граница публикации

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