Как правильно спроектировать интеграцию сайта с CRM

Интеграция сайта с CRM — это не один HTTP-запрос после отправки формы. Нужно определить событие, состав данных, источник истины, правила повторов, поведение при недоступности и способ доказать, что конкретная заявка действительно дошла. Без этой схемы обмен работает только в идеальном сценарии.

Начните с карты событий

Перечислите действия, которые должны пересекать границу систем:

• новая заявка;
• изменение контакта;
• создание заказа;
• смена статуса;
• подтверждение оплаты;
• обновление остатка;
• загрузка документа;
• отмена или возврат.

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

Определите источник истины

Если телефон клиента можно редактировать и на сайте, и в CRM, какая версия главнее? Кто владеет статусом заказа? Где создается идентификатор товара? Без ответа системы начинают перезаписывать изменения друг друга.

Для каждого поля или объекта фиксируют:

• основную систему;
• разрешенное направление изменения;
• правило конфликта;
• момент синхронизации;
• ответственного за исправление.

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

Зафиксируйте контракт данных

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

Особое внимание:

• телефоны и адреса;
• временные зоны;
• денежные значения и валюты;
• справочники статусов;
• составные товары;
• файлы и ссылки;
• удаление и архивирование;
• персональные данные.

Добавьте версию контракта. Тогда изменение поля можно выпустить постепенно, не ломая старого потребителя.

Выберите способ обмена

Основные варианты:

• сайт вызывает API CRM;
• CRM забирает данные из API сайта;
• webhook сообщает о событии;
• очередь передает операции через промежуточный слой;
• периодическая синхронизация сверяет состояние.

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

Не блокируйте пользователя внешним сервисом

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

Операция получает состояния: создана, отправляется, доставлена, требует внимания. Так заявку можно повторить и найти по идентификатору.

Если интеграция уже теряет данные, используйте диагностический порядок из статьи о сбое передачи сайта и CRM.

Идемпотентность и защита от дублей

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

Нельзя считать email универсальным уникальным ключом: один адрес может относиться к нескольким обращениям. Лучше использовать идентификатор конкретного события или заказа.

Классифицируйте ошибки

Не все ошибки нужно повторять одинаково.

• таймаут и временная недоступность — повтор с увеличением интервала;
• ограничение частоты — повтор после указанной паузы;
• ошибка авторизации — остановка и уведомление;
• ошибка валидации — исправление данных или контракта;
• конфликт — отдельное правило разрешения;
• неизвестная ошибка — ограниченное число повторов и ручной разбор.

Бесконечный автоматический повтор способен забить очередь и скрыть первопричину.

Логи и наблюдаемость

Для каждой операции сохраняют:

• внутренний идентификатор;
• тип события;
• направление;
• время попыток;
• код результата;
• безопасное описание ошибки;
• номер повтора;
• внешний идентификатор;
• итоговый статус.

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

Безопасность

API-доступ выдается отдельному техническому клиенту с минимальными правами. Секрет хранится вне кода, передача идет по HTTPS, входящие webhooks проверяются подписью или иным подтверждением источника.

Также ограничивают частоту запросов, размер вложений и допустимые поля. В журнал не записывают пароли, токены и платежные данные.

Тестирование интеграции

Нужен не один успешный запрос, а набор сценариев:

1. 1Обычная операция.
2. 2Минимальный набор данных.
3. 3Повтор того же события.
4. 4Временная недоступность.
5. 5Ошибка авторизации.
6. 6Неизвестное значение справочника.
7. 7Большое вложение.
8. 8Изменение объекта с обеих сторон.
9. 9Контрольная сверка количества операций.

Перед production полезен тестовый контур или технические сущности, которые легко отличить от реальных данных.

Документация для поддержки

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

Страница разработки интеграций сайта и CRM описывает коммерческий контур такой работы; материал об устойчивых API и webhooks подробнее разбирает технические механизмы доставки.

Частые вопросы

Нужна ли двусторонняя синхронизация всех данных?

Обычно нет. Она увеличивает число конфликтов. Для каждого объекта выбирают минимально необходимое направление и четкий источник истины.

Можно ли передавать заявку напрямую из браузера?

Не стоит. Так секрет API попадает в клиентский код, а блокировщики и сетевые ошибки делают доставку ненадежной. Браузер отправляет данные серверу сайта, который валидирует и сохраняет операцию.

Как понять, что данные не потерялись?

Нужны журнал исходных событий, статусы очереди, внешний идентификатор и периодическая сверка. Сообщения «запрос отправлен» недостаточно.

Что делать при изменении API CRM?

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