-
Источники
Формы, чат и заказы
-
Правила
Поля, владелец и идентификаторы
-
Отказы
Очередь, повторы и уведомления
-
Приёмка
Сценарии с ожидаемым результатом
ТЗ на интеграцию сайта с CRM должно описывать не только успешную передачу заявки, но и повторы, ошибки, права сотрудников и критерии приёмки. Формулировка «подключить Битрикс24» не определяет, какие сущности создавать, как искать дубли и что делать при недоступности API.
Начните с границ проекта
Перечислите источники: обычная форма, заявка из карточки, калькулятор, чат, заказ магазина. Укажите, переносится ли история или подключаются только новые обращения. Для каждого сценария определите конечный результат: контакт и сделка, лид, задача или диалог открытой линии.
Впишите портал, воронку, этап и ответственного в закрытую часть документа. Ключи и пароли в ТЗ не помещают: их передают через согласованное хранилище секретов. Доступ интеграции ограничивают необходимыми операциями; публичный JavaScript не должен содержать вебхук с правами CRM.
Опишите карту полей
| Источник | Назначение | Проверка | Если значение отсутствует |
|---|---|---|---|
| Телефон формы | Телефон контакта | Строка, формат и допустимая длина | Ошибка для формы, где телефон обязателен |
| Email контакта | Формат и длина | Не создавать вымышленный адрес | |
| Выбранный товар | Комментарий или товарная позиция | ID и вариант из каталога | Сохранить обращение без придуманного товара |
| UTM и URL | Источник обращения | Разрешённые поля, ограничение длины | Отметить источник как неизвестный |
| ID сайта | Внешний идентификатор CRM | Уникальность и стабильность при повторах | Не отправлять до присвоения ID |
Разделите исходное значение и нормализованное. Это помогает найти ошибку преобразования телефона, но не даёт права бессрочно хранить всё введённое. Сроки, состав хранения и доступ к персональным данным согласуют с ответственным за их обработку.
Зафиксируйте правила дублей
Дубль доставки и повторное обращение клиента — разные ситуации. Повтор запроса после тайм-аута должен ссылаться на прежнюю заявку. Новое сообщение того же человека через неделю может создавать новую сделку. Не объединяйте их только по номеру телефона.
Опишите порядок поиска контакта, действия при нескольких совпадениях и обновление полей. Если телефон совпал, а email отличается, интеграция не должна молча перезаписывать контакт без согласованного правила. Для общих корпоративных номеров и адресов предусмотрите ручную проверку.
Доставка, ошибки и восстановление
Заявка сначала сохраняется на сайте. Для CRM и почты создаются независимые задания. В ТЗ укажите тайм-аут, повторяемые категории ошибок, интервалы, предельный возраст задания и уведомление при остановке. Возврат HTTP 200 с телом ошибки API тоже должен считаться неуспехом.
Если результат создания неизвестен, перед повтором проверяйте внешний ID. Это защищает от ситуации, когда CRM создала сделку, а ответ потерялся. Подробнее схема разобрана в статье доставка заявок в Битрикс24 и на почту.
Для чата добавьте входящие и исходящие сообщения, подтверждение доставки, привязку к сессии посетителя, доступ менеджеров и поведение после окончания рабочего времени. Отдельно проверьте восстановление диалога и защиту от чтения чужой переписки.
Критерии приёмки
- Каждый утверждённый источник создаёт нужную сущность в нужной воронке.
- Все обязательные поля заполнены из фактических данных, телефон не разбит и не превращён в число.
- Повтор одного задания не создаёт дубль.
- Ошибка CRM не блокирует письмо, ошибка почты не блокирует CRM.
- Задание переживает перезапуск и доставляется после восстановления доступа.
- Некорректный ввод возвращает понятную ошибку до подтверждения успеха.
- Обычный менеджер видит сделку и может открыть разрешённый диалог.
- Секреты не присутствуют в HTML, JavaScript, клиентских ответах и открытых логах.
Для каждого теста запишите ожидаемый результат, фактический результат, дату и ссылку на закрытое доказательство. «У нас отправилось» не заменяет проверку отказов. При сдаче передайте инструкцию: где смотреть очередь, кто получает ошибку, как заменить доступ и как безопасно повторить доставку.
Что влияет на смету
Стоимость зависит от числа источников и сущностей, двустороннего обмена, правил дублей, чата, товарного состава и требований к восстановлению. Наличие готового модуля может сократить часть разработки, но не отменяет настройку и приёмку. До оценки пришлите список форм, текущую CRM, пример полей без персональных данных и желаемую схему обработки.
Посмотрите реализацию на сайте ISKAR и проверку двустороннего чата. Эти примеры помогут сформулировать требования предметно.
Как описать ошибку так, чтобы её можно было проверить
Фраза «интеграция должна работать стабильно» не задаёт критерий приёмки. Замените её сценарием: при временной недоступности CRM сайт сохраняет обращение, показывает посетителю подтверждение приёма и создаёт задачу повторной доставки. После восстановления связи заявка появляется в согласованной воронке без повторного создания уже существующей записи. В ТЗ указывают интервал повторов, предельное число попыток и способ уведомления ответственного.
Для каждого поля запишите тип и правила преобразования. Телефон — строка, сумма — число с согласованной валютой и точностью, время — значение с определённым часовым поясом. Отдельно задайте поведение пустого поля: сохранить прежнее значение, очистить его или отклонить операцию. Без такого правила очередное обновление может удалить вручную уточнённые менеджером данные.
Разделите источник истины для каждого объекта. Например, сайт создаёт обращение, а CRM определяет его коммерческий статус. Если обе системы могут независимо менять один статус, нужен порядок разрешения конфликта. Направление стрелки на схеме обмена не заменяет описание этих правил и не объясняет, чьё изменение останется последним.
Учебная строка приёмочного протокола
Сценарий: покупатель дважды нажал отправку на медленном соединении. Вход: одна форма, один идентификатор операции, одинаковые контактные данные. Ожидание: одно сохранённое обращение и одна согласованная CRM-сущность; интерфейс не предлагает повторить уже принятую заявку. Доказательства: идентификатор обращения, запись доставки и ссылка на тестовую сущность. Одинаковый телефон без идентификатора операции этого поведения не обеспечивает.
Рядом запишите противоположный сценарий: тот же покупатель сознательно оставляет вторую заявку на другую услугу. Она не должна исчезать из-за слишком грубого объединения по номеру. Эти два теста вместе помогают проверить границу между техническим повтором и новым коммерческим обращением. Используйте вымышленные данные в тестовом контуре или заранее согласованные контакты.
В передаваемые материалы включите карту полей, описание очереди, журнал ошибок, способ проверки доступности интеграции и инструкцию смены ключей. Укажите владельца учётной записи приложения и порядок отзыва доступа. После запуска команда должна понимать, где искать причину сбоя и кто принимает решение о повторе. Документация считается полезной, когда другой специалист может выполнить контрольный сценарий без догадок о внутренней логике проекта.
