Что должно быть в ТЗ на интеграцию CRM

ТЗ — это не список соединяемых систем

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

Полезное ТЗ связывает три уровня. Бизнес-уровень объясняет, какое действие компании должно стать быстрее или надёжнее. Процессный уровень показывает участников, состояния и исключения. Технический уровень фиксирует сущности, поля, события и правила обмена. Эти уровни нельзя заменить одной большой таблицей полей: одинаковый набор данных может обслуживать совершенно разные процессы.

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

Зафиксируйте границы и сквозные сценарии

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

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

1. 01

   Назвать начало

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

2. 02

   Проследить путь

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

3. 03

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

   Описать созданные или изменённые сущности, ответственного, уведомление и состояние исходной системы.

4. 04

   Добавить исключения

   Проверить дубликат, неполные данные, отсутствие доступа, таймаут и повторную доставку.

Назначьте источник истины для каждой сущности

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

Для каждой сущности определите стабильный внешний идентификатор. Телефон и электронная почта полезны для поиска совпадений, но сами по себе могут меняться, отсутствовать или принадлежать нескольким обращениям. Лучше хранить связь между внутренними идентификаторами систем и отдельно описать правила первичного сопоставления. Если автоматическое решение неоднозначно, ТЗ должно передавать запись на ручную проверку, а не молча объединять клиентов.

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

Принцип проектирования Agentix Labs

Опишите сопоставление полей и преобразования

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

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

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

Согласуйте контракты команд и событий

Интеграция может работать по запросу, расписанию или событиям. В любом варианте ТЗ фиксирует контракт: название операции, инициатора, адрес и метод вызова, схему запроса, схему ответа, коды ошибок, требования к авторизации и версию. Спецификация OpenAPI подходит для описания HTTP-интерфейсов, а AsyncAPI — для событийных каналов, но сам формат документа не заменяет бизнес-смысл полей и состояний.

Для события важно различать факт и команду. «Оплата подтверждена» сообщает о произошедшем и не требует от получателя изменить прошлое. «Создать сделку» просит выполнить действие и может быть отклонено. В ТЗ нужно указать, кто выпускает событие, кто подписывается, какой идентификатор обеспечивает трассировку, допускается ли изменение порядка и как долго сообщение считается актуальным.

Заранее спроектируйте повторы и идемпотентность

Сеть и внешние API иногда отвечают медленно или становятся недоступны. Отсутствие ответа не всегда означает, что операция не выполнена: CRM могла создать сделку, но соединение оборвалось до возврата результата. Если просто повторить запрос, появится дубликат. Поэтому ТЗ должно описывать идемпотентность — способность безопасно обработать повтор одной логической операции без второго бизнес-эффекта.

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

1. 01

   Классифицировать ошибку

   Разделить временную недоступность, ограничение частоты, ошибку данных, отсутствие прав и конфликт состояния.

2. 02

   Повторить безопасно

   Использовать тот же идентификатор операции, ограничить попытки и увеличить паузу между ними.

3. 03

   Проверить итог

   Если ответ потерян, запросить состояние по внешнему идентификатору до создания новой сущности.

4. 04

   Передать человеку

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

Включите безопасность и доступ в основной контракт

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

Проверки выполняются на сервере для каждого объекта, а не только на уровне интерфейса или общего доступа к методу. Это особенно важно для систем с несколькими организациями. В подтверждённом кейсе Crypto Exchange CRM сервер определяет организацию из активного профиля сотрудника, проверяет принадлежность связанных записей и применяет ограничения к API, отчётам и закрытым файлам. Такой подход показывает, почему скрытая кнопка или клиентский фильтр не являются границей безопасности.

• Отдельная техническая учётная запись с минимально необходимыми правами.
• Серверная проверка роли, организации и доступности каждой связанной сущности.
• Шифрование канала и безопасное хранение секретов вне исходного кода.
• Маскирование персональных данных и токенов в журналах и сообщениях об ошибках.
• Ограничение частоты, размера запросов и допустимых операций.
• Журнал доступа и процедура отзыва ключа при инциденте или смене подрядчика.

Скрытый пункт меню не считается защитой: одинаковые правила должны действовать для интерфейса, прямого API, отчётов и файлов.

Подход, реализованный в Crypto Exchange CRM

Сделайте приёмку воспроизводимой

Критерий «данные передаются корректно» невозможно проверить одинаково. Вместо него подготовьте набор сценариев с входными данными и ожидаемым состоянием во всех системах. Приёмка должна охватывать нормальный путь, дубликат, неверные данные, отсутствие прав, таймаут, повтор, восстановление после сбоя и изменение порядка событий. Для каждого теста укажите, где проверить результат и какой журнал объясняет принятое решение.

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

Опишите поддержку и изменение контрактов

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

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

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

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