Я не интегрирую «всё со всем»: сначала решаю, какое обещание клиенту должна сохранить система

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

За словом «интеграция» часто скрывается очень разное. Один заказ должен попасть в учёт. Клиент должен получить честный статус доставки. Склад не должен собрать товар, который уже отменён. Финансы должны увидеть платёж один раз, даже если сообщение пришло повторно. В каждом случае соединяются не системы вообще, а конкретное обязательство.

Данные сами по себе ничего не обещают

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

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

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

У обещания должен быть хозяин

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

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

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

Изменять контракт так, будто старый клиент всё ещё рядом

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

Поэтому изменение полезно сначала проверить на совместимость. Что увидит старый получатель, если появится новое необязательное поле? Будет ли новый статус понятен тому, кто его ещё не знает? Можно ли некоторое время принимать оба варианта и как определить, что старый путь больше не нужен? Это не техническая роскошь, а способ не сломать обещание в день релиза.

Важные изменения стоит вводить поэтапно: сначала научить принимающую сторону терпеть новое поле или версию события, затем начать отправлять его небольшой группе операций, после наблюдения сделать новым стандартом. У каждого этапа нужен признак готовности. «Код развернули» не подходит; лучше «принимающая система обработала новый вариант на реальных данных, а сотрудники знают, где увидеть отклонение».

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

Не обещать мгновенность там, где её нет

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

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

Собираю путь одного события

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

• Кто создаёт исходное событие и на каком основании?
• Какая система считается источником истины для каждого факта?
• Что именно должна сделать принимающая сторона?
• Как отправитель узнает, что обещание выполнено, а не просто сообщение принято?
• Что происходит при повторе, задержке, отмене и ручном исправлении?

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

Разделяю факт, команду и подтверждение

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

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

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

Повтор — не ошибка, а нормальная жизнь

Сеть может прерваться после отправки. Получатель может обработать событие, но не успеть вернуть ответ. Оператор может повторно нажать кнопку. Это не экзотика, а обычный рабочий день.

Поэтому важное обещание должно переживать повтор. У события нужен устойчивый идентификатор, у получателя — понятное правило: второй такой же запрос не создаёт второй заказ и не списывает товар ещё раз. Этот случай подробно разобран в статье о повторной отправке операции. А у команды должно быть место, где видно, что произошло с конкретной операцией от начала до конца.

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

Исключения нужно проектировать раньше демонстрации

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

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

Так интеграция перестаёт быть «чёрным ящиком». Она становится частью процесса, в котором понятны границы ответственности.

Наблюдаемость нужна не только инженерам

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

Это особенно полезно в первые недели после запуска. Вместо спора «у нас всё отправилось» команда разбирает один маршрут: исходное событие, попытка доставки, ответ, повтор, финальный результат. Такой разбор быстро показывает, где проблема в данных, где в правиле, а где в самой связи систем.

Что я считаю готовой интеграцией

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

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

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