# Битрикс24: как работает коннектор

В этой статье вы узнаете, как коннектор Битрикс24 выгружает данные в хранилище ROMI center: что именно попадает в таблицы, с какой периодичностью идёт выгрузка и как устроена перезапись прошлых дней. Полный список полей — в статье [Битрикс24: описание выгружаемых полей](https://help-ru.romi.center/bitrix24-opisanie-vygruzhaemyh-polej).

## Что попадает в таблицу: не карточки, а переходы по стадиям

Коннектор выгружает историю стадий портала. Одна строка таблицы — это момент, когда сделка, лид или элемент смарт-процесса попал на стадию. Дата этого перехода кладётся в колонку `event_date` — по ней строятся воронки и отчёты. Остальные поля (сумма, ответственный, источник, поля контакта и компании) добираются из карточки на момент выгрузки, то есть показывают её состояние тогда, когда коннектор забрал событие.

> **Важно**
> У одной сделки в таблице по строке на каждую стадию, куда она попадала. Если сделка вернулась на стадию, где уже была, добавится ли вторая строка — решает настройка «Учитывать повторные переходы в этап»: включена — каждый возврат даёт ещё одну строку со своей датой события; выключена — в таблице остаётся только первое попадание на эту стадию.

## Периодичность

Коннектор опрашивает портал каждые 30 минут (следующий прогон не стартует, пока идёт предыдущий) и заливает собранное в таблицы хранилища каждую минуту.

> **Примечание**
> Исходящий вебхук портала для хранилища не используется — он работает только для потоков офлайн-конверсий. Подключение к хранилищу коннектор пропускает и забирает данные опросом, поэтому задержка от события в CRM до строки в таблице — до получаса плюс время заливки, а не «в реальном времени».

## За какой период забираются данные

Обычный прогон берёт данные с момента прошлой успешной выгрузки по текущий момент. Первый прогон нового подключения — за последние 7 дней. Даты портала читаются в часовом поясе из настроек подключения — если он указан неверно, события съедут на несколько часов и могут попасть в соседние сутки.

## Как сохраняет данные

*   **Куда:** хранилище ROMI center на движке ClickHouse.
*   **Одна таблица на сущность.** Контакт и компания своих таблиц не создают: их поля приезжают колонками с префиксами `contact_` и `company_` в таблицы лидов и сделок.

| Суффикс таблицы | Что внутри |
| --- | --- |
| `_lead` | лиды |
| `_deal` | сделки |
| `_d<N>` | смарт-процесс с номером N |

Других сущностей у коннектора нет: счета, предложения и дела в хранилище не выгружаются.

*   **Имя таблицы:** `bitrix24_<поддомен портала>_<id подключения>_<суффикс>` — например `bitrix24_acme_1234_deal`.
*   **Структура таблицы:** движок `MergeTree`, сортировка по `rc_data_id`. В отличие от рекламных коннекторов разбиения на партиции по дате нет — события приходят вперемешку по датам, партиции по дню здесь ничего бы не ускорили.
*   **Структура догоняется, а не пересоздаётся.** Новое поле, выбранное в настройках, добавляется командой `ALTER TABLE … ADD COLUMN`. Колонки никогда не удаляются: если снять поле в настройках, колонка останется со старыми значениями, а новые строки будут писаться в неё пустыми.
*   **Повторная заливка того же события не плодит дубли.** У каждой строки есть `rc_data_id` — номер события в очереди ROMI. При повторной заливке строка с таким же `rc_data_id` удаляется и вставляется заново, а дата первой заливки (`rc_created_at`) переносится со старой строки.
*   **Одинаковые события отсеиваются ещё до таблицы:** если портал прислал событие, полностью совпадающее с уже сохранённым по тому же подключению и той же сущности, оно не сохраняется.

## Перезапись прошлых дней

Битрикс24 позволяет менять сделки задним числом, поэтому коннектор регулярно перечитывает недавние дни. Глубина ежедневной перезаписи — настройка «Перезагрузка прошлых дней»: 0, 1, 3 (по умолчанию), 7 или 14.

Автоматическая перезагрузка за выбранное число дней назад по вчерашний день включительно удаляет из всех таблиц подключения строки этих событий, перечитывает их у портала и заливает заново; дни за пределами окна не трогаются. Функция «Загрузить исторические данные» в меню подключения работает за любой период: данные догружаются, уже загруженные события не задваиваются.

> **Важно**
> Галочка «Удалить ранее загруженные данные за период» у Битрикс24 удаляет все таблицы подключения целиком и всю очередь его событий — не только выбранный период. После такой перезагрузки в таблицах останется только перезагруженный период, остальная история пропадёт. Ставьте галочку, только если готовы перезагрузить всю историю.

Кроме перезагрузки с галочкой удаления таблицы не удаляются и не пересоздаются: коннектор удаляет только строки тех событий, которые собирается перечитать.

## Дополнительные настройки

| Настройка | Что делает |
| --- | --- |
| Часовой пояс аккаунта | В нём читаются даты портала. Ставится один раз при настройке, менять его на живом подключении не стоит — старые строки пересчитаны не будут. |
| Перезагрузка прошлых дней (0 / 1 / 3 / 7 / 14) | Глубина ежедневной перезаписи. Больше дней — больше нагрузка на портал и дольше прогон. |
| Учитывать повторные переходы в этап | Включено — каждый возврат сделки на стадию даёт отдельную строку. Выключено — только первое попадание на стадию. |

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

## Технические поля

| Колонка | Что внутри |
| --- | --- |
| `rc_data_id` | Номер события в очереди ROMI. По нему строка обновляется и удаляется при перезагрузке. Заполнен всегда, проиндексирован. |
| `rc_created_at` | Когда строка впервые попала в таблицу. При перезаливке того же события сохраняется прежнее значение. |

Других служебных колонок у Битрикс24 нет: `rc_updated_at`, `rc_import_id` и `rc_datasource`, которые встречаются у рекламных коннекторов, здесь не создаются. Колонка `event_date` — не служебная: это дата самого события, она приходит из истории стадий портала.