# EnvyCRM: как работает коннектор В этой статье вы узнаете, как коннектор EnvyCRM выгружает сделки и лиды в хранилище ROMI center: какие таблицы он создаёт, как события попадают в хранилище и как устроена перезагрузка. Полный список полей — в статье [EnvyCRM: описание выгружаемых полей](https://help-ru.romi.center/envycrm-opisanie-vygruzhaemyh-polej). ## Что попадает в таблицы: события сделок и лидов Коннектор выгружает события EnvyCRM — появление сделки или лида и их переход в выбранный этап. На каждое событие пишется одна строка. | Сущность | Таблица | Откуда приходят события | | --- | --- | --- | | Сделки | `envy_<поддомен>__deal` | вебхук EnvyCRM и ночной опрос | | Лиды | `envy_<поддомен>__lead` | только вебхук | `<поддомен>` — первая часть домена аккаунта, дефисы заменены подчёркиваниями: у аккаунта `my-company.envycrm.com` таблица сделок называется `envy_my_company_12_deal`. * **Этапы выбираются обязательно.** События по невыбранным этапам в таблицу не попадают, а без единого выбранного этапа мастер дальше не пустит. Исключение — ночной опрос: у сделки, созданной в день перехода в выбранный этап, он добавляет и строку создания, даже если начальный этап не выбран. * В таблицу сделок можно добавить поля клиента — они приходят в той же строке. * Воронка и этап в строке — те, что были у события. Остальные поля — такие, какими коннектор увидел карточку, когда забирал её из EnvyCRM. ## Периодичность | Что происходит | Когда | | --- | --- | | Приём вебхука | сразу, как EnvyCRM прислал событие | | Ночной опрос сделок | каждую ночь, начиная с 02:00: задание за вчерашний день | | Автоперезагрузка сделок | ежедневно в 05:03, если «Перезагрузка прошлых дней» больше 0 | | Запись в таблицы | каждую минуту | | Проверка доступа к EnvyCRM | раз в 2 часа | Первая выгрузка ставится при сохранении подключения: по заданию на каждый из последних 30 дней по вчерашний. Задания ночного опроса не создаются, если истекла лицензия проекта, хранилище не настроено или недоступно, подключение на паузе или у него ошибка доступа. > **Важно** > Вебхук коннектор сам не настраивает. События приходят, только если отправка на адрес ROMI center (`/api/envy`) включена на стороне EnvyCRM. Без неё лидов не будет вовсе, а сделки придут только ночным опросом. > **Важно** > Вебхук сразу запрашивает карточку в EnvyCRM. Если API в этот момент не ответил — например, из-за лимита запросов, — событие не сохраняется: сделки вернёт перезагрузка, лиды — нет. > **Важно** > Ошибка доступа сама не снимается. Её ставит проверка раз в 2 часа, после чего ночные задания перестают создаваться. Снять её можно, пройдя подключение EnvyCRM заново с тем же ключом — мастер найдёт существующее подключение. С новым ключом получится новое подключение со своими таблицами. > **Примечание** > Пауза останавливает ночные задания и приём вебхуков, но не автоперезагрузку: та и на паузе удаляет и заново собирает сделки за последние N дней. Вебхуки, пришедшие на паузе, не сохраняются: сделки за этот период можно вернуть перезагрузкой после снятия паузы, лиды — нет. ## За какой период забираются данные | Случай | Период | | --- | --- | | Вебхук | одно событие; временем события считается момент приёма | | Ночной опрос | вчерашний день: сделки, перешедшие в выбранные этапы; если сделка в тот же день и создана, добавляется строка её создания | | Первая выгрузка | последние 30 дней по вчерашний, по заданию на день | | Автоперезагрузка | последние N дней по вчерашний (N — настройка «Перезагрузка прошлых дней») | | Ручная перезагрузка | любой период, включая сегодня | Дни опроса и перезагрузок считаются по московскому времени: время из журнала этапов EnvyCRM коннектор читает как московское. ## Как сохраняет данные * **Куда:** хранилище ROMI center на движке ClickHouse. * **Структура таблицы:** движок `MergeTree`, сортировка по `rc_data_id`, без партиций. * **Колонки добавляются на ходу.** Поле, отмеченное позже, появится колонкой при очередной записи. Колонки не удаляются: снятое поле остаётся колонкой и дальше заполняется пустыми значениями. * **Повторная запись того же события не плодит дубли:** строка с тем же `rc_data_id` заменяется, а дата первой записи `rc_created_at` сохраняется. * **Удаление подключения удаляет обе таблицы** из хранилища. > **Важно** > Повтором считается событие с теми же значениями всех выбранных полей. Если такое уже принято, новое не попадёт в таблицу; этап и воронка события в сравнении не участвуют. Поэтому держите среди выбранных полей этап и дату его смены: без них переходы одной сделки по разным этапам склеятся в одну строку, а без ID — ещё и разные сделки с одинаковыми значениями. Возврат сделки на тот же этап с неизменными полями новой строки не даст. > **Важно** > Одна смена этапа может записаться дважды — вебхуком и ночным опросом, если у этих двух записей разойдутся значения выбранных полей: опрос берёт карточку такой, какой она стала к ночи. Например, у сделки, которая за день сменила несколько этапов, «Дата и время обновления этапа» к ночи уже другая, и ранние смены при заранее отмеченных полях попадут в таблицу дважды. > **Важно** > Опрос зависает на больших днях. Сделки и журнал этапов EnvyCRM отдаёт страницами по 50, а коннектор при догрузке каждый раз запрашивает первую страницу. Если за день в выбранные этапы перешло 50 сделок и больше или у сделки в журнале 50 записей и больше, задание за этот день не завершится. Если у вас такие объёмы, обратитесь в поддержку. > **Важно** > При истёкшей лицензии события теряются. Вебхук их по-прежнему принимает, но при записи они помечаются ошибкой «License expired» и после продления не дозаписываются. Сделки за этот период можно вернуть перезагрузкой, лиды — нет. ## Перезапись прошлых дней Перезагружаются только сделки: лиды приходят лишь вебхуком, и заново их взять неоткуда. | Перезагрузка | Что делает | | --- | --- | | Автоматическая, в 05:03 | Работает при «Перезагрузке прошлых дней» от 1 до 30, если лицензия действует и у подключения нет ошибки доступа. Из таблицы сделок удаляются строки за последние N дней по вчерашний, и сделки за эти дни собираются заново | | «Загрузить исторические данные» | Любой период, включая сегодня. Сделки собираются заново по дню; уже принятые события не задваиваются, если значения выбранных полей с тех пор не изменились | | Она же с галочкой «Удалить ранее загруженные данные за период» | Удаляется вся таблица сделок — не только выбранный период. После перезагрузки в таблице останутся только сделки этого периода. Таблица лидов не трогается | Удаление идёт после постановки заданий в очередь: если подключение на паузе, задания не создаются, перезагрузка завершается ошибкой, а данные остаются на месте. ## Дополнительные настройки | Настройка | Что делает | | --- | --- | | API-ключ | Шаг «Доступ»: ключ пользователя из настроек EnvyCRM, мастер сразу проверяет его запросом к API. У пользователя должны быть права администратора. Домен и часовой пояс аккаунта подтягиваются из EnvyCRM сами; пояс — только при создании подключения, позже он не обновляется | | Таблицы, поля и этапы | Шаг «Выбор полей»: две таблицы — сделки и лиды. Для каждой выбираются поля и этапы воронок; основные поля отмечены заранее | | Перезагрузка прошлых дней | Шаг «Дополнительные настройки»: от 0 до 30 дней, по умолчанию 0 — автоперезагрузка выключена | | Приостановить выгрузку | Останавливает ночные задания и приём вебхуков; уже созданные задания доработают. Автоперезагрузку пауза не останавливает | * **Имя колонки** собирается из подписи поля транслитом, скобка в конце подписи отбрасывается: «Дата и время создания» → `data_i_vremya_sozdaniya`. У уже сохранённых полей имя при редактировании не меняется. * Повторное подключение с тем же ключом в том же проекте и хранилище второго подключения не создаёт: мастер продолжит настройку существующего. * Изменения полей и этапов действуют для новых событий. Уже записанные строки не пересчитываются. ## Технические поля | Колонка | Что внутри | | --- | --- | | `rc_data_id` | Номер события в промежуточной очереди ROMI. По нему строка заменяется при повторной записи | | `rc_event_time_utc` | Время события в UTC: у вебхука — момент приёма, у опроса — время смены этапа из журнала EnvyCRM, у строки создания — время создания сделки | | `rc_event_date_msk` | Дата события по Москве. По ней автоперезагрузка удаляет строки | | `rc_created_at` | Когда строка впервые записана в хранилище, по Москве. При повторной записи сохраняется | В «Просмотре данных» служебные колонки скрыты, в самой таблице они есть.