ТЗ на интеграцию сайта с CRM: готовая структура

Если вы готовите сайт, интернет-магазин или обновление CRM, сохраните этот материал как рабочий чек-лист. За уточнением архитектуры можно обратиться к команде ИРС.

Что должно определить ТЗ на интеграцию сайта с CRM?

Коротко: ТЗ должно однозначно отвечать на пять вопросов: какие события запускают обмен, какие данные передаются, где хранится эталонная запись, что считать дублем и как система ведёт себя при ошибке. Названия двух систем и фразы «настроить интеграцию» для оценки и приёмки недостаточно.

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

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

Какие события сайта нужно включить в интеграцию?

Коротко: В ТЗ перечисляют не страницы, а бизнес-события. Для каждого события указывают источник, условие срабатывания, создаваемые сущности CRM, ответственного и ожидаемый срок обработки. Такой список показывает реальный объём работы до оценки проекта.

Начните с инвентаризации всех точек обращения:

Отправка формы обратной связи.
Заказ обратного звонка.
Оформление и оплата заказа.
Регистрация личного кабинета.
Сообщение из чата или mini-app.
Звонок через систему коллтрекинга.
Повторное обращение существующего клиента.

Не объединяйте события с разной логикой в строку «заявка с сайта». Заказ с составом корзины и короткая форма с телефоном требуют разных полей, проверок и реакции CRM.

Какие поля передавать из сайта в CRM?

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

Используйте таблицу как основу приложения к ТЗ:

Поле сайта	Поле CRM	Обязательность	Правило
Имя	Имя контакта	Нет	Не подставлять вымышленное значение
Телефон	Телефон контакта	По сценарию	Нормализовать формат до поиска дубля
Email	Email контакта	По сценарию	Проверить формат, сохранить исходный регистр не требуется
Комментарий	Примечание к сделке	Нет	Передавать без HTML и служебных полей формы
URL страницы	Источник обращения	Да	Сохранять полный адрес страницы отправки
UTM-параметры	Поля аналитики	Если есть	Не заменять последующие значения без согласованного правила атрибуции
ClientID Метрики	Поле аналитики	Если доступен	Получать на сайте и передавать вместе с обращением
ID события	Внешний ID	Да	Использовать для идемпотентности и поиска повторной доставки

Яндекс рекомендует передавать ClientId при создании сделки: идентификатор помогает связать заказ из CRM с визитом на сайте. Для форм его можно получить методом getClientID и записать в скрытое поле до отправки данных в CRM.

Карта полей - часть проектирования всей цифровой системы. Если сайт связан с аналитикой, рекламой и mini-app, полезно заранее проверить как объединить сайт и приложение MAX, чтобы источники и идентификаторы не расходились.

Если требуется сверить формы, воронку и аналитику до разработки, команда ИРС может разобрать задачу и подобрать релевантные кейсы.

Как описать создание контакта, лида и сделки?

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

Не все CRM используют одинаковую модель. Поэтому пишите не только название сущности, но и бизнес-результат. Например: «после отправки формы консультации найти контакт по нормализованному телефону; при совпадении добавить новую сделку в воронку корпоративных сайтов; сохранить комментарий в сделке; назначить ответственного по правилу распределения».

В ТЗ перечислите:

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

API amoCRM, например, разделяет методы работы со сделками, контактами, компаниями и полями. Документация Битрикс24 также выделяет методы CRM и события. Конкретные названия методов разработчик определит после выбора CRM, но ожидаемое поведение должно быть согласовано бизнесом заранее.

Как защититься от дублей и повторной отправки?

Коротко: Поиск дублей и защита от повторного выполнения - разные задачи. Дубль клиента ищут по согласованным контактным данным, а повтор одного события определяют по уникальному ID запроса или заказа. В ТЗ нужны оба правила.

Ситуация	Как распознать	Что делать
Повторная доставка одного события	Совпадает внешний ID события	Вернуть успешный ответ без второй сделки
Повторное обращение клиента	Совпадает нормализованный телефон или email	Создать новую сделку у существующего контакта
Один телефон у нескольких людей	Совпадение не даёт однозначного контакта	Создать задачу на ручную проверку
Повторная оплата заказа	Совпадает ID заказа и уже записан платёж	Не менять сумму, записать событие в журнал

Не ограничивайтесь фразой «исключить дубли». Укажите порядок поиска, нормализацию телефона, отношение к пустому email и решение для общих корпоративных номеров. Иначе разработчик и отдел продаж будут понимать дубль по-разному.

Что должна делать система при ошибке CRM?

Коротко: Заявка не должна исчезать из-за тайм-аута или временной недоступности CRM. ТЗ должно определить локальное сохранение события, повторные попытки, предел повторов, уведомление ответственного и журнал с данными, достаточными для восстановления обмена.

Безопасный сценарий выглядит так:

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

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

Какие требования безопасности включить в ТЗ?

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

Проверьте четыре группы требований:

Формы собирают только данные, необходимые для заявленного сценария.
Пользователь видит информацию об обработке персональных данных и доступ к политике.
Ключи API хранятся на сервере в переменных окружения или хранилище секретов.
Входящие вебхуки проверяются предусмотренным CRM способом, а их адреса не дают лишних полномочий.

Не копируйте рабочий ключ вебхука в ТЗ, переписку или систему задач. В документации Битрикс24 код входящего вебхука является частью URL, поэтому доступ к такому адресу нужно контролировать как доступ к секрету.

Как сформулировать критерии приёмки?

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

Подготовьте минимум следующие проверки:

Новая заявка создаёт нужные сущности и заполняет согласованные поля.
UTM-параметры и ClientId доходят до отдельных полей CRM.
Повтор одного события не создаёт вторую сделку.
Повторное обращение создаёт новую сделку у существующего контакта по согласованному правилу.
Ошибка авторизации CRM попадает в журнал и вызывает уведомление.
Временная ошибка CRM запускает повторную отправку.
Поле с неверным форматом возвращает понятную ошибку и не теряет исходное событие.
Секреты отсутствуют в HTML, JavaScript и сообщениях пользователю.

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

Как передать ТЗ разработчику без пробелов?

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

Структура готового ТЗ:

1. Цель интеграции и измеримый бизнес-результат.
2. Системы, окружения и ответственные стороны.
3. Каталог событий сайта.
4. Таблица полей сайт -> CRM.
5. Правила создания и обновления сущностей.
6. Воронки, этапы, ответственные и задачи.
7. Поиск дублей и уникальные ID событий.
8. Ошибки, повторы, уведомления и журнал.
9. Персональные данные и хранение секретов.
10. Тестовое окружение и критерии приёмки.
11. Порядок запуска и отката.
12. Документация и передача доступов.

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

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

Источники

Коротко: Технические решения в статье опираются на официальную документацию CRM и Яндекс Метрики. Перед реализацией сверяйте методы, права доступа и ограничения с документацией выбранной версии системы.

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