Интеграция сайта с CRM через API: что предусмотреть

Начните с события

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

Согласуйте поля и значения

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

Защититесь от дублей

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

План на ошибку

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

Доступы и персональные данные

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

Проверка перед запуском

Пройдите тестовые сценарии: корректная заявка, неполные данные, повтор, ошибка CRM, восстановление после сбоя. Затем сравните число событий на сайте с числом созданных записей за контрольный период.

Пример карты события

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

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

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

Критерии приёмки

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