Интеграция ломается после релиза: как следить за контрактом API

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

Ответ приходит с кодом 200, JSON валиден, CI зелёный.

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

Ошибки в логах при этом нет: интеграция принимает испорченные данные как корректные и раскладывает их по справочникам.

Чем позже их найдут, тем дороже откат.

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

Контракт - формальное описание того, что потребитель ждёт от API:

• какие поля приходят
• какого они типа
• какие обязательны
• какие значения
• коды ошибок допустимы

Обычно его пишут в OpenAPI или JSON Schema и хранят в репозитории рядом с кодом интеграции.

Контрактный тест сверяет с этим документом ответ поставщика из песочницы.

Поставщик видит, чью интеграцию сломает его изменение, ещё до выкатки.

Бюллетень n8n напоминает, что уязвимости находят и в самих инструментах, на которых построены интеграции. В выпуске от 1 октября четыре уязвимости уровня High: - SQL-инъекция в узле Microsoft SQL.

Выражение `{{ }}` с пользовательскими данными подставлялось прямо в текст запроса.

Если в поле формы попадал фрагмент SQL, база выполняла его как команду.

Защита - параметризованные запросы, где данные передаются отдельно от текста SQL. - Проверка учётных данных в общих workflow не учитывала вложенные и inline-подпроцессы.

Бюллетень выходит раз в две недели, значит за полгода их набирается около 13. У платформы должен быть владелец: он читает бюллетень, прогоняет патч на стенде вместе с контрактными тестами и выкатывает его в согласованное окно.

Без владельца self-hosted инсталляция за те же полгода пропускает эти 13 выпусков, включая исправления уровня High.

В KT.Team интеграционный слой выбирают по нагрузке и цене ошибки. Обмен 1С с маркетплейсами и PIM (Pimcore, Akeneo) строим на Datareon или Apache Kafka. Тяжёлый enterprise-контур - на MuleSoft или Talend ESB. Быстрые сценарии автоматизации - на n8n. Инженерные правила для всех вариантов одни:

Контракт каждого внешнего API лежит в репозитории и проверяется в CI.

На входе в шину стоит валидатор; сообщение, не совпавшее со схемой, уходит в карантин.

У каждой интеграции есть владелец и дашборд с долей отклонённых сообщений.

Запросы к базам только параметризованные, без подстановки выражений в текст SQL. В AI-native integration рутину выполняет модель. Она читает changelog поставщика и diff его OpenAPI-спецификации, предлагает правку контракта и тест под неё. Инженер проверяет предложение и мёржит. Когда AI-агенты сами обращаются к внешним API, их запросы проходят через LLM & Security Gateway. Там действуют те же контракты, лимиты и журнал вызовов, поэтому агент не отправит в учётную систему данные, не прошедшие схему.