Структура данных Битрикс24: REST API, BI-наборы и связи CRM

Обновлено 3 сентября 2026 года.

У Битрикс24 нет одной универсальной схемы, которая одновременно описывает REST API, таблицы BI Конструктора, внутреннюю базу коробочной версии и выгрузку стороннего коннектора. В аналитике сначала нужно определить, с каким из этих представлений вы работаете, а затем проверить поля, ключи и детализацию.

В прежней версии статьи эти уровни были смешаны. Приложенная диаграмма содержит таблицы bitrix24_deals, bitrix24_deals_facts, general_dates и другие элементы аналитической модели. Это не ER-диаграмма физических таблиц b_crm_* работающего портала.

Чем отличаются представления данных

Представление	Пример	Где уточнять структуру
REST API CRM	Объект сделки с id, title, assignedById	Описание метода и метаданные полей конкретного портала
Наборы BI Конструктора	crm_deal, crm_deal_uf, crm_deal_product_row	Справка набора, его доступные столбцы и фактический результат запроса
Внутренняя база коробки	Таблицы модулей установленной версии	Фактическая схема и код этой инсталляции
Выгрузка коннектора или хранилище	Таблицы и названия полей, заданные разработчиком выгрузки	Контракт коннектора, преобразования и проверочная выгрузка

Тип API crm_contact, признак isMultiple или разрешение на запись поля не являются SQL-типами и ограничениями физического столбца. И наоборот: наличие числового ID в таблице не доказывает, что в базе объявлен внешний ключ. Описание полей объектов CRM; Каталог BI-наборов.

Основные сущности и связи

Сделка — работа по продаже: сумма, валюта, стадия, направление, ответственный и другие атрибуты.
Контакт и компания — отдельные объекты CRM. У сделки могут быть привязки к клиентам; не сводите все связи к одному столбцу «клиент» без проверки.
Пользователь может участвовать в разных ролях: ответственный, создатель или последний редактор. Это разные связи с одной сущностью.
Товарная позиция описывает строку товара или услуги в конкретной продаже. Она отличается от карточки товара в каталоге.
История стадий содержит события движения сделки. У одной сделки может быть несколько записей истории, включая повторные переходы.
Пользовательские и множественные поля требуют проверки типа и количества значений; их нельзя всегда трактовать как один текстовый столбец.

В универсальном REST API поля assignedById, createdBy и updatedBy обозначают разных участников. contactIds — список контактов у поддерживающих его объектов. Соединение со справочником сотрудников нужно строить по той роли, которую вы анализируете. Системные поля и связи.

Читай также: Аналитика данных, BI и статистика: практическое введение

Как получить поля своего портала через API

Для подготовки запросов доступны конструктор вебхуков Битрикс24 и конструктор batch-запросов.

Метод crm.item.fields возвращает поля и их конфигурацию для заданного типа объекта. Для сделки используется entityTypeId = 2. Пример тела запроса:

{
  "entityTypeId": 2,
  "useOriginalUfNames": "Y"
}

Запрос выполняется к методу crm.item.fields вашего портала с действующей авторизацией. Значение Y сохраняет исходные имена пользовательских полей вроде UF_CRM_...; при N возвращаются имена в camelCase. Сохраните ответ вместе с датой, типом объекта и версией интеграции. Параметры и ответ crm.item.fields.

Проверьте название, тип, обязательность, доступность записи и признак множественности. Затем сравните метаданные с несколькими реальными ответами чтения: пустым полем, заполненным полем и полем с несколькими значениями. Статический PDF не может заранее содержать все пользовательские поля каждого портала.

Телефоны и email — не обязательно один столбец

Контакт может иметь несколько телефонов или адресов email с разными типами значений. В REST они представлены мультиполями; конкретная структура зависит от используемого метода. Поэтому описание «телефон хранится в столбце таблицы контактов» недостаточно для реализации выгрузки. Метаданные полей контакта.

В своей аналитической модели можно хранить значения отдельно: ключ контакта, тип контакта связи, вид значения и само значение. Перед соединением такой таблицы со сделками решите, нужен ли один приоритетный телефон, список телефонов или отдельные строки. Иначе одна сделка размножится по числу контактных значений.

Наборы данных сделок в BI Конструкторе

Набор	Содержание	Что проверить при объединении
crm_deal	Системные поля сделки	Уникальность ID и выбранный срез данных
crm_deal_uf	Пользовательские поля сделки	Связь по DEAL_ID и фактические типы пользовательских полей
crm_deal_stage_history	История движения по стадиям	Несколько событий на одну сделку
crm_deal_product_row	Товары и услуги в сделке	Несколько товарных строк на одну сделку

Это имена аналитических наборов, а не инструкция добавить префикс b_ и выполнить SQL к базе коробки. Доступность BI Конструктора зависит от тарифа. Состав наборов сделок.

Отдельно проверьте смысл дат и денежных полей. В описании crm_deal поле CLOSEDATE — планируемая дата закрытия. Не используйте его без проверки как дату оплаты или единственное доказательство фактического завершения. Стадия успеха, выставленный счёт, оплата и признанная выручка — разные события.

Пример ошибки JOIN: 3000 превращаются в 4000

Учебные сделки: ID 101 на сумму 1000 RUB и ID 102 на сумму 2000 RUB. У первой сделки две товарные строки, у второй — одна.

Читай также: AI-автоматизация для стартапа: пять схем процессов и проверка результата

Сделка	Товарная строка	Сумма сделки после JOIN
101	1	1000
101	2	1000
102	3	2000

Сумма сделок до объединения — 3000. Сумма столбца после JOIN — 4000, потому что сумма сделки 101 повторилась. SUM(DISTINCT amount) не является общим исправлением: две разные сделки с одинаковой суммой тоже должны учитываться обе.

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

Как читать старую диаграмму

Открыть архивную диаграмму аналитической модели. На ней есть сущности bitrix24_*, таблицы фактов *_facts и общие справочники general_*. Её можно использовать для обсуждения построения хранилища, но не как подтверждение состава физической базы текущего Битрикс24.

На схеме также встречается account_id. При объединении нескольких порталов недостаточно одного ID: добавляйте идентификатор портала, а для общей таблицы разных сущностей — ещё и тип объекта. Сделка 101 и контакт 101 не являются одним объектом.

Проверка схемы перед построением отчёта

Зафиксируйте способ доступа: REST, BI-набор, коробочная база или конкретный коннектор.
Для каждой таблицы опишите, что означает одна строка и какой ключ должен быть уникальным.
Сверьте типы ID, валют, дат и множественных полей на фактических данных.
Перед JOIN и после него сравните число строк, число уникальных сделок и сумму в одной валюте.
Проверьте пропуски связей, удалённые элементы и неполную выгрузку из-за прав доступа.
Для истории определите, анализируете ли вы текущее состояние или состояние на дату.
Изменяйте данные CRM через поддерживаемый API или штатные инструменты; схема аналитики не является инструкцией прямой записи в служебные таблицы.

Скачать исправленный справочник по структуре данных CRM, редакция от 3 сентября 2026 года. Он объясняет уровни данных, ключи и контроль объединений. Полный актуальный список полей конкретного портала нужно получать из его метаданных.