Интеграционная API-архитектура: как связать корпоративные системы

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

Главная цель — не «соединить всё со всем», а сделать изменения локальными. Замена CRM, SMS-провайдера или формата партнёра не должна требовать правок в десятках приложений.

Начните с границ и владельцев

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

Зафиксируйте:

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

Не проектируйте единый «универсальный объект клиента» со всеми полями компании. Контракт должен содержать минимум, нужный конкретному сценарию.

Синхронный запрос или асинхронное событие

Модель	Используйте, когда	Основной риск
Синхронный API	Ответ нужен для продолжения операции	Каскадный отказ и рост задержки
Команда через очередь	Работу можно выполнить позже	Неочевидный конечный результат
Событие	Нужно сообщить о состоявшемся факте	Несовместимые потребители и повторная доставка
Пакетный обмен	Допустима большая задержка и важен объём	Сложная сверка и повтор части пакета

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

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

Контракт API как продукт

Контракт должен позволять потребителю интегрироваться без чтения исходного кода. OpenAPI Specification задаёт машиночитаемое описание HTTP API и поддерживает документацию, генерацию клиентов и тестирование.

В контракт включите:

• назначение операции и владельца;
• схемы запросов и ответов;
• обязательность, формат и ограничения полей;
• аутентификацию и авторизацию;
• коды успеха и ошибок;
• ограничения скорости;
• idempotency key и correlation ID;
• правила пагинации и фильтрации;
• политику версий и прекращения поддержки.

HTTP-метод и код ответа должны сохранять общепринятую семантику. Для машиночитаемых ошибок можно применять RFC 9457: стабильный тип проблемы, статус, понятное описание и идентификатор экземпляра.

Идемпотентность и повторная доставка

В распределённой системе «ровно один раз» обычно достигается не транспортом, а сочетанием at-least-once доставки и идемпотентной обработки.

Для изменяющей операции:

1. клиент генерирует ключ до первого запроса;
2. сервер атомарно сохраняет ключ и результат;
3. повтор с тем же ключом возвращает тот же результат;
4. тот же ключ с другим содержанием отклоняется;
5. срок хранения ключа покрывает окно повторов.

Для событий храните ID обработанных сообщений или используйте уникальное бизнес-ограничение. Обработчик должен безопасно переживать дубль после перезапуска.

Эти правила особенно важны для внешних каналов, где повтор может создать второе сообщение; пример есть в сравнении SMPP и HTTP API.

Transactional outbox вместо двойной записи

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

Паттерн transactional outbox записывает бизнес-изменение и событие в одной транзакции. Отдельный publisher читает outbox и отправляет событие в брокер. Публикация может повториться, поэтому потребители всё равно должны быть идемпотентными.

Для входящего события полезен inbox или журнал обработки. Он упрощает дедупликацию, аудит и повтор после исправления ошибки.

Адаптеры защищают домен

Внешняя система может использовать нестабильные поля, SOAP, CSV, SMPP или собственные статусы. Адаптер переводит внешний контракт во внутренний и не даёт этим деталям распространиться по доменной логике.

Хороший адаптер отвечает за:

• аутентификацию и ротацию ключей;
• маппинг схем и статусов;
• таймауты, retry и circuit breaker;
• ограничение скорости;
• корреляцию и безопасные логи;
• метрики зависимости;
• тестовую заглушку.

Готовые сценарии для корпоративных систем показаны в руководстве по интеграции SMS с 1С и Битрикс24.

Версионирование без вечных v1 и v2

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

Процесс изменения:

1. публикуется предложение и impact analysis;
2. запускаются contract tests;
3. потребители получают срок миграции;
4. использование старой версии измеряется;
5. отключение выполняется после подтверждения.

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

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

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

Минимальный набор:

• TLS и проверка сертификата;
• отдельная identity для сервиса;
• scopes или роли;
• короткий срок и ротация секретов;
• rate limit и защита от слишком больших запросов;
• валидация схемы;
• журнал административных и чувствительных операций;
• маскирование персональных данных;
• процедура быстрого отзыва.

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

Наблюдаемость интеграций

Передавайте correlation ID через HTTP, сообщения и фоновые задачи. Измеряйте:

• rate, errors, duration по операции;
• возраст очереди и число повторов;
• долю permanent failures;
• задержку от события до бизнес-результата;
• ошибки по внешней зависимости;
• использование версий API;
• число сообщений в dead-letter queue.

Логируйте решение, а не секрет: какой контракт, версия, ID и тип ошибки. Практика связывания метрик, логов и traces описана в статье о наблюдаемости инфраструктуры.

Чек-лист архитектурного review

• Для ключевых данных известна система записи.
• У каждого контракта есть владелец и потребители.
• Выбор sync/async обоснован требованием к задержке.
• Таймауты короче пользовательского бюджета времени.
• Retry ограничен и безопасен от дублей.
• Есть outbox для критичной публикации событий.
• Ошибки машиночитаемы и не раскрывают внутренние детали.
• Схемы проходят contract tests.
• Секреты разделены по средам и ротируются.
• Очередь и DLQ имеют владельца и runbook.
• Прекращение поддержки версии измеряется.

CTA: «Лоджик Телеком» может помочь описать интеграционные контракты, адаптеры и поток событий. Начните с одного критичного процесса: определите систему записи, бюджет задержки и поведение при недоступности каждой зависимости.