Как проектировать интеграции CRM, ERP и внешних API, чтобы система не рассыпалась

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

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

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

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

Внешний сервис может не ответить, вернуть неполные данные или прислать событие позже другого события. Нужны таймаут, повторная попытка, ограничение частоты, журнал и понятный статус «требует проверки».

Для платежей, заказов и списаний обязательна защита от повторной операции. Иначе повторное уведомление превратится в два списания или два заказа.

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

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

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

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

В первой версии закройте один путь от начала до результата: например, заявка → CRM → уведомление менеджеру или заказ → оплата → резерв на складе. После этого добавляйте второстепенные обмены.

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

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

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

Долгие обмены нельзя строить как один блокирующий HTTP-запрос. Используйте очередь, статус операции, correlation ID и безопасный повтор шага. Идемпотентный ключ защищает от дублей, когда внешний сервис принял запись, но ответ потерялся.

Храните результат попытки и причину отказа отдельно от бизнес-объекта. Тогда можно повторить только неудавшийся шаг, не создавая второй заказ, платёж или документ.

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

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

Описание успешного ответа — только половина интеграции. Зафиксируйте коды, формат ошибок, обязательность полей, идемпотентность, лимиты и правила повторной отправки. Клиент и сервер должны одинаково понимать, можно ли безопасно повторить запрос.

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

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

Если системы расходятся, заранее определите источник истины и правила сверки. Нельзя решать конфликт простым «последняя запись победила», когда речь идёт о деньгах, остатках или доступах.

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

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

Опишите для каждого метода обязательные поля, состояния, коды ошибок, идемпотентность и допустимую задержку. Клиенту важно понимать, можно ли безопасно повторить запрос, а поддержке — найти операцию по идентификатору.

Версия контракта должна меняться предсказуемо. Обратная совместимость и период перехода дешевле срочной синхронной правки нескольких систем в день релиза.

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

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