Внедрение и настройка Битрикс24

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

Сайт, 1С и внешние сервисы создают события: новая заявка, проведённая оплата, изменение заказа.

Проверяет формат, сохраняет событие, сопоставляет записи и ставит операцию в очередь.

Получает контакт, сделку или задачу через API. Результат возвращается в журнал обмена.

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

До разработки фиксируем владельца каждого поля. Если телефон редактируется в CRM, а сумма оплаты рассчитывается в 1С, обратный обмен не должен безусловно перезаписывать эти значения. Для защиты от циклов учитываем источник изменения и сравниваем фактические данные перед обновлением.

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

1. Принять и зарегистрировать

   Сохраняем обращение до обращения к CRM. Пользователю можно подтвердить получение заявки, отдельно отслеживая её доставку в Битрикс24.

2. Найти клиента

   Нормализуем телефон и email, ищем связанные контакты. Несколько совпадений — повод применить согласованное правило или передать случай на проверку.

3. Создать продажу

   В зависимости от режима CRM создаём лид либо контакт и сделку. Указываем воронку, ответственного, источник и обязательные поля портала.

4. Зафиксировать результат

   Сохраняем ID созданных объектов. При сбое следующего шага продолжаем с последней подтверждённой операции.

Идентификаторы и значения в примере условные.

Поиск по телефону или email помогает найти клиента, но сам по себе не защищает от повторного создания сделки. Для этого нужен отдельный учёт событий и связанных CRM-объектов. Политику объединения контактов согласуем отдельно: автоматическое слияние может затронуть историю продаж.

Источником сведений об оплате выступает учётная система. В CRM передаётся результат согласованного учётного события, например проведения платёжного документа. Сначала интеграция находит нужный заказ и сделку по сохранённой связи, затем обновляет суммы и признаки оплаты.

250 000 ₽ — согласованная сумма заказа.

100 000 ₽ — подтверждённая частичная оплата.

150 000 ₽ — остаток по этому примеру.

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

После успешного обновления сохраняем подтверждение CRM. Если связь со сделкой не найдена, событие остаётся доступным для повторной обработки после исправления сопоставления. Не создаём новую сделку только потому, что платёж не удалось привязать автоматически.

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

1. Проверить готовность

   Проверяем стадию, оплату и обязательные данные. Неполный заказ возвращается ответственному с понятным перечнем недостающих сведений.

2. Проверить предыдущий запуск

   Ищем сохранённую связь сделки и задачи. Повторное событие не должно создавать второй проект.

3. Передать в работу

   Создаём задачу или используем согласованный механизм проекта. Назначаем ответственного и передаём ссылку на сделку.

4. Вернуть статус

   Сохраняем ID задачи. Обратные статусы обновляем по отдельным правилам: закрытие одной задачи не всегда означает завершение заказа.

Идентификаторы и значения в примере условные.

В этом примере создаётся задача с привязкой к сделке. Для реального портала нужно подставить существующего пользователя и учесть обязательные пользовательские поля. Сроки, наблюдателей, чек-листы и состав работ определяем по процессу компании, а не назначаем одинаково для всех заказов.

Карта обмена описывает не только названия полей, но и их смысл: кто хранит исходное значение, какие изменения разрешены и как отличить отсутствие данных от намеренного очищения поля. Это основной рабочий документ для разработки и приёмки.

Для обновлений отдельно определяем поведение пустых значений. Отсутствующее поле обычно означает «не менять», а явно переданное пустое значение может означать «очистить» — если это разрешено для данного поля. Это соглашение проверяется для каждого используемого метода API.

Список доступных полей и их характеристики получаем для нужного типа CRM-элемента. Обязательные поля могут зависеть от настроек портала и стадии. После изменений конфигурации карту обмена пересматриваем и проверяем на тестовых сценариях.

Запросы к Битрикс24 выполняет сервер интеграции. В браузере посетителя не должно быть секретного URL вебхука или OAuth-токена. Способ подключения выбираем с учётом числа порталов, необходимых событий и жизненного цикла доступа.

Идентификаторы и значения в примере условные.

Метод crm.item.add создаёт CRM-элемент; значение entityTypeId: 2 в примере соответствует сделке. Это пример структуры параметров, а не универсальный готовый запрос: конкретному порталу могут требоваться дополнительные поля и права. Создание элемента также может запускать настроенную автоматизацию, поэтому проверяем роботов и бизнес-процессы.

Обработчик сохраняет результат запроса и идентификатор созданной сущности. Ошибку анализируем по ответу метода, а не только по HTTP-статусу. Перед запуском проверяем доступность нужных возможностей на конкретном портале и разделяем тестовые и рабочие настройки.

Очередь отделяет приём события от его доставки в CRM. Если внешний сервис временно недоступен, принятое событие остаётся в хранилище и может быть обработано позже. Для связанных изменений сохраняем порядок там, где он влияет на результат, например при обновлении одного заказа.

1. Принято → ожидает

   Событие сохранено вместе с источником, ID, временем и полезной нагрузкой.

2. В обработке → выполнено

   Рабочий процесс проверяет связи, вызывает API и записывает подтверждённый результат.

3. Временная ошибка → повтор

   Следующая попытка назначается с увеличением задержки и небольшим случайным разбросом.

4. Требует разбора → исправлено

   После исчерпания попыток или ошибки данных операция попадает в отдельный список для оператора.

Самый сложный случай — потеря ответа после успешного создания записи. Сервер не знает, создалась ли сделка, поэтому слепой повтор может дать дубль. Перед повтором нужна сверка по сохранённым связям или согласованному внешнему ключу. Если результат нельзя установить автоматически, операция требует разбора.

Число попыток, максимальное время ожидания и условия оповещения задаём отдельно для каждого процесса. Ограничения REST API учитываем в скорости обработки очереди; точные значения проверяем по актуальной документации и условиям портала.

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

Контролируем не только количество ошибок, но и возраст самого старого события, размер очереди и время доставки. Даже при отсутствии явных сбоев растущая очередь может означать, что обновления приходят слишком поздно для бизнеса.

Оператору нужен безопасный повтор конкретной операции после исправления причины. Повтор регистрируется в истории с указанием инициатора. Чувствительные данные в диагностике маскируются; полная полезная нагрузка доступна только там, где это оправдано задачей и настройками доступа.

Интеграции выдаются только необходимые права. Учётная запись с полным административным доступом не должна быть вариантом по умолчанию. Проверяем отдельно возможность читать CRM, создавать нужные сущности, работать с задачами и получать используемые события.

Секреты храним в защищённой серверной конфигурации и исключаем из логов, репозитория и клиентских файлов. Для входящих сообщений проверяем подлинность способом, поддерживаемым конкретным источником; одного наличия URL обработчика недостаточно.

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

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

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

Карта полей, связи сущностей, порядок мониторинга, повторов и восстановления доступа.

Протокол сценариев, известные ограничения и распределение ответственности за сопровождение.

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

Демонстрация на странице помогает увидеть логику процесса: от заявки к сделке, от оплаты к изменению состояния и от готового заказа к исполнению. Это учебная модель с условными данными; она не подтверждает подключение к вашему порталу или конкретной базе 1С.

Чтобы перейти от примера к проекту, описываем один реальный процесс, источники данных и ожидаемый результат. Затем проверяем ограничения систем, выбираем способ подключения и согласуем критерии приёмки. Это позволяет оценивать интеграцию по наблюдаемому результату, а не только по наличию запроса к API.