Метод отчёта

Метод возвращает данные для элемента воронки.

Объявите операцию

Объявите метод в OpenAPI действий приложения с x-senler-app-action: version: 1, context: "funnel", read_only: true, result: { kind: "funnel_report" }. В поле элемента укажите полное имя, например metrika__report. Метод другого приложения или метод с изменением данных использовать нельзя.

Расширение для отчёта задаётся непосредственно в OpenAPI. Декораторы и CLI пакета @senlerio/api версии 0.4.0 не поддерживают funnel; метод также не появляется как отдельное действие плагина в каталоге MCP. Это не мешает подключённой воронке получать отчёт. Подробнее — в разделе о контексте funnel.

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

В схеме тела запроса объявите поля source_id, definition_id, definition_revision, metric_key, configuration, mode, date_from, date_to, timezone, cursor, limit, include_records. Для текущего значения даты равны null; период — от date_from включительно до date_to не включительно. Максимальная страница — 500 записей, период — 366 дней, ответ — 2 МиБ. Общая статистика кешируется на минуту.

Ответ и детализация

Ответ содержит mode, as_of, total, series, records, next_cursor, records_complete. total: 0 — измеренный ноль, total: null — данных нет. as_of — дата актуальности данных. В series передаются непересекающиеся интервалы { date_from, date_to, value }; этот массив доступен только в режиме series.

Запись детализации содержит стабильный id, value, external_id или lead_id. Неиспользованный идентификатор равен null. Для точного события задаются occurred_at и два null в полях периода. Для недельного итога по человеку задаются date_from, date_to и occurred_at: null. Разбивать недельный итог на выдуманные даты нельзя. Повторный ответ для той же записи сохраняет id, идентификатор и исходную дату или период. Исправленное значение передаётся с более новым as_of.

В режиме current все три поля времени записи могут быть null: это текущее состояние без известной даты события. Такие записи сопоставляются с текущими переменными лидов без восстановления исторических связей. Страница с записями без дат не импортируется; as_of не подставляется вместо даты события. Для period и series дата события либо интервал обязательны.

Сопоставление с лидами

При identity: "none" массив records пуст, next_cursor равен null. При external_id настройка воронки выбирает переменную лида, область приложения переменной и ID счётчика или кабинета. Значение переменной — строка scope:external_id или массив таких строк. Совпадение проверяется в пределах проекта и выбранной области переменной. При нескольких подходящих лидах связь не назначается.

Чтение отчёта не сохраняет новые связи. Команда импорта фиксирует только однозначные сопоставления текущей страницы, с исходной датой или интервалом. Повторный импорт обновляет те же факты; изменение переменной лида не переписывает сохранённую связь. Отсутствующий ID можно сопоставить повторным импортом после заполнения переменной, пока источник предоставляет эту историю. Общие числа не создают лидов и не перемещают их между этапами.