Как описать интеграционный контур до начала разработки

Интеграция редко ограничивается формулировкой «сайт нужно связать с 1С». В реальном проекте рядом с сайтом могут находиться ERP, CRM, складская система, платёжные сервисы, службы доставки, телефония, сервис авторизации, маркетинговые инструменты и несколько внутренних баз.

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

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

Начать со списка систем

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

Допустим, компания запускает новый B2B-портал. На первой встрече называются сайт и 1С. При дальнейшем разборе выясняется, что остатки фактически приходят из складской системы, информация о клиентах частично ведётся в CRM, документы хранятся отдельно, а персональные условия рассчитываются ещё одним внутренним сервисом.

Поэтому сначала стоит составить перечень всех систем, которые участвуют в будущем процессе:

• сайт или мобильное приложение;
• 1С, ERP;
• CRM;
• WMS и другие складские системы;
• PIM;
• платёжные сервисы;
• службы доставки;
• сервисы документооборота;
• системы авторизации;
• внутренние базы и сервисы;
• внешние API.

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

Затем определить объекты обмена

Фраза «синхронизировать сайт с ERP» слишком абстрактна для проектирования. Нужно перечислить конкретные сущности:

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

Один объект при этом может состоять из десятков полей и зависеть от других сущностей. Например, товар на сайте — это не только название и артикул, но и варианты, характеристики, изображения, цены, доступность на разных складах и маркетинговое описание. На этом этапе уже становится понятно, что «одна интеграция с 1С» фактически может состоять из нескольких независимых потоков данных.

Для каждого объекта нужен источник истины

Одна из самых важных договорённостей — какая система считается основной для конкретных данных. Например, название товара и артикул приходят из ERP, остатки — из WMS, фотографии и SEO-описания ведутся на сайте. Заказ создаётся в интернет-магазине, но после передачи в ERP именно оттуда возвращается его актуальный статус.

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

Менеджер корректирует цену в ERP, контент-менеджер — на сайте. Какая версия должна остаться после следующего обмена? Если правило не определено заранее, ответ фактически оказывается зашит в программную реализацию и может стать неожиданностью для пользователей.

Для каждой сущности или даже отдельной группы полей стоит указать:

где данные создаются → где изменяются → какая система является источником истины → куда результат передаётся.

Направление обмена тоже нужно зафиксировать

Интеграция не обязательно двусторонняя.

Каталог может передаваться только из ERP на сайт. Заказы — с сайта в ERP. Статусы — обратно из ERP на сайт. Клиентские данные — обновляться в обе стороны по разным правилам. Поэтому простая стрелка «сайт ↔ 1С» скрывает слишком много деталей.

Гораздо полезнее описывать отдельные потоки:

• ERP → сайт: товары, базовые цены;
• WMS → сайт: остатки;
• сайт → ERP: новые заказы;
• ERP → сайт: статусы заказов, документы;
• CRM → сайт: данные закреплённого менеджера.

Такая схема сразу показывает количество независимых процессов и помогает оценивать их отдельно.

Нужно описать не только данные, но и события

Следующий вопрос — когда происходит обмен.

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

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

Поэтому для каждого потока стоит определить триггер:

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

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

Объём и частота меняют архитектуру

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

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

Эти показатели влияют на способ интеграции.

Где-то достаточно периодического пакетного обмена. Где-то потребуется API. При большом количестве событий могут понадобиться очереди. Для разных потоков одного проекта могут использоваться разные механизмы. Выбирать технологию до понимания объёмов — значит проектировать интеграцию на предположениях.

Отдельно нужно разобрать идентификаторы

Один и тот же клиент в разных системах может иметь разные идентификаторы. То же происходит с товарами, заказами, складами, договорами и другими объектами. Например, на сайте есть внутренний ID товара, в ERP — код номенклатуры, а в PIM — собственный идентификатор. Нужно понимать, по какому признаку системы определяют, что речь идёт об одном объекте.

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

Справочники требуют тех же договорённостей

Проблемы возникают не только с основными объектами.

Статус "Отгружен" в одной системе может называться "Передан в доставку" в другой. Способ оплаты может храниться кодом 03, а на сайте отображаться как «Безналичный расчёт». Один склад может иметь разные названия в ERP и интернет-магазине.

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

• какие значения существуют;
• как они сопоставляются;
• кто управляет справочником;
• что делать при появлении нового значения.

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

Успешный сценарий — только половина интеграции

Обычно бизнес-процесс описывают так:

Клиент оформляет заказ → заказ передаётся в ERP → менеджер начинает работу.

Но что происходит, если ERP недоступна?

Сайт должен показать ошибку покупателю? Сохранить заказ и отправить позже? Сколько раз повторить попытку? Как сотрудник узнает, что передача не состоялась?

Такие ситуации стоит разобрать до разработки для каждого критичного потока:

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

Интеграционный контур должен описывать не только маршрут данных, но и поведение при нарушении этого маршрута.

Особенно важно определить правила повторной обработки

Представим, что сайт отправил заказ в ERP, но из-за сетевого сбоя не получил подтверждение. Неизвестно, создан заказ или нет.

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

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

Нужно определить, кто имеет доступ к данным

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

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

Поэтому ещё до разработки стоит определить:

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

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

Данные нужно проверять на границе систем

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

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

Должно быть понятно, как контролировать обмен

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

Поэтому ещё при описании контура стоит определить для критичных потоков:

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

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

Схемы недостаточно — нужна таблица потоков

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

1. Схема интеграционного контура: системы и основные направления обмена.
2. Реестр интеграционных потоков, где каждый поток описан отдельно

Откуда → куда	Что передаём	Источник истины	Когда	Критичность
ERP → сайт	Товары и базовые цены	ERP	По расписанию	Средняя
WMS → сайт	Остатки	WMS	Каждые несколько минут	Высокая
Сайт → ERP	Заказы	Сайт при создании	Сразу	Критическая
ERP → сайт	Статусы заказов	ERP	При изменении	Высокая
ERP → сайт	Закрывающие документы	ERP	После формирования	Средняя

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

Не обязательно заранее знать все технические детали

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

Гораздо важнее до разработки ответить на вопросы:

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

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

Интеграционный контур помогает точнее оценить проект

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

Одновременно становится точнее оценка проекта. Формулировка «интеграция с ERP» может скрывать два простых потока или несколько десятков сценариев с персональными ценами, договорами, документами, складами и двусторонним обменом. Пока это неизвестно, любая оценка разработки содержит большую долю предположений.

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