# Своя CRM: как работает коннектор

В этой статье вы узнаете, как коннектор «Своя CRM» принимает события из вашей системы — CRM, личного кабинета, биллинга — в хранилище ROMI center: как отправлять запросы на вебхук, как события попадают в таблицу и что настраивается в мастере. Типы полей и правила записи значений — в статье [Своя CRM: описание выгружаемых полей](https://help-ru.romi.center/svoya-crm-opisanie-vygruzhaemyh-polej).

## Что выгружается: одна таблица, строка на каждое событие

Коннектор ничего не запрашивает сам: ваша система отправляет запрос на вебхук ROMI center, и каждый запрос становится строкой таблицы. Поля и их типы вы задаёте в мастере.

| Что присылает ваша система | Что в таблице |
| --- | --- |
| Один запрос на вебхук | Строка |
| Ключ верхнего уровня JSON, заданный в настройках | Колонка |
| Ключи, которых нет в настройках | Не попадают в таблицу |

Имя таблицы — `customcrm_<название подключения транслитом>_<id подключения>`, например `customcrm_billing_12`. У подключений, созданных до 30.06.2025, имя другое: `custom_db_data_<токен>`.

*   **Один запрос — одно событие.** Массив событий в одном запросе не разбирается: настроенных ключей верхнего уровня в нём нет, и присланные данные в таблицу не попадут.
*   **Берутся только ключи верхнего уровня.** Вложенный объект целиком пишется в текстовую колонку строкой JSON; достать поле изнутри него нельзя.
*   **Перезагрузки нет.** В таблице только то, что прислала ваша система: повторить события можно лишь повторной отправкой с вашей стороны.

## Приём и отправка

| Что происходит | Когда |
| --- | --- |
| Приём вебхука | сразу: событие сохраняется в промежуточный буфер ROMI |
| Запись в таблицу | раз в 2 минуты |
| Повтор событий с ошибкой записи | раз в 30 минут, до 5 повторов на событие |

Обычно событие оказывается в таблице в течение нескольких минут после приёма.

**Адрес вебхука и токен** показаны в мастере на шаге «Доступ». Токен можно передать в адресе (`?token=…`, так он уже вставлен в показанный URL) или полем `token` в теле запроса. Поля данных — в теле, JSON или обычной формой, либо параметрами адреса.

> **Важно**
> JSON разбирается только с заголовком вида `Content-Type: application/json` — без него поля не прочитаются, и присланные значения в таблицу не попадут.

Ответ вебхука выглядит так: `{"status": "ok", "matched_statuses": N, "created_rows": […]}`.

> **Важно**
> При неверном токене или удалённом подключении ответ тоже `status: ok`, только `matched_statuses: 0`, и ничего не сохраняется — проверяйте это число. Запрос без `token` получает ошибку 400.

> **Важно**
> Запрос больше 64 КБ не сохраняется: на больший запрос вебхук ответит ошибкой 500. Учтите, что буква кириллицы занимает 2 байта.

> **Примечание**
> Пауза не теряет события: вебхук принимает их в буфер, а в таблицу они уйдут после снятия паузы.

> **Важно**
> Если хранилище недоступно, события помечаются ошибкой и повторяются раз в 30 минут. После пяти неудачных повторов — примерно через два с половиной часа — они больше не отправляются.

> **Примечание**
> Истёкшая лицензия запись не останавливает, а только задерживает: событие записывается позже, чем обычно, — иногда через десятки минут.

## Что попадает в таблицу

*   **Каждое событие — отдельная строка.** Ключ строки `rc_data_id` — номер события в буфере ROMI, поэтому одинаковый `id` в присланных данных строки не затирает. До 23.07.2026 ключом был присланный `id`, и событие с тем же `id` стирало предыдущее.
*   **Событие без единого настроенного поля** в таблицу не пишется. Исключение — подключения с полем `event_date`: у них такое событие запишется строкой, где заполнено только это поле.

> **Важно**
> Повторы отсеиваются по содержимому. Событие, у которого значения всех настроенных полей совпадают с более ранним, в таблицу не попадает. Сравнение идёт с событиями подключения за последние полгода. Поэтому держите среди полей идентификатор события или время: иначе, например, два одинаковых платежа одного клиента склеятся в одну строку.

> **Важно**
> Тестовые события, отправленные до сохранения мастера, пропадают: запись раз в 2 минуты застаёт подключение ещё без полей. Отправляйте тестовые запросы после сохранения настроек.

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

*   **Куда:** хранилище ROMI center на движке ClickHouse.
*   **Структура таблицы:** движок `MergeTree`, сортировка по `rc_data_id`, без партиций. У старых таблиц структура может отличаться.
*   **Колонки добавляются на ходу.** Новое поле из настроек появится колонкой при очередной записи и заполнится только у новых событий — уже записанные не пересчитываются. Колонки не удаляются: снятое поле остаётся колонкой и дальше заполняется пустыми значениями. Смена типа у сохранённого поля колонку не меняет: значения приводятся по новому типу, а тип колонки остаётся прежним.
*   **Имя колонки** — ключ из вебхука транслитом: «Почта» → `pochta`, `client_email` → `client_email`. У подключений, созданных до нового мастера, колонкой служит сам ключ без транслита. У сохранённых полей имя при редактировании не меняется, а другой ключ — это новое поле и новая колонка.
*   **Удаление подключения удаляет и таблицу** из хранилища.

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

| Шаг мастера | Что задаётся |
| --- | --- |
| «Доступ» | Название источника — из него собирается имя таблицы — и готовые токен и URL вебхука. Токен и URL при редактировании не меняются |
| «Выбор полей» | Поля по одному: «Имя поля (как в вебхуке)» — ключ JSON, «Название в ROMI center» и тип. Нужно хотя бы одно поле |
| «Дополнительные настройки» | «Часовой пояс вашей CRM», по умолчанию Москва — см. [описание полей](https://help-ru.romi.center/svoya-crm-opisanie-vygruzhaemyh-polej) |
| Приостановить выгрузку | События копятся в буфере и уходят в таблицу после снятия паузы |

> **Важно**
> Название источника поменять можно, но у подключений, созданных после 30.06.2025, запись тогда пойдёт в новую таблицу: прежняя останется с накопленными данными и при удалении подключения уже не удалится.

«Название в ROMI center» хранится только в настройках: в «Просмотре данных» подписью колонки служит ключ из вебхука.

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

| Колонка | Что внутри |
| --- | --- |
| `rc_data_id` | Номер события в буфере ROMI. У таблиц, созданных до 23.07.2026, — присланный `id`, если он был |
| `rc_created_at` | Когда строка впервые записана в хранилище, по Москве |

**Поле, чья колонка называется `event_date`, особенное.** В него пишется не присланное значение, а момент приёма события вебхуком по Москве; у типов «Дата» и «Дата и время» он ещё и сдвинут на пояс подключения. Оно заполняется у каждого события, даже если ключа нет в запросе. В подключениях из старой формы такое поле обычно есть и чаще всего открывается в мастере как «Текст»: время в нём московское, без сдвига. При отсеве повторов сравнивается присланное значение этого ключа, а не время приёма.

В «Просмотре данных» служебные колонки скрыты, в самой таблице они есть.