За три года интеграций с CRM я могу по пальцам пересчитать проекты, где заказчик приходил с готовым ТЗ на интеграцию с CRM и мы ни разу не возвращались к архитектуре в середине разработки. Обычно всё наоборот: бриф на полстраницы, формулировка «синхронизируйте заказы с Битриксом», а через две недели выясняется, что нужен ещё обмен статусами оплаты, уведомления менеджеру в Telegram и отдельная логика для отмен. Ниже - список того, что я всегда прошу описать заранее, чтобы не переписывать интеграцию во второй раз.
Что должно быть на входе в ТЗ на интеграцию с CRM
Прежде чем расписывать сценарии и поля, нужно зафиксировать матчасть - без неё документ превращается в благие пожелания. Я всегда фиксирую пять вещей.
- Какая именно CRM: Bitrix24, amoCRM, retailCRM, самописная система на Laravel - у каждой свой API, свои лимиты запросов и своя логика вебхуков. Я обычно прошу ссылку на документацию API ещё до оценки, потому что от неё зависит, сколько времени займёт разбор.
- Откуда идут данные: форма на Tilda, корзина WooCommerce, Telegram-бот на aiogram, личный кабинет клиента.
- Кто выдаёт доступы: токен CRM, реквизиты для эквайринга T‑Bank, доступ к личному кабинету СДЭК для работы с доставкой.
- Формат обмена: REST API, вебхуки в реальном времени или выгрузка по расписанию - от этого зависит, нужен ли постоянно работающий обработчик на сервере.
- Лимиты: сколько запросов в минуту разрешает CRM и есть ли отдельная очередь для массовой загрузки контактов. Это особенно критично, если вместе с интеграцией переносите в CRM историческую базу клиентов одним пакетом.
На практике часто беру интернет-магазин на WooCommerce с эквайрингом T‑Bank: заказ создаётся на сайте, оплата проходит через T‑Bank, и оба события - создание заказа и подтверждение оплаты - должны долетать до CRM отдельными шагами, а не одним общим вызовом. Если это не прописать заранее, разработчик соберёт один хук на создание заказа, а потом окажется, что менеджер видит в CRM «оплачено» ещё до реального поступления денег.
Карта данных: сущности и поля, которые едут между системами
Дальше составляю таблицу соответствия полей. Она нужна не для красоты - именно на ней спотыкаются на приёмке, когда выясняется, что в CRM нет поля под трек-номер или скидка потерялась при переносе заказа. Обычно такая таблица занимает от 15 до 30 строк для типового интернет-магазина - в зависимости от того, сколько статусов заказа и способов доставки используется.
| Сущность | Источник | Куда попадает в CRM | Что важно уточнить |
|---|---|---|---|
| Контакт | Форма на сайте, Telegram-бот | Карточка контакта | Как сопоставлять дубли по телефону или email |
| Заказ | WooCommerce, Tilda | Сделка | Переносим ли скидки и промокоды или только позиции и сумму |
| Оплата | Вебхук T‑Bank | Поле статуса оплаты в сделке | Как отмечать частичную оплату и возвраты |
| Доставка | Личный кабинет СДЭК | Поле трек-номера и статуса | Опрашивать статус по расписанию или ждать вебхук от СДЭК |
Для каждой строки указываю тип поля (текст, число, дата, список значений) и что делать, если поле в CRM обязательное, а на сайте его можно не заполнять - например, отчество в форме заказа. Это мелочь, но именно из-за таких мелочей интеграция падает с ошибкой валидации через месяц после запуска, когда придёт заказ без привычных данных.
Бесплатный материал
🎁 Полезный скрипт в подарок
Подпишитесь на Telegram - пришлю готовый скрипт по этой теме.
Без спама. Отписка в 1 клик.
Направление синхронизации и что делать с конфликтами
Здесь чаще всего рождаются переделки, потому что стороны по умолчанию считают очевидным то, что таковым не является.
Кто источник истины
Для каждого поля нужно решить, кто главный: сайт или CRM. Цена и состав заказа обычно живут на сайте, а статус сделки после первого касания - уже в CRM, потому что менеджер двигает воронку руками. Если синхронизация двусторонняя, опишите, что происходит при конфликте: например, менеджер поменял телефон клиента в CRM, а клиент через час обновил профиль на сайте с другим номером. Без явного правила («последнее изменение побеждает» или «сайт всегда главный для контактных данных») разработчик выберет вариант сам, и не факт, что он совпадёт с вашими ожиданиями.Если интеграция не разовая, а нужно гибко перекладывать данные между несколькими системами - сайтом, CRM, ботом на aiogram, СДЭК - я часто беру для этого автоматизацию процессов в n8n: он берёт на себя маршрутизацию вебхуков и повторные попытки при сбоях, и в ТЗ достаточно описать сами узлы сценария и условия перехода между ними, а не писать HTTP-клиент с нуля под каждую систему.
Сценарии и события: пошаговое описание процессов
Это самая объёмная часть документа, и именно её обычно урезают до одной строчки «синхронизация заказов». На деле сценариев минимум шесть, и у каждого свой триггер и свой ожидаемый результат.
- Новый заказ создан. Триггер - оформление заказа на сайте. Действие - создать сделку в CRM с товарами, суммой и контактом, привязать к воронке «Новые заказы».
- Оплата прошла. Триггер - вебхук от T‑Bank со статусом успешной оплаты. Действие - обновить поле статуса оплаты в сделке, не создавая вторую сделку.
- Оплата не прошла или отменена. Триггер - вебхук с отказом. Действие - перевести сделку в отдельный статус, чтобы менеджер видел брошенный заказ и мог связаться с клиентом.
- Заказ отменён клиентом. Триггер - отмена в личном кабинете или по звонку. Действие - синхронизировать статус в обе стороны, если отмену можно инициировать и из CRM.
- Статус доставки изменился. Триггер - обновление статуса в личном кабинете СДЭК. Действие - обновить поле в сделке и, если настроено, отправить клиенту уведомление через Telegram-бота.
- Менеджер вручную поменял статус в CRM. Триггер - действие человека. Действие - решить, нужно ли отражать это обратно на сайте, например показать клиенту «заказ в обработке» в личном кабинете.
Для каждого сценария в ТЗ пишу не абзац прозы, а три строки: что произошло, что должна сделать система, что увидит пользователь или менеджер. Это резко сокращает количество вопросов на этапе разработки.
Ошибки, повторы и что делать при сбое интеграции
CRM время от времени отдаёт 500‑ю ошибку или медленно отвечает под нагрузкой, платёжный вебхук может прийти дважды, а СДЭК - прислать один и тот же статус несколько раз подряд. Если это не заложено в ТЗ, интеграция в проде создаёт дубли сделок или теряет события молча.Что обязательно описываю:
- Идемпотентность: по какому ключу (номер заказа, id платежа) система понимает, что событие уже обработано, и не создаёт вторую сделку при повторном вебхуке.
- Повторные попытки: сколько раз и с какой паузой система пытается отправить запрос в CRM, если та недоступна.
- Логирование: куда пишутся неудачные попытки, чтобы можно было руками довести проблемный заказ до CRM, а не искать его в логах сервера.
- Оповещение: кто узнаёт, что интеграция легла - только разработчик по логам или ещё и менеджер, если заказы перестали появляться в CRM больше часа.
На одном проекте с Tilda и amoCRM у меня как раз вышло так: вебхук от Робокассы иногда дублировался при нестабильном соединении на стороне платёжной системы, и без проверки по id платежа в CRM улетало по две сделки на один заказ. После добавления идемпотентности проблема ушла полностью.
Кто сопровождает интеграцию после запуска
Отдельный пункт, который часто забывают - что происходит после сдачи проекта. CRM обновляет API, в личном кабинете СДЭК меняются поля, T‑Bank меняет формат вебхука, и если в ТЗ не прописано, кто следит за такими изменениями, интеграция через полгода начинает молча терять заказы. Фиксирую отдельно:
- Кто мониторит логи ошибок и как часто - раз в день, раз в неделю или только по жалобе клиента.
- Куда идут алерты о падении интеграции - на почту разработчика, в чат руководителя или в отдельный канал.
- Что входит в разовую разработку, а что - в постоянное сопровождение: у меня настройка интеграции - отдельная работа, а регулярный мониторинг и правки под изменения на стороне CRM или платёжной системы - уже техподдержка от 15 000 ₽ в месяц.
- Кто становится ответственным за сценарий в n8n или скрипт на сервере, если через год понадобится добавить новое поле.
Тестовые случаи и критерии приёмки
ТЗ без критериев приёмки - это пожелание, а не техническое задание: непонятно, в какой момент интеграция считается готовой. Я формирую список тестовых случаев отдельно от сценариев, потому что тесты специально бьют по граничным ситуациям.
| Тест-кейс | Что проверяем | Ожидаемый результат |
|---|---|---|
| Повторный вебхук оплаты | Идемпотентность по id платежа | Сделка обновляется, вторая не создаётся |
| CRM недоступна во время заказа | Логика повторных попыток | Заказ уходит в очередь и долетает после восстановления связи |
| Заказ без email | Обработка необязательных полей | Сделка создаётся, поле остаётся пустым, ошибки нет |
| Частичный возврат оплаты | Отдельный статус для частичного возврата | Статус в CRM отличается от полного возврата |
| Ручное изменение статуса в CRM | Влияние на сайт | Личный кабинет клиента показывает актуальный статус либо явно не меняется, если так решено в ТЗ |
Перед сдачей прогоняю все кейсы на реальных, но тестовых заказах - не на моках, потому что именно на реальных вебхуках от T‑Bank или СДЭК вылезают форматы данных, которых нет в документации API. Обычно это 10-15 тестовых заказов, покрывающих все сценарии из ТЗ.
Форматы вебхуков T‑Bank и СДЭК меняются чаще документации, поэтому перед запуском я проверяю их на реальных данных.
Частые вопросы
Сколько стоит написать ТЗ на интеграцию с CRM?
Обычно я включаю разработку ТЗ в стоимость самой интеграции. Комплексная доработка Tilda с подключением CRM, эквайринга и СДЭК начинается от 40 000 ₽, а если нужен только сам документ и консультация по архитектуре - от 3 000 ₽. В итоговый документ обычно попадает 15-20 страниц: список полей, сценарии, обработка ошибок и критерии приёмки.
Нужно ли отдельное ТЗ, если CRM подключаем через готовый плагин или виджет?
Готовый коннектор снимает часть работы по авторизации и базовой отправке заказа, но карту полей, направление синхронизации и обработку конфликтов всё равно нужно описать - плагин обычно решает только базовый сценарий «заказ создан», а отмены, частичные оплаты и статусы доставки остаются на вашей стороне.
Кто должен писать техническое задание на CRM-интеграцию - заказчик или разработчик?
На практике это совместная работа. Заказчик знает бизнес-процесс и особенности CRM изнутри - какие поля обязательны, как построена воронка. Разработчик переводит это в конкретные триггеры, поля и обработку ошибок. Я обычно провожу отдельную встречу на час-полтора, чтобы вместе пройтись по сценариям и не упустить нетипичные случаи вроде оптовых заказов или заявок из чата. Если ТЗ пишет только одна сторона, вторая половина информации всплывает уже на тестировании.
Что делать, если требования меняются в процессе разработки?
Меняются почти всегда - появляется новый статус в CRM или заказчик решает добавить уведомления в Telegram уже после старта. Я веду список изменений отдельным списком поверх исходного ТЗ и на его основе пересчитываю сроки и стоимость доработки, а не переписываю документ с нуля.