Интеграции / РУКОВОДСТВО
Интеграция Битрикс24: что проверить до разработки
Подготовите карту полей и протокол проверки доставки, дублей и восстановления.
Рабочий инструментКарта интеграции и протокол приёмкиПерейти к шаблону ↓

В ЭТОМ МАТЕРИАЛЕ
В этом материале +
Надёжная интеграция начинается с правил владения данными. Определите, где создаётся сущность, как она узнаётся в другой системе и что происходит при повторе, конфликте или недоступности API. Успешный HTTP-ответ сам по себе ещё не означает корректную сделку.
Одна сущность — понятный источник правды
Заявка с сайта, контакт в Битрикс24 и контрагент в 1С не являются взаимозаменяемыми объектами. Опишите их соответствие: какие поля обязательны, какие идентификаторы связывают записи, кто может менять телефон, сумму и статус. Контракт нужен даже для «простой» передачи формы в CRM.
Для каждого поля назначьте источник. Например, CRM хранит этап переговоров, учётная система — подтверждённый платёж, а сайт — исходный текст обращения. Если обе системы могут изменять значение, потребуется правило конфликта. Синхронизация по последнему времени изменения не всегда соответствует бизнес-смыслу.
Повтор события не должен создавать повторную сделку
Для маршрута нужен устойчивый идентификатор операции и сохранённый результат. Повторная отправка с сайта или ручное восстановление не должны создавать дубль. Отдельно проверьте потерю события: Bitrix24 не повторяет онлайн-событие при ошибке обработчика. Восстановление проектируют через доступные механизмы, например offline events или сверку с источником.
Не скрывайте очередь ошибок. Ответственный должен видеть, какая заявка не дошла, почему и что нужно исправить. Проверяйте ограничения конкретного портала, доступность методов API и выданные права до согласования схемы: возможности облачной и коробочной установки и используемый тариф могут различаться.
На примере нашей формы: принято, доставлено и взято в работу
На нашем сайте сервер сначала сохраняет обращение и выдаёт его номер. Если связь оборвалась до подтверждения, браузер повторяет отправку с тем же идентификатором. Сервер находит уже сохранённое обращение: второй заявки не появляется. Затем отдельная задача отвечает за доставку уведомления. По этому примеру удобно разделять приём данных и дальнейшую работу с ними.
После приёма отдельный обработчик доставляет уведомление в настроенные каналы. Он хранит состояния каналов и повторяет неудачную попытку; исчерпанная серия попыток остаётся видимой ошибкой. Успешная доставка в Telegram не подтверждает создание записи в CRM, а ни одно из этих событий не доказывает, что менеджер прочитал сообщение или связался с человеком.
На приёмке вашей интеграции разберите ту же ситуацию: запись уже сохранилась, но связь оборвалась до подтверждения. По какому ключу найдётся результат? Как сотрудник отличит очередь от доставки и узнает об окончательной ошибке? Проверяйте ответ исходной системы и состояние каждого получателя отдельно. Один зелёный ответ API не должен подменять весь маршрут.
- Приём: есть сохранённое обращение и устойчивый идентификатор; повтор той же операции находит его.
- Доставка: для каждого согласованного канала видно подтверждение либо ошибка и порядок восстановления.
- Работа сотрудника: назначен ответственный и зафиксировано его действие. Это следующий этап, который проверяют отдельно.
Технический контракт для проверки с разработчиком
При первой успешной записи наш API возвращает HTTP 202 и accepted=true. Повтор с тем же submissionId получает HTTP 200 и duplicate=true. Эти признаки подтверждают сохранение, а статусы доставки проверяются отдельно. Это контракт формы IT WHITE; внедрение такого же поведения в другой системе требует отдельной проверки.
Пять проверок перед приёмкой интеграции
Проверяйте один и тот же маршрут на тестовых данных с известным результатом. Для каждого испытания сохраните идентификатор операции, ожидаемое состояние CRM и запись журнала. Следующий список — сценарий приёмки, а не утверждение о проверке вашей системы.
У каждой ошибки должен быть понятный владелец и способ восстановления. Если подтверждение потерялось, сначала выясните, была ли операция выполнена; повтор без сверки может создать второй документ или повторное уведомление.
- Повтор: дважды передайте одно обращение с тем же идентификатором. Проверьте одну CRM-запись и отсутствие повторного побочного действия.
- Временный отказ: сделайте CRM недоступной в тестовом контуре. Исходное обращение должно сохраниться, ошибка — стать видимой, а повтор после восстановления — завершить ту же операцию.
- Потеря подтверждения: смоделируйте выполненную запись без полученного ответа. Сверка должна найти результат до новой попытки создания.
- Конфликт поля: измените значение в системе-владельце до обработки старого события. Устаревшее событие не должно молча вернуть старые данные.
- Недостаточные права: отзовите необходимое разрешение. Обработчик должен показать диагностируемую ошибку, сохранив данные для восстановления, и не расширять себе доступ.
Telegram — рабочий канал, CRM — история процесса
Сообщение в Telegram помогает быстро заметить событие. Но передача карточки в чат не подтверждает реакцию менеджера. Для контроля нужен переход к CRM и событие действия: назначение ответственного, ответ клиенту или новый следующий шаг.
Не отправляйте в общий чат лишние персональные данные. Разделите оперативные уведомления и управленческие отчёты по получателям. Опишите, как сотрудник прекращает получать уведомления после смены роли и где остаётся история решения.
Приёмка на неудобных примерах
Проверьте новую заявку, повторную отправку, отсутствующее обязательное поле, смену ответственного и временное отключение CRM. Повторите событие после восстановления и убедитесь, что запись появилась ровно один раз, а исходные данные сохранились.
Сверяйте результат в обеих системах по идентификаторам. Скриншот успешного запроса не проверяет маппинг полей, права и дальнейшую работу менеджера. В передаче проекта должны быть схема сущностей, перечень доступов, журнал ошибок и инструкция по восстановлению.
ПРИМЕНИТЬ К СВОЕЙ ЗАДАЧЕ
Карта интеграции и протокол приёмки
Владельцы полей, повторная обработка, сбои и подтверждение доставки. Есть заполненный пример и таблица для своей интеграции.
- Поле и его владелец
- Источник каждого значения и правило разрешения расхождений.
- Повтор и сбой
- Как найти исходную операцию и безопасно повторить её.
- Доставка подтверждена
- Результат проверяется в CRM, а ошибка остаётся доступна ответственному.
Заполненный пример: одна заявка отправлена повторно
Условный пример для обсуждения, не клиентский кейс.
- Вход
- Сайт повторяет ранее принятую заявку с тем же идентификатором.
- Проверка
- Обработчик находит связь с существующей CRM-записью.
- Результат
- Повтор не создаёт вторую карточку; статус и данные сверяются с CRM.
Не рассчитывайте на повторную доставку онлайн-события со стороны Bitrix24. Механизм восстановления и сверки согласуется для конкретного маршрута.
Без регистрации. PDF — для чтения, Word — для заполнения. Исходник Markdown ↓
Что подготовить к обсуждению
- Облачная или коробочная версия и доступные методы
- Примеры заявок, сделок и учётных документов
- Правила дублей и владения полями
- Список получателей уведомлений и ответственный за ошибки
Источники и основания
Источники объясняют, как устроена технология. Подойдёт ли она вам, что потребуется для запуска и окупятся ли затраты — проверяем на данных вашей компании.
- IT WHITE: собственная форма обращения — пример приёма и повторной отправки
- IT WHITE: внедрение маршрута Avito, Telegram и Bitrix24 для PUSHMINER — устройство и границы результата
- Битрикс24: справочник REST API CRM
- Битрикс24: события, ограничения доставки и восстановление
- OpenTelemetry: наблюдаемость интеграций