Выгрузка отчётов и API аналитики

Выгрузка данных из CRM Битрикс24 нужна, когда встроенных отчётов и дашбордов не хватает: требуется свести цифры с другими системами, построить нестандартную аналитику или отдать данные во внешний BI. Забрать данные можно тремя способами — ручным экспортом списков в Excel, через BI-конструктор с готовыми коннекторами и программно по REST API. Разберём, когда что уместно и как это работает на практике.

Три способа забрать данные из CRM

Прежде чем настраивать выгрузку, стоит выбрать уровень, на котором вы будете работать с данными. В Битрикс24 их три, и они закрывают разные задачи:

• Ручной экспорт — кнопка «Экспорт» в списках лидов, сделок, контактов и компаний. Разовая выгрузка в Excel или CSV, когда данные нужны «здесь и сейчас» одному человеку.
• BI-конструктор — встроенный инструмент, который отдаёт данные CRM во внешние BI-системы (Power BI, Google Looker Studio, Yandex DataLens) по готовым коннекторам, без программирования.
• REST API — программная выборка через методы crm.*.list. Подходит для регулярных интеграций, своих скриптов и сторонних приложений.

Ручной экспорт списков в Excel и CSV

Самый быстрый способ. В любом списке CRM — CRM → Сделки (или Лиды, Контакты, Компании) — есть кнопка контекстного меню «Экспорт CRM» с выбором формата Excel или CSV. Выгрузятся именно те записи, что попали под текущий фильтр, поэтому перед экспортом сузьте выборку: период, стадия, ответственный, воронка.

Несколько практических моментов:

• В выгрузку идут колонки, которые сейчас видны в списке. Настройте набор полей через шестерёнку списка — включите нужные пользовательские поля, суммы, даты.
• Экспорт ограничен правами доступа: сотрудник выгрузит только те элементы, которые видит по своей роли, и только если у роли включено право «Экспорт».
• CSV удобнее для повторного импорта и загрузки в базы данных, Excel — для ручного анализа и сводных таблиц.

Отдельно данные отдаёт сам раздел CRM-аналитики: построенный отчёт или воронку можно выгрузить в изображение или данные, но это скорее для презентаций, чем для дальнейшей обработки.

BI-конструктор и внешние BI-системы

Когда нужна живая аналитика, которая обновляется сама, используют BI-конструктор (BI Builder). Это встроенный раздел, где строятся дашборды на данных CRM, а главное — есть готовые коннекторы для выгрузки во внешние системы визуализации.

Поддерживаются, в частности:

Принцип общий: BI-конструктор публикует наборы данных (сделки, лиды, счета, дела, источники), а внешняя система обращается к ним как к источнику. Вы не выгружаете файл вручную — данные тянутся автоматически при обновлении дашборда. Это правильный путь, если аналитику смотрит руководство и цифры должны быть всегда свежими.

REST API: методы выборки данных

Для интеграций и своих скриптов данные забирают через REST API. Аналитического метода «дай готовый отчёт» в Битрикс24 нет — вы выгружаете сырые сущности методами списков и агрегируете их на своей стороне. Основные методы:

• crm.deal.list — сделки с суммами, стадиями, датами и ответственными.
• crm.lead.list — лиды и их статусы.
• crm.contact.list и crm.company.list — контакты и компании.
• crm.item.list — универсальный метод для сделок, счетов и смарт-процессов (передаётся entityTypeId).
• crm.activity.list — дела, звонки и задачи по элементам; статистику телефонии отдаёт voximplant.statistic.get.

Доступ к API открывается двумя путями. Для внутренних задач проще всего входящий вебхук: Разработчикам → Другое → Входящий вебхук, где выдаётся URL с токеном и набором прав. Для тиражируемых приложений используется OAuth 2.0 с client_id и обновляемыми токенами.

Фильтры, поля, постраничность и batch

Чтобы выгрузка была точной и не тянула лишнее, list-методы принимают четыре ключевых параметра:

• filter — условия отбора. Поддерживаются префиксы операторов: >=DATE_CREATE, <=DATE_CREATE для периода, =STAGE_ID, %TITLE для поиска по подстроке.
• select — какие поля вернуть. Указывайте только нужные колонки; чтобы получить пользовательские поля, добавляйте их коды UF_CRM_* явно.
• order — сортировка результата, например по ID или дате.
• start — смещение постраничной выборки.

Важнейший нюанс — пагинация. Один вызов list-метода возвращает не больше 50 записей. Чтобы выгрузить всю базу, идёте циклом, увеличивая start на 50, пока в ответе есть данные. Для больших объёмов эффективнее так называемый быстрый метод: сортировка по ID по возрастанию, фильтр >ID по последнему полученному идентификатору и start=-1 — это снимает нагрузку на подсчёт общего количества.

Когда нужно объединить много запросов, применяют метод batch: до 50 команд за один вызов, с возможностью подставлять результат одной команды в параметры другой через выражение $result[...].

Регулярные выгрузки и интеграции

Разовый экспорт хорош для проверки гипотез, но настоящая ценность — в автоматическом обновлении данных. Типовые сценарии регулярной выгрузки:

1. Ночная синхронизация в хранилище. Скрипт по расписанию (cron) обходит crm.deal.list с фильтром по дате изменения и складывает изменившиеся сделки в свою БД или Google Sheets.
2. Реакция на событие. Вместо опроса подписываетесь на исходящие вебхуки событий — например ONCRMDEALUPDATE — и получаете уведомление в момент изменения сделки, а затем догружаете детали.
3. Дашборд во внешнем BI. BI-конструктор публикует источник, Power BI или Looker Studio обновляют отчёт по своему расписанию.

Для аналитики почти всегда фильтруют по дате изменения, а не создания: так в выгрузку попадают и старые сделки, у которых поменялась стадия или сумма. Инкрементальная выгрузка «только изменённое с прошлого запуска» экономит и лимиты API, и время.

Ограничения и типичные ошибки

API Битрикс24 не безлимитно, и это стоит закладывать в архитектуру выгрузки заранее:

• Частота запросов. Действует ограничение около 2 запросов в секунду на портал; при превышении приходит ошибка QUERY_LIMIT_EXCEEDED. Спасают batch и паузы между вызовами.
• Права токена. Вебхук отдаёт только те данные, на которые выданы права (scope crm) и которые видит его владелец — под ограниченной ролью часть сделок в выгрузку не попадёт.
• Пользовательские поля. Если не перечислить UF_CRM_* в select, их значения не вернутся, и в отчёте окажутся пустые колонки.

Частые ошибки на практике:

• Забыли про пагинацию и выгрузили только первые 50 записей, приняв их за всю базу.
• Фильтруют по дате создания и теряют движение по старым сделкам.
• Тянут все поля через пустой select, перегружая ответ и упираясь в лимиты.
• Держат токен вебхука в открытом коде — по сути это ключ ко всей CRM.

Итог

Выгрузка данных из Битрикс24 строится на трёх уровнях: ручной экспорт списков в Excel/CSV для разовых задач, BI-конструктор с коннекторами к Power BI, Looker Studio и DataLens для живой аналитики и REST API для интеграций. Ключевые технические детали — выборка методами crm.*.list с фильтрами и select, обязательная пагинация по 50 записей, объединение запросов через batch и учёт лимита в 2 запроса в секунду. А самое главное — сверять выгрузку с контрольными цифрами в интерфейсе.

Если нужно вывести данные CRM во внешний BI, настроить автоматическую выгрузку в хранилище или связать Битрикс24 с сайтом, 1С и учётными системами по API, мы в B2Bsite спроектируем интеграцию, настроим сквозную аналитику и обеспечим сопровождение решения.